A custom remote caching server for Nx, written in Go.
This implementation follows the Nx OpenAPI specification (v20.8+) and provides a lightweight, self-hosted remote cache solution.
Since Nx 20.8, you can use your own caching server by implementing their OpenAPI spec.
This server handles storage, retrieval, and optional bearer-token authentication.
Configure the server using environment variables:
| Variable | Description | Default | Example values |
|---|---|---|---|
STORAGE_DIR |
Directory for storing cache artifacts | System temp dir | /data/nx-cache |
CLEANUP_THRESHOLD |
Duration after which unused cache entries are removed (hours only) | 1h |
1h, 24h, 168h |
PORT |
Port the server listens on | 8090 |
8080 |
AUTH_TOKEN |
Bearer token required for all requests (optional) | (unset = no auth) | my-secure-token |
AUTH_TOKENS |
Comma-separated name:token pairs, one per repository; each token only sees STORAGE_DIR/<name>/ (optional) |
(unset) | repoA:tokA,repoB:tokB |
Note: CLEANUP_THRESHOLD uses hour-based durations (e.g. 24h = 1 day, 168h = 1 week).
Note: AUTH_TOKEN and AUTH_TOKENS cannot be combined; the server exits at startup if both are set.
-
Build the binary:
go build -o nx-caching-server ./main.go
-
Run it:
./nx-caching-server
With custom settings:
STORAGE_DIR=./cache-data \ PORT=8090 \ AUTH_TOKEN=super-secret-123 \ CLEANUP_THRESHOLD=24h \ ./nx-caching-server
Pull the pre-built image from Docker Hub:
docker pull enxtur/nx-caching-serverRun example (with persistent storage and authentication):
docker run -d \
--name nx-cache \
-p 8090:8090 \
-v $(pwd)/nx-cache-data:/data \
-e STORAGE_DIR=/data \
-e AUTH_TOKEN=your-secure-token-here \
-e CLEANUP_THRESHOLD=48h \
enxtur/nx-caching-serverOr build your own image from source (if preferred):
docker build -t nx-caching-server .Create a docker-compose.yml file:
version: '3.8'
services:
nx-cache:
image: enxtur/nx-caching-server:latest
container_name: nx-caching-server
restart: unless-stopped
ports:
- "8090:8090"
volumes:
- ./nx-cache-data:/data
environment:
- STORAGE_DIR=/data
- PORT=8090
- AUTH_TOKEN=your-secure-token-here # remove this line if you want no authentication
- CLEANUP_THRESHOLD=24hStart it:
docker compose up -dSeveral repositories can share one server while keeping their caches separate. Give each repository its own name and token with AUTH_TOKENS:
services:
nx-cache:
image: enxtur/nx-caching-server:latest
restart: unless-stopped
ports:
- "8090:8090"
volumes:
- ./nx-cache-data:/data
environment:
- STORAGE_DIR=/data
- AUTH_TOKENS=web-app:token-for-web-app,api:token-for-api
- CLEANUP_THRESHOLD=24hEach token can only read and write its own subdirectory:
nx-cache-data/
├── web-app/
│ └── <hash>.cache
└── api/
└── <hash>.cache
- Names may contain only letters, digits,
_and-. Tokens may contain:; only the first:separates the name from the token. - Names and tokens must be unique.
- Each repository sets its own token in
NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN; no other Nx changes are needed. - Switching from
AUTH_TOKENtoAUTH_TOKENSmoves cache files into per-name subdirectories, so Nx misses the cache once and rebuilds. The old flat files expire through normal cleanup.
Point your Nx workspace to the caching server by setting these environment variables (or add them to .env / CI config):
# No authentication
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=http://localhost:8090
# With authentication
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=http://localhost:8090
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=your-secure-token-hereThen run your tasks as usual:
npx nx run-many --target=build --allNx will automatically read from / write to your self-hosted cache.
Contributions, bug reports, and feature suggestions are welcome!
Feel free to open an issue or submit a pull request.