Registry / devops / turborepo-remote-cache

turborepo-remote-cache

library2.8.4jsnpmunverified

turborepo-remote-cache provides a self-hosted, open-source alternative to Vercel's official Turborepo remote cache service, allowing teams to manage their monorepo build artifact caching infrastructure in private environments. It supports a variety of storage providers, including S3, Google Cloud Storage, and Azure Blob Storage, and offers flexible deployment options such as Docker, Kubernetes, and serverless platforms. The project is actively maintained, currently at version 2.8.4 (April 2026), with a consistent release cadence that primarily focuses on dependency updates, security patches (e.g., Fastify bumps), and incremental feature enhancements. Its key differentiators include the flexibility to choose a storage backend, comprehensive deployment guides, and empowering organizations with full control over their build caching strategy, which is critical for compliance or specific infrastructure requirements. It requires Node.js version 20 or higher.

devops aws gcp azure web-framework

npm install turborepo-remote-cache

github ↗package ↗

INSTALL

IMPORT

SIG · TURBOREPO-REMOTE-C

turborepo-remote-cache

devopsjavascriptv2.8.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

start

✓ import { start } from 'turborepo-remote-cache';

✗ const { start } = require('turborepo-remote-cache');

The `start` function is the programmatic entry point for the server. The package is primarily designed for ESM usage, reflecting its Node.js >=20.0.0 requirement.

Options

✓ import type { Options } from 'turborepo-remote-cache';

For TypeScript users, import the `Options` interface to type the configuration object passed to the `start` function.

* as TurborepoCache

✓ import * as TurborepoCache from 'turborepo-remote-cache';

✗ import TurborepoCache from 'turborepo-remote-cache';

While not the most common usage, this imports all named exports if you prefer to namespace them. There is no default export.

This quickstart demonstrates how to programmatically start the Turborepo remote cache server using TypeScript, configured for an S3 storage backend with authentication.

import { start } from 'turborepo-remote-cache'; // Configure environment variables for a basic S3-backed cache process.env.STORAGE_PROVIDER = 's3'; process.env.S3_BUCKET = process.env.AWS_BUCKET_NAME ?? 'your-turbocache-bucket'; process.env.S3_REGION = process.env.AWS_REGION ?? 'us-east-1'; process.env.S3_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID ?? ''; // Ensure these are set in your env process.env.S3_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY ?? ''; // Ensure these are set in your env process.env.AUTH_TOKEN = process.env.TURBO_AUTH_TOKEN ?? 'supersecrettoken'; // Crucial for security process.env.PORT = process.env.PORT ?? '3000'; process.env.HOST = process.env.HOST ?? '0.0.0.0'; // Default host for wider accessibility async function runCacheServer() { try { const { url } = await start(); console.log(`Turborepo Remote Cache server listening at ${url}`); } catch (err) { console.error('Failed to start Turborepo Remote Cache server:', err); process.exit(1); } } runCacheServer();

Debug

Known issues

breakingThe minimum Node.js version requirement was raised to `20.0.0`. Running on older Node.js versions (e.g., 18.x) may lead to unexpected behavior or failures. Recent releases (v2.8.3) default to Node.js 24 for container deployments.

fix

Ensure your environment uses Node.js v20.0.0 or higher. For new deployments, consider using Node.js v24 for optimal compatibility as indicated by the project.

affects: >=2.0.0

gotchaThe default `HOST` environment variable changed to `0.0.0.0` in v2.8.0. While this improves accessibility in containerized environments, it might expose the server to all network interfaces if not intended or secured properly, especially in non-containerized setups.

fix

Explicitly set the `HOST` environment variable (e.g., `HOST=127.0.0.1`) if you only want the server to listen on a specific interface, or ensure proper firewall rules are in place.

affects: >=2.8.0

gotchaFor secure operation, it is critical to set the `AUTH_TOKEN` environment variable. If `AUTH_TOKEN` is not set, or if `AUTH_MODE=none` (introduced in v2.7.0) is explicitly used, the cache will be publicly accessible without authentication, posing a significant security risk for sensitive artifacts.

fix

Always set a strong `AUTH_TOKEN` in production environments. Avoid `AUTH_MODE=none` unless you are operating within a completely trusted and isolated network segment, or implementing external authentication.

affects: >=2.0.0

gotchaRegular dependency bumps, especially for `fastify` and `ajv`, are common. While these often include security patches and performance improvements, they can occasionally introduce subtle behavioral changes or new requirements for plugins, which could impact highly customized deployments.

fix

Monitor the project's changelog for each new minor/patch release. Test upgrades in a staging environment before deploying to production, especially if you rely on specific `fastify` features or plugins.

affects: >=2.0.0

Errors

Common errors & fixes

HTTP 401 Unauthorized

The `AUTH_TOKEN` environment variable is either not set on the server, or the client is not providing the correct token in its requests.

fix

Ensure the `AUTH_TOKEN` environment variable on your `turborepo-remote-cache` server matches the `REMOTE_CACHE_TOKEN` configured in your Turborepo client's `.env.local` or `turbo.json`.

Error: listen EADDRINUSE: address already in use :::3000

Another process is already listening on the port that `turborepo-remote-cache` is trying to use (default 3000).

fix

Change the port by setting the `PORT` environment variable (e.g., `PORT=4000`) for the `turborepo-remote-cache` server, or terminate the conflicting process.

Error: Missing environment variable for storage provider: S3_BUCKET is not set.

Required environment variables for the selected storage provider (e.g., S3, GCS, Azure) are not configured, preventing the server from connecting to the backend storage.

fix

Refer to the documentation for your chosen `STORAGE_PROVIDER` (e.g., S3, GCS) and ensure all necessary environment variables (e.g., `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`) are correctly set.

Upgrade

Version history

2.8.4latest on npm

Audit

Dependencies

fastifyrequiredCore web framework for the HTTP server.

ajvrequiredUsed for JSON schema validation within the Fastify framework.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ducktors/turborepo-remote-cache ↗

packagehttps://www.npmjs.com/package/turborepo-remote-cache ↗