common questions

Frequently Asked Questions

Everything you need to know about node_modules cache.

general

What is node_modules cache?

An API service for reusing previously built node_modules archives. Instead of reinstalling on every CI run, your pipeline requests an archive and extracts it when the same dependency set was processed before.

How does it work?

  1. Call POST /api/v2/npm/ci with your manifests in an application/json body.
  2. We compute a deterministic hash from your user, image digest, architecture, and payload.
  3. Cache hit: 302 to an existing archive. Cache miss: we run npm ci, store it, then return 302.
  4. Your client follows the redirect, downloads node_modules.tar.gz, and extracts it.

What CI/CD systems are supported?

Any CI system that can make HTTP requests — GitHub Actions, GitLab CI, Jenkins, CircleCI, Bitbucket Pipelines, etc. The API is platform-agnostic.

Is there a CLI client?

Yes. The nmc CLI is an open-source Go binary that handles the full flow — request, extraction, retries, and automatic npm ci fallback. Drop it into any CI runner and set four environment variables. Pre-built binaries are available for Linux and Windows (amd64 / arm64).

How long are cached archives kept?

Archives are retained for 3 months from the last request that matched them. If no request hits a cached archive within that window, it expires and the next request for the same dependency set is treated as a cache miss — we run npm ci again and store a fresh archive as usual.

Because of this, always keep an npm ci fallback in your pipeline or use the nmc CLI , which handles retries and fallback automatically.

advanced usage

Which Docker image should I use?

Use the official node image with a specific version tag, e.g. node:22.15.0. Avoid floating tags like node:lts or node:22 — the service ties the cache to the exact image digest, so a silent upstream update to those tags will cause a cache miss on the next run even though nothing in your project changed.

Can I control NODE_ENV during the build?

Yes. Pass "environmentVariables": { "NODE_ENV": "production" } (or development / test) in your request body to set the environment variable for npm ci inside the container. This affects any lifecycle scripts that branch on NODE_ENV.

How do I include the Cypress binary in the cache?

Cypress writes its binary to ~/.cache/Cypress by default — outside node_modules/ and therefore not included in the archive. To include it, set environmentVariables.CYPRESS_CACHE_FOLDER to an absolute path such as /cypress/cache in your request body. The service remaps that path to inside node_modules/ before archiving, so the binary lands at node_modules/cypress/cache/ after extraction.

After extracting in CI, point Cypress to the cached binary:

export CYPRESS_CACHE_FOLDER="$(pwd)/node_modules/cypress/cache"

See the implementation guide for a full request example.

pricing & plans

Is there a free plan?

Yes. The Free plan includes 20 first-run builds per day and 200 per month. Repeat builds (cache hits) are unlimited on all plans.

What's the difference between first-run and repeat builds?

First-run build (cache miss): No archive exists yet — we run npm ci, store the result, then redirect. Counts against your daily/monthly limit.

Repeat build (cache hit): Archive already exists — we return a 302 redirect immediately. Unlimited on all plans.

What happens if I exceed my limits?

The API returns 429 Rate limit exceeded for additional first-run builds until the window resets. Keep an npm ci fallback in your pipeline and upgrade on the pricing page .

Can I cancel my subscription anytime?

Yes. You'll retain access to your paid plan until the end of your current billing period.

Do you offer a Custom plan?

Yes. For high-volume teams that need custom request limits or dedicated support, get in touch to discuss your requirements.

security & privacy

Is my data secure?

All requests require authentication. Cached archives are isolated per user — no cross-user access. Data is encrypted in transit.

Do you store my package.json files?

The request payload is persisted to track and reproduce cache requests. The generated artifact is a node_modules.tar.gz archive tied to your request hash.

Can other users access my cached packages?

No. Each user's cache is completely isolated. Your API token authenticates you, and only you can access your cached archives.

support

How do I get support?

Solo and Team users get priority support. All plans can use docs and the contact page . Dashboard analytics and API logs are the first stop before reaching out.

Can I track my API usage?

Yes. Your dashboard shows total requests, cache hits, first-run builds, hit rates, and daily/monthly usage against your plan limits.

technical docs

Implementation guide

Prerequisites, token setup, request examples, and CI fallback.

Troubleshooting

API error patterns and redirect handling.

Create account

Set up account access and a CI token.

Ready for your next technical step?

Start with the implementation guide, then create your account to generate a CI token.

Implementation guide Create account