Turborepo Remote Cache (For Cloudflare Workers!)

🚀 Introduction

This project offers an open source implementation of the Turborepo custom remote cache server purpose-built from the ground up for Cloudflare Workers

📚 For detailed documentation, please refer to our official website

Important

You can now store your build artifacts in either Cloudflare 🪣 R2 or 🔑 KV storage. Find out how in our official documentation

🤔 Why should I use this?

If you're a Turborepo user, this project offers compelling advantages:

💿 Storage Options: Choose between 🪣 R2 or 🔑 KV storage for your build artifacts. This gives you the flexibility to choose the storage option that best fits your needs.
🚀 Faster Builds: Harness the power of remote caching to significantly speed up your builds
🌐 Independence from Vercel: Use Turborepo without tying your project to Vercel. This gives you flexibility in hosting decisions.
🌍 Global Deployment: Code deploys instantly across the globe in over 300 countries, ensuring unmatched performance and reliability.
💰 Affordable Start: With Cloudflare Workers' generous free tier, you can make up to 100,000 requests every day at no cost. Even better Cloudflare has zero egress fees on it's platform, meaning you only pay for what you use.

⚡️ Quick start

Deploy Using the CLI

The fastest and easiest way to deploy this project is with wrangler (cloudflare's CLI tool for managing workers).

This project already comes with wrangler installed and configured, so all you need to do is clone this repository and run pnpm run deploy.

# 1. Clone the repository
git clone https://github.com/AdiRishi/turborepo-remote-cache-cloudflare.git

# 2. Install packages
pnpm install

# 3. Create the R2 bucket for storage
pnpm wrangler r2 bucket create turborepo-cache

# 4. Publish the project
pnpm run deploy

# 5. Set a Bearer auth token
echo "SECRET" | pnpm wrangler secret put TURBO_TOKEN

Deploy using Cloudflare's deploy button

This project also supports one-click deploy via Cloudflare's deploy button. Use this option only if you already have a Cloudflare account and have used R2 buckets before.

Warning

The deploy button workflow has some bugs/gotchas that may catch people new to Cloudflare's ecosystem off guard (see #258 or our docs). It's recommended to use the CLI method if you're new to Cloudflare.

⚙️ Configuration

Github actions requirements

In order to successfully run the deploy Github action you will need the following secrets

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
TURBO_TOKEN

For those who have forked this repository, feel free to delete the release.yml workflow file. This is only used to automatically publish new releases of this repository to GitHub releases.

Automatic deletion of old cache files

This project sets up a cron trigger for Cloudflare workers, which automatically deletes old cache files within the bound R2 bucket. This behavior can be customized:

To disable the automatic deletion, remove the [triggers] configuration in wrangler.toml
To change the retention period for objects, adjust the BUCKET_OBJECT_EXPIRATION_HOURS option in wrangler.toml or set it via workers environment variables

▲ Setting up remote caching in your Turborepo project

Here's my recommended approach for setting up remote caching in your Turborepo project. You can read more about this topic in the official Turborepo documentation.

Step 1: Update `turbo.json`

Modify the turbo.json file at your project root to include signature validation

{
    "remoteCache": { "signature": true }
}

Step 2: Install `dotenv-cli`

Install the dotenv-cli npm package:

# You may have to add -W if you are installing this on your workspace root
pnpm add -D dotenv-cli

Step 3: Create a `.env` File

Create a .env file at your project root with the following content:

TURBO_API=YOUR_API_URL # Remember to remove the trailing slash
TURBO_TEAM=team_my_team_name
TURBO_TOKEN=SECRET # The turbo token must be a valid Bearer auth token
TURBO_REMOTE_CACHE_SIGNATURE_KEY=SECRET

Keep the following in mind

Replace SECRET and YOUR_API_URL with your chosen values.
Turborepo requires that the TURBO_API value must not end with a trailing slash
The TURBO_TEAM value must begin with team_
Remember to add the .env file to .gitignore
If you are building your project in some remote CI tool (like Github Actions) you need to make these environment variables available to your build script

Step 4: Modify Turbo Commands

Load the .env file prior to execution. Instead of running a command like turbo run build directly, use dotenv -- turbo run build. This loads everything in our .env file into the process's environment variables.

Here's how to modify your scripts in package.json to use dotenv-cli:

{
    "scripts": {
        "build": "dotenv -- turbo run build",
        "dev": "dotenv -- turbo run dev",
        "lint": "dotenv -- turbo run lint",
        "test": "dotenv -- turbo run test"
    }
}

And that's it 🎉🎉

Whenever you run a turbo command you will see Remote cache enabled in it's log output

pnpm lint

$ dotenv -- turbo run lint
• Packages in scope: turborepo-project, webapp, docs
• Running lint in 3 packages
• Remote caching enabled

...output

 Tasks:    3 successful, 3 total
Cached:    3 cached, 3 total
  Time:    1.174s >>> FULL TURBO

✨  Done in 3.54s.

Made with ❤️

AdiRishi/turborepo-remote-cache-cloudflare