Skip to content

Commit 2902f12

Browse files
s-stumbos-stumbo
authored
Add cache clearing info to JS Build config docs (#3297)
[ ] Check if this is a typo or other quick fix and ignore the rest :) ## Type of change Update to JS build config docs ### What should this PR do? Adds info about clearing the caches, from Angela's draft: https://docs.google.com/document/d/13kMq9F1mUooOoLsIXN_EuAs51J8TLshw4D0-uZTK7p0/edit?tab=t.0#heading=h.pqhjvgw1gl4l ### Why are we making this change? Reduce friction in the user experience ### What are the acceptance criteria? Content should be clear and accurate and appear in expected location ### How should this PR be tested? Review deploy preview --------- Signed-off-by: s-stumbo <sally.stumbo@chainguard.dev>
1 parent 8c9ba04 commit 2902f12

1 file changed

Lines changed: 192 additions & 15 deletions

File tree

‎content/chainguard/libraries/javascript/build-configuration.md‎

Lines changed: 192 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ used for managing JavaScript dependencies and scripts. It allows developers to
106106
install, share, and manage packages for their projects. For more details, see
107107
the [npm documentation](https://docs.npmjs.com/).
108108

109+
**Declare dependencies in package.json**
110+
109111
With npm, you declare JavaScript package dependencies in a `package.json` file
110112
and separated into development and runtime dependencies. The following snippet
111113
shows a minimal example with a couple of dependencies each:
@@ -146,7 +148,18 @@ therefore an update to the lock file. The lock file also encodes the checksum
146148
values in the `integrity` field and the download URL in the `resolved` field for
147149
each module.
148150

151+
**Direct access: Point registry to Chainguard**
152+
153+
To change a project to use Chainguard Libraries for JavaScript, set the registry
154+
URL to point to Chainguard in your user `.npmrc` file:
155+
156+
```bash
157+
npm config set registry https://libraries.cgr.dev/javascript/
158+
```
159+
160+
149161
### Using a repository manager
162+
150163
To change a project to use Chainguard Libraries for JavaScript, set the registry
151164
URL to point to your repository manager in your user `.npmrc` file:
152165

@@ -167,13 +180,38 @@ configuring authentication.
167180

168181
Example URLs:
169182

170-
* JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all/
171-
* Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
172-
* Direct access: https://libraries.cgr.dev/javascript/
183+
* JFrog Artifactory: `https://example.jfrog.io/artifactory/javascript-all/`
184+
* Sonatype Nexus: `https://repo.example.com:8443/repository/javascript-all/`
185+
* Direct access: `https://libraries.cgr.dev/javascript/`
186+
187+
### Apply registry changes
173188

174189
To apply the registry changes, remove the `node_modules` directory and the
175190
`package-lock.json` file and run the `npm install` command again. This re-fetches all
176-
packages from Chainguard and regenerates the lockfile with updated hashes.
191+
packages from Chainguard and regenerates the lockfile with updated hashes:
192+
193+
```bash
194+
rm -rf node_modules package-lock.json
195+
npm install
196+
```
197+
198+
As an alternative to deleting the lock file, you can [run `chainctl libraries update-hashes`](#update-lockfile-hashes) to update hashes in place.
199+
200+
**Clear caches**
201+
202+
If you encounter stale or corrupted package data, clear the cache with:
203+
204+
```bash
205+
npm cache clean --force
206+
```
207+
208+
To verify the cache is empty:
209+
210+
```bash
211+
npm cache verify
212+
```
213+
214+
### Update lockfile hashes
177215

178216
If you are migrating an existing project and want to preserve your current
179217
lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
@@ -323,6 +361,8 @@ other desired packages for further testing.
323361
JavaScript, designed as an alternative to npm and Yarn. For
324362
more information, see the [pnpm documentation](https://pnpm.io/motivation).
325363

364+
**Declare dependencies in package.json**
365+
326366
With pnpm, you declare JavaScript package dependencies in a `package.json` file
327367
and separated into development and runtime dependencies. The following snippet
328368
shows a minimal example with a couple of dependencies each:
@@ -362,6 +402,15 @@ Any dependency or dependency version changes require another install and
362402
therefore an update to the lock file. The lock file also encodes the checksum
363403
values in the `integrity` field and other information for each module.
364404

405+
**Direct access: Point registry to Chainguard**
406+
407+
To change a project to use Chainguard Libraries for JavaScript, set the registry
408+
URL to point to Chainguard in your user `.npmrc` file:
409+
410+
```bash
411+
pnpm config set registry https://libraries.cgr.dev/javascript/
412+
```
413+
365414
### Using a repository manager
366415

367416
To change a project to use Chainguard Libraries for JavaScript, set the registry
@@ -384,14 +433,72 @@ configuring authentication.
384433

385434
Example URLs:
386435

387-
* JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all/
388-
* Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
389-
* Direct access: https://libraries.cgr.dev/javascript/
436+
* JFrog Artifactory: `https://example.jfrog.io/artifactory/javascript-all/`
437+
* Sonatype Nexus: `https://repo.example.com:8443/repository/javascript-all/`
438+
* Direct access: `https://libraries.cgr.dev/javascript/`
439+
440+
### Apply registry changes
390441

391442
To apply the registry change, remove the `node_modules` directory and the
392443
`pnpm-lock.yaml` file and run the `pnpm install` command again. This re-fetches all
393444
packages from Chainguard and regenerates the lockfile with updated hashes.
394445

446+
```bash
447+
rm -rf node_modules pnpm-lock.yaml
448+
pnpm install
449+
```
450+
451+
As an alternative to deleting the lock file, you can [run `chainctl libraries update-hashes`](#update-lockfile-hashes-1) to update hashes in place.
452+
453+
454+
**Clear pnpmn caches**
455+
456+
pnpm has three separate layers of cached data. If you encounter stale or corrupted package data, you can clear all of these caches:
457+
458+
{{< details "Clear pnpm caches" >}}
459+
460+
**Metadata (packuments)**
461+
462+
There is an [experimental command](https://pnpm.io/cli/cache-delete) to delete the metadata cache:
463+
464+
```bash
465+
pnpm cache delete
466+
```
467+
468+
**HTTP cache**
469+
470+
pnpm maintains a separate HTTP cache at `~/.cache/pnpm` (or `$XDG_CACHE_HOME/pnpm` if that variable is set). Delete it with:
471+
472+
```bash
473+
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pnpm"
474+
```
475+
476+
**Content-addressable store (tarballs)**
477+
478+
To find and manually remove the full store:
479+
480+
```bash
481+
pnpm store path
482+
```
483+
484+
Then delete the directory that command outputs:
485+
486+
On macOS/Linux -
487+
488+
```bash
489+
rm -rf "$(pnpm store path)"
490+
```
491+
492+
On Windows -
493+
494+
Use the path returned by `pnpm store path` and delete it via File Explorer or `rmdir`.
495+
496+
> Note: pnpm prune removes unused tarballs but does not remove packument metadata. If you are seeing 404 errors after switching to or updating the Chainguard registry endpoint, use the commands above rather than pnpm prune.
497+
498+
{{< /details >}}
499+
500+
### Update lockfile hashes
501+
395502
If you are migrating an existing project and want to preserve your current
396503
lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
397504
to update only the integrity hashes in place instead.
@@ -457,6 +564,8 @@ This section applies to modern versions of Yarn, also known as Yarn Berry, with
457564
versions 2.x and higher. If you are using Yarn 1.x refer to the [Yarn Classic
458565
section](#yarn-classic).
459566

567+
**Declare dependencies in package.json**
568+
460569
With Yarn, you declare JavaScript package dependencies in a `package.json` file
461570
and separated into different scoped dependencies such as development and runtime
462571
dependencies. The following block shows a minimal example with `react` and
@@ -490,6 +599,15 @@ Any dependency or dependency version changes require another install and
490599
therefore an update to the lock file. The lock file also encodes the checksum
491600
values in the `checksum` field.
492601

602+
**Direct access: Point registry to Chainguard**
603+
604+
To change a project to use Chainguard Libraries for JavaScript, set the registry
605+
URL to point to Chainguard in your user `.yarnrc` file:
606+
607+
```bash
608+
yarn config set npmRegistryServer https://libraries.cgr.dev/javascript/
609+
```
610+
493611
### Using a repository manager
494612

495613
To change a project to use Chainguard Libraries for JavaScript, set the registry
@@ -510,18 +628,33 @@ more details such as authentication support.
510628

511629
Example URLs:
512630

513-
* JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all
514-
* Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all
515-
* Direct access: https://libraries.cgr.dev/javascript
631+
* JFrog Artifactory: `https://example.jfrog.io/artifactory/javascript-all`
632+
* Sonatype Nexus: `https://repo.example.com:8443/repository/javascript-all`
633+
* Direct access: `https://libraries.cgr.dev/javascript`
634+
635+
### Apply registry changes
516636

517637
To apply the registry change, run the `yarn` command again. This forces an update of
518638
all packages from the new registry and regeneration of the lock file.
519639

640+
If you encounter stale or corrupted package data, clear the cache with:
641+
642+
```bash
643+
yarn cache clean --all
644+
```
645+
646+
If you're seeing checksum mismatch errors rather than stale data, you can control Yarn's behavior via the [`checksumBehavior` setting](https://yarnpkg.com/configuration/yarnrc#checksumBehavior) in `.yarnrc.yml`. Setting it to `reset` causes Yarn to purge and re-fetch any cache entry whose checksum doesn't match, without clearing the entire cache:
647+
648+
```yaml
649+
checksumBehavior: reset
650+
```
651+
652+
### Update lockfile hashes
653+
520654
If you are migrating an existing project and want to preserve your current
521655
lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
522656
to update only the integrity hashes in place instead.
523657

524-
525658
Now you can proceed with your development and testing.
526659

527660
<a id="yarn-berry-minimal"></a>
@@ -623,6 +756,28 @@ therefore an update to the lock file. The lock file also encodes the checksum
623756
values in the `integrity` field and the download URL in the `resolved` field for
624757
each module.
625758

759+
**Direct access: Point registry to Chainguard**
760+
761+
To change a project to use Chainguard Libraries for JavaScript, first export your pull token as base64-encoded environment variables:
762+
763+
```bash
764+
export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0)
765+
```
766+
767+
Then, set auth and set the registry URL to point to Chainguard in your user `.npmrc` file:
768+
769+
```bash
770+
cat > .npmrc << 'EOF'
771+
registry=https://libraries.cgr.dev/javascript/
772+
//libraries.cgr.dev/javascript/:_auth="$token"
773+
//libraries.cgr.dev/javascript/:always-auth=true
774+
//libraries.cgr.dev/javascript-upstream/:_auth="$token"
775+
//libraries.cgr.dev/javascript-upstream/:always-auth=true
776+
EOF
777+
```
778+
779+
### Using a repo manager
780+
626781
To change a project to use Chainguard Libraries for JavaScript, set the registry
627782
URL to point to your repository manager in your `.npmrc` file:
628783

@@ -634,9 +789,12 @@ EOF
634789

635790
Example URLs:
636791

637-
* JFrog Artifactory: https://example.jfrog.io/artifactory/javascript-all
638-
* Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all
639-
* Direct access: https://libraries.cgr.dev/javascript
792+
* JFrog Artifactory: `https://example.jfrog.io/artifactory/javascript-all`
793+
* Sonatype Nexus: `https://repo.example.com:8443/repository/javascript-all`
794+
* Direct access: `https://libraries.cgr.dev/javascript`
795+
796+
797+
### Apply registry changes
640798

641799
Note that you can also use the `yarn config set registry` command to set the
642800
registry in the `.yarnrc` file, however this approach does not support
@@ -649,10 +807,25 @@ details.
649807

650808
To apply the registry change, remove the `node_modules` directory and the `yarn.lock`
651809
file and run the `yarn` command again. This forces a new download of all
652-
packages from the new registry and regeneration of the lock file. Alternatively,
810+
packages from the new registry and regeneration of the lock file:
811+
812+
```bash
813+
rm -rf node_modules yarn.lock
814+
yarn install
815+
```
816+
817+
Alternatively,
653818
you can run `yarn upgrade` to update all dependencies to their latest allowed
654819
versions and regenerate the lock file.
655820

821+
If you encounter stale or corrupted package data, clear the cache with:
822+
823+
```bash
824+
yarn cache clean
825+
```
826+
827+
### Update lockfile hashes
828+
656829
If you are migrating an existing project and want to preserve your current
657830
lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
658831
to update only the integrity hashes in place instead.
@@ -722,6 +895,8 @@ other desired packages for further testing.
722895
package manager designed as an alternative to Node.js tooling. It provides an
723896
integrated package manager that is compatible with the npm ecosystem.
724897

898+
**Declare dependencies in package.json**
899+
725900
With Bun you declare dependencies in a `package.json` file just like
726901
[npm](#npm). The following snippet shows a minimal example:
727902

@@ -785,6 +960,8 @@ Example registry URLs:
785960
* Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
786961
* Direct access: https://libraries.cgr.dev/javascript/
787962

963+
### Apply registry changes
964+
788965
To apply the registry change to an existing project, remove `node_modules` and
789966
the `bun.lock` file and run:
790967

0 commit comments

Comments
 (0)