> ## Documentation Index
> Fetch the complete documentation index at: https://celesto.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript and TypeScript

> Speed up Node.js jobs with npm and pnpm dependency caches, Turborepo task caches, and Nx remote caching.

Reuse downloaded packages and completed builds so your checks finish sooner. Save package downloads and build results separately. Compare the complete job duration to find which saves the most time for your project.

First complete the [CI quickstart](https://celesto.ai/docs/ci.md#quickstart) for your repository. The examples use Linux runners and Node.js 22. Keep action versions aligned with your repository's update policy.

## Cache npm downloads

Commit `package-lock.json`, the lockfile that records your exact dependency versions. For a project with an `npm test` command, save this workflow as `.github/workflows/npm-tests.yml`:

```yaml .github/workflows/npm-tests.yml theme={null}
name: npm tests
on: [push, pull_request, workflow_dispatch]
permissions:
  contents: read
jobs:
  test:
    runs-on: celesto-micro
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
          cache-dependency-path: package-lock.json
      - run: npm ci
      - run: npm test
```

The [setup action](https://github.com/actions/setup-node#caching-global-packages-data) saves npm's downloaded packages. `npm ci` uses your lockfile to create `node_modules`, the directory of installed dependencies.

Keep the install step on every run. It reuses saved downloads on a **cache hit** and downloads packages on a **cache miss**. Saving npm's download cache fits this workflow because `npm ci` creates a fresh installed directory each time.

To check reuse, run the workflow twice with the same lockfile. Look for a restore message in the setup action's logs on the second run, followed by successful installation and tests.

## Choose what to cache with pnpm

pnpm keeps downloaded package files in a **store**, then creates the installed dependencies your project uses. These caches serve different purposes:

| Saved files | What you reuse | What to measure |
| - | - | - |
| pnpm store | Downloaded packages | Restore plus installation time |
| Root and package-level `node_modules` | Installed dependencies and links between packages | Unpacking plus installation checks |
| `lockfile-verified.jsonl`, when your pnpm version creates it | Successful checks that locked packages meet your dependency rules | Time spent checking package information with the registry |

Start with the store. Compare installed dependencies if installation remains a large part of your job. See [restore performance](https://celesto.ai/docs/ci/caching.md#reduce-cache-restore-time) when a large number of small files makes extraction slow.

### Save the pnpm store

Commit `pnpm-lock.yaml` and set an exact pnpm version in the `packageManager` field of your root `package.json`. For a project with a `pnpm test` command, save this workflow as `.github/workflows/pnpm-tests.yml`:

```yaml .github/workflows/pnpm-tests.yml theme={null}
name: pnpm tests
on: [push, pull_request, workflow_dispatch]
permissions:
  contents: read
jobs:
  test:
    runs-on: celesto-micro
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v6
        with:
          run_install: false
      - uses: actions/setup-node@v4
        id: node
        with:
          node-version: "22"
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml
      - run: pnpm install --frozen-lockfile
      - run: pnpm test
```

Install pnpm before `setup-node` so the setup action can find the store. Its `cache: pnpm` option saves the store; it recreates installed dependencies during the install step. `--frozen-lockfile` requires the committed lockfile to agree with your package definitions.

Run the workflow twice with the same lockfile. On the second run, check the setup action's logs for a restored store and confirm that installation and tests succeed.

### Save installed dependencies and verification results

For a pnpm monorepo (several packages in one repository), include the root and every package's `node_modules`.

A **cache key** names a saved entry. Include the operating system, processor architecture, Node.js and pnpm versions, lockfile, package definitions, local package changes, and installation settings in that key. These details help you restore files built for the same environment.

pnpm v11 introduced lockfile policy verification: checks that locked package versions meet your dependency rules. Versions that use `lockfile-verified.jsonl` save a successful check in the configured cache directory. Keeping that record lets pnpm reuse an accepted result for the same lockfile and compatible rules.

The record is separate from the store and installed dependencies. Its availability depends on your pnpm version and installation settings. See [pnpm's verification design](https://github.com/pnpm/pnpm/issues/11722).

In the pnpm workflow above, replace the `setup-node` and install steps with these steps. Keep checkout, pnpm setup, and the final test step:

```yaml theme={null}
      - uses: actions/setup-node@v4
        id: node
        with:
          node-version: "22"
      - name: Read pnpm version
        id: pnpm-version
        run: echo "version=$(pnpm --version)" >> "$GITHUB_OUTPUT"
      - name: Restore installed dependencies and verification results
        uses: actions/cache@v4
        with:
          path: |
            node_modules
            apps/*/node_modules
            packages/*/node_modules
            ${{ runner.temp }}/pnpm-metadata/lockfile-verified.jsonl
          key: >-
            pnpm-modules-v1-${{ runner.os }}-${{ runner.arch }}-node${{ steps.node.outputs.node-version }}-pnpm${{ steps.pnpm-version.outputs.version }}-${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', '**/package.json', '**/.npmrc', 'patches/**') }}
      - name: Check and install dependencies
        run: pnpm install --frozen-lockfile --cache-dir="$RUNNER_TEMP/pnpm-metadata"
```

Use this as an alternative to `cache: pnpm`. Adjust `apps/*/node_modules` and `packages/*/node_modules` to match the package locations in `pnpm-workspace.yaml`. Add any custom patch paths or installation settings to `hashFiles`, which includes those files' contents in the key.

Keep the install step on every run so pnpm checks the restored dependencies and handles a miss. Use an exact key for installed dependencies. This example leaves `restore-keys` unset so it restores only an exact match.

The example sets `--cache-dir` explicitly so the saved path matches the install path. Keep your dependency policy checks enabled and let pnpm decide whether a saved verification result is valid.

## Reuse Turborepo task results

Celesto saves Turborepo task results automatically, with no extra setup. See [Turbo cache](https://celesto.ai/docs/ci/turbo-cache.md).

## Reuse Nx task results

Nx also reuses completed tasks, but its local cache checks which machine created the files. Each Celesto job gets a fresh computer. Copying Nx's local cache through `actions/cache` can produce an [unknown local cache error](https://nx.dev/docs/kb/unknown-local-cache).

Use [Nx Cloud or a supported self-hosted remote cache](https://nx.dev/docs/features/ci-features/remote-cache) for task results shared between jobs. Continue caching npm or pnpm dependencies through Celesto. Set up the remote cache's read and write permissions for your default branch and pull requests using that provider's instructions.

Keep Nx's checks for trusted cache files enabled. Follow the chosen provider's Nx setup instructions to share task results between computers.

## Cache Docker builds separately

Docker saves reusable parts of an image, called layers, separately from your dependency and task caches. Save and restore them with `cache-to` and `cache-from` set to `type=gha`, as shown in [Cache image layers between jobs](https://celesto.ai/docs/ci/docker.md#cache-image-layers-between-jobs).


## Related topics

- [Cache dependencies between CI jobs](https://celesto.ai/docs/ci/caching.md)
- [Use the Celesto HTTP API and TypeScript SDK](https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk.md)
- [Celesto SDK for sandboxed computers and agents](https://celesto.ai/docs/cloud/overview.md)
- [CLI overview](https://celesto.ai/docs/celesto/cli/overview.md)
- [Control internet access for AI agent sandboxes](https://celesto.ai/docs/cloud/features/network-control.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.