Implementation guide for node_modules cache

1. prerequisites

Collect these inputs before sending your first request.

package.json and package-lock.json from the project you want to cache.
Your CI image tag for dockerImageReference — use the official node image with a specific version tag (e.g. node:22.15.0) and CPU architecture (x64 or arm64). Avoid floating tags such as node:lts or node:22 — the service pins the cache to the exact image digest, so an undetected image update will silently cause cache misses.
For the shell example: curl, jq, and tar available on the runner.
A personal access token stored in CI as NMC_ACCESS_TOKEN.

2. token setup

Create an account to get started.
In the token area, generate a new access token for CI usage.
Save it in your CI secrets as NMC_ACCESS_TOKEN — never commit tokens to source control.

3. request, extract & fallback

Each snippet covers the full flow: read the manifest files, call the API, save and extract the archive, and fall back to npm ci if the request fails or returns an error.

# Download the binary for your platform.
# All releases: https://www.staging.node-modules-cache.com/nmc-cli

# Linux amd64
curl -fsSL "https://www.staging.node-modules-cache.com/nmc-cli/nmc-linux-amd64" \
  -o nmc && chmod +x nmc

# Linux arm64
# curl -fsSL "https://www.staging.node-modules-cache.com/nmc-cli/nmc-linux-arm64" \
#   -o nmc && chmod +x nmc

# Required environment variables
export NMC_TOKEN="${NMC_ACCESS_TOKEN}"   # your API token
export NMC_BASE_DIR="/path/to/project"   # absolute path — package.json must be here
export NMC_DOCKER_IMAGE="node:22.15.0"   # your CI Docker image reference
export NMC_ARCHITECTURE="x64"            # x64 or arm64

# Run — reads manifests, calls the API, extracts node_modules,
# retries up to 5 times, and falls back automatically on error.
./nmc

jq -n \
  --argfile package package.json \
  --argfile lock package-lock.json \
  '{
    dockerImageReference: "node:22.15.0",
    architecture: "x64",
    ".npmrc": "@fortawesome:registry=https://npm.fontawesome.com/\n//npm.fontawesome.com/:_authToken=${FONTAWESOME_TOKEN}\n",
    environmentVariables: {
      FONTAWESOME_TOKEN: env.FONTAWESOME_TOKEN
    },
    "package.json": $package,
    "package-lock.json": $lock
  }' > payload.json

if curl --request POST "https://www.staging.node-modules-cache.com/api/v2/npm/ci" \
  --header "Authorization: Bearer ${NMC_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  --location \
  --fail-with-body \
  --output node_modules.tar.gz; then
  tar -xzf node_modules.tar.gz
else
  npm ci
fi

import { execSync } from "node:child_process"
import { readFile, writeFile } from "node:fs/promises"

const [packageJson, lockFile] = await Promise.all([
  readFile("package.json", "utf8").then(JSON.parse),
  readFile("package-lock.json", "utf8").then(JSON.parse),
])

const response = await fetch("https://www.staging.node-modules-cache.com/api/v2/npm/ci", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NMC_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    dockerImageReference: "node:22.15.0",
    architecture: "x64",
    ".npmrc": "@fortawesome:registry=https://npm.fontawesome.com/\n//npm.fontawesome.com/:_authToken=${FONTAWESOME_TOKEN}\n",
    environmentVariables: {
      FONTAWESOME_TOKEN: process.env.FONTAWESOME_TOKEN,
    },
    "package.json": packageJson,
    "package-lock.json": lockFile,
  }),
  redirect: "follow",
})

if (!response.ok) {
  console.error(`Cache request failed (${response.status}), falling back to npm ci`)
  execSync("npm ci", { stdio: "inherit" })
} else {
  await writeFile("node_modules.tar.gz", Buffer.from(await response.arrayBuffer()))
  execSync("tar -xzf node_modules.tar.gz", { stdio: "inherit" })
}

$package = json_decode(file_get_contents('package.json'), true, 512, JSON_THROW_ON_ERROR);
$lock    = json_decode(file_get_contents('package-lock.json'), true, 512, JSON_THROW_ON_ERROR);

$payload = [
    'dockerImageReference' => 'node:22.15.0',
    'architecture'         => 'x64',
    '.npmrc'               => '@fortawesome:registry=https://npm.fontawesome.com/' . "\n"
        . '//npm.fontawesome.com/:_authToken=${FONTAWESOME_TOKEN}' . "\n",
    'environmentVariables' => [
        'FONTAWESOME_TOKEN' => getenv('FONTAWESOME_TOKEN'),
    ],
    'package.json'         => $package,
    'package-lock.json'    => $lock,
];

$ch = curl_init('https://www.staging.node-modules-cache.com/api/v2/npm/ci');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('NMC_ACCESS_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_THROW_ON_ERROR),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
]);

$archive = curl_exec($ch);
$status  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400 || $archive === false) {
    passthru('npm ci');
} else {
    file_put_contents('node_modules.tar.gz', $archive);
    passthru('tar -xzf node_modules.tar.gz');
}

import json
import os
import subprocess
import tarfile

import requests

with open("package.json") as f:
    package_json = json.load(f)
with open("package-lock.json") as f:
    lock_file = json.load(f)

response = requests.post(
    "https://www.staging.node-modules-cache.com/api/v2/npm/ci",
    headers={"Authorization": f"Bearer {os.environ['NMC_ACCESS_TOKEN']}"},
    json={
        "dockerImageReference": "node:22.15.0",
        "architecture": "x64",
        ".npmrc": "@fortawesome:registry=https://npm.fontawesome.com/\n//npm.fontawesome.com/:_authToken=${FONTAWESOME_TOKEN}\n",
        "environmentVariables": {
            "FONTAWESOME_TOKEN": os.environ["FONTAWESOME_TOKEN"],
        },
        "package.json": package_json,
        "package-lock.json": lock_file,
    },
    allow_redirects=True,
    timeout=120,
)

if not response.ok:
    print(f"Cache request failed ({response.status_code}), falling back to npm ci")
    subprocess.run(["npm", "ci"], check=True)
else:
    with open("node_modules.tar.gz", "wb") as f:
        f.write(response.content)
    with tarfile.open("node_modules.tar.gz", "r:gz") as tar:
        tar.extractall(".")

The nmc CLI is an open-source Go binary maintained by us. Download binaries for Linux and Windows (amd64 / arm64) from the nmc CLI page .

4. optional request fields

All fields below are optional. Omit them if you do not need them.

`environmentVariables`

Pass any string-to-string map to expose variables to npm ci and package lifecycle scripts inside the container. NODE_ENV still supports production, development, or test, and CYPRESS_CACHE_FOLDER still uses the existing cache-path remap.

`.npmrc`

Pass raw .npmrc text in the JSON body under the .npmrc key when you need private registry config. The service writes it into the project directory before running npm ci. In the current implementation, .npmrc and environmentVariables are persisted with the request so the build can be replayed later.

Private registry example

{
  "dockerImageReference": "node:22.15.0",
  "architecture": "x64",
  ".npmrc": "@fortawesome:registry=https://npm.fontawesome.com/\n//npm.fontawesome.com/:_authToken=${FONTAWESOME_TOKEN}\n",
  "environmentVariables": {
    "FONTAWESOME_TOKEN": "your-fontawesome-token"
  },
  "package.json": { ... },
  "package-lock.json": { ... }
}

5. trust & support boundaries

Authentication is always required: send a valid Bearer token with every request.
Required fields: dockerImageReference, architecture, package.json, and package-lock.json in an application/json body. Optional: .npmrc and environmentVariables (see step 4).
Success output is a downloadable node_modules.tar.gz artifact — extract before running tasks that depend on node_modules/.
This service is an optimisation layer. CI speedups depend on your cache hit rate and workflow shape.
Solo and Team include priority support. All plans can use docs and contact .

Run your first cache-backed CI install in minutes