DOCSEARCHbyAlgolia
Submit Docs

Turborepo Remote Cache for Cloudflare Workers

repository·master·Indexed 42 days ago

https://github.com/adirishi/turborepo-remote-cache-cloudflare

An open-source implementation of a Turborepo custom remote cache server purpose-built for Cloudflare Workers. Version 4.0.0 allows users to host their own remote cache using Cloudflare R2 or KV storage, providing independence from Vercel and global deployment. Includes features for automatic cache deletion via cron triggers and signature validation for artifact integrity.

Tokens
7.2K
Snippets
26
Records
35
Agent score
51%

What's inside turborepo-remote-cache-cloudflare

  2. Use One-click Deploy for Cloudflare Workers

    master

    You can use Cloudflare's one-click deploy feature to automate the deployment process. This is particularly useful for new users. The process involves linking your GitHub account to Cloudflare and forking the repository.

    Important Requirements & Gotchas

    • Enable R2 Storage: If you have never used R2 on your Cloudflare account, you must enable it before completing the deployment. You may be required to enter credit card details, but Cloudflare R2 includes a 10GB free tier and you will not be charged unless you exceed this limit.
    • Manual Steps Required: One-click deploy does not automatically set up your GitHub workflow secrets or enable R2 storage. You must perform these steps manually after the initial deployment.
    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/AdiRishi/turborepo-remote-cache-cloudflare)

  3. Create a Cloudflare R2 bucket for artifact storage

    master

    To store build artifacts, you must first create an R2 bucket. You can do this via the Wrangler CLI or the Cloudflare Dashboard.

    Using Wrangler CLI

    Run the following command to create a bucket. Note that using the CLI will create the bucket in the region closest to you. If you need to specify a specific region to minimize latency for your Workers, use the Cloudflare Dashboard instead.

    Using Cloudflare Dashboard

    1. Navigate to the R2 tab in the Cloudflare dashboard.
    2. Click Create Bucket.
    3. Enter a name and select a region. It is recommended to pick a region closest to where your API requests originate (e.g., a US region if using GitHub Actions in the US).
    4. Click Create Bucket.
    wrangler r2 bucket create YOUR_BUCKET_NAME

  4. Set up remote caching in your Turborepo project

    master

    To enable remote caching using this project, follow these four steps to configure your Turborepo workspace with signature validation, environment variables, and dotenv-cli for command execution.

    1. Enable Signature Validation

    Update your turbo.json at the project root to include the signature option. This ensures artifact integrity and authenticity.

    2. Install dotenv-cli

    Install dotenv-cli as a development dependency. If you are in a monorepo, you may need to use the -W flag to install it at the workspace root.

    3. Configure Environment Variables

    Create a .env file at your project root. You must provide the following variables:

    • TURBO_API: Your API URL. Important: Do not include a trailing slash.
    • TURBO_TEAM: Your team name. Important: Must begin with the prefix team_.
    • TURBO_TOKEN: A valid Bearer auth token.
    • TURBO_REMOTE_CACHE_SIGNATURE_KEY: Your secret key for signature verification.

    Note: Add .env to your .gitignore. If using CI (e.g., GitHub Actions), ensure these variables are configured in your CI environment settings.

    4. Update Scripts to use dotenv

    Prefix your Turbo commands with dotenv -- to ensure the environment variables are loaded before execution. Update your package.json scripts accordingly.

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

  6. Deploy the Turborepo Remote Cache using Wrangler

    master

    The fastest way to deploy this project is using the Cloudflare CLI tool, wrangler. This project includes a pre-configured wrangler setup. Follow these steps to clone, install, create the necessary R2 storage bucket, deploy the worker, and set your authentication token.

    Note: You must create an R2 bucket named turborepo-cache for the storage to function correctly.

    # 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

  7. Configure GitHub Actions secrets for deployment

    master

    If you are using GitHub Actions for deployment (e.g., after forking the repository), you must configure the following secrets in your GitHub repository settings to allow the deploy workflow to run successfully:

    • CLOUDFLARE_API_TOKEN
    • CLOUDFLARE_ACCOUNT_ID
    • TURBO_TOKEN

    If you have forked the repository and do not need the original project's CI/CD pipeline, you can safely delete the following workflow files:

    • .github/workflows/release.yml
    • .github/workflows/docs-pr-preview.yml
    • .github/workflows/deploy-docs.yml

  8. Deploy Turborepo Remote Cache to Cloudflare Workers

    master

    You can deploy this remote cache implementation using the provided CLI setup. This requires pnpm and wrangler (Cloudflare's CLI). Follow these steps to clone, prepare storage, and deploy:

    1. Clone the repository.
    2. Install dependencies using pnpm install.
    3. Create an R2 bucket named turborepo-cache for artifact storage.
    4. Deploy the project using pnpm run deploy.
    5. Set a Bearer authentication token using pnpm wrangler secret put TURBO_TOKEN.
    # 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

  10. Configure Turborepo environment variables in `.env`

    master

    The following environment variables are required for the remote cache to function correctly. Ensure they are placed in a .env file at your project root.

    VariableRequirement
    TURBO_APIMust not end with a trailing slash
    TURBO_TEAMMust begin with team_
    TURBO_TOKENMust be a valid Bearer auth token
    TURBO_REMOTE_CACHE_SIGNATURE_KEYSecret key for signature validation
    TURBO_API=YOUR_API_URL
TURBO_TEAM=team_my_team_name
TURBO_TOKEN=SECRET
TURBO_REMOTE_CACHE_SIGNATURE_KEY=SECRET

  11. Configure automatic deletion of old cache files

    master

    The project includes a Cloudflare Workers cron trigger that automatically deletes old cache files from your R2 bucket to manage storage.

    You can customize this behavior in two ways:

    1. To disable automatic deletion: Remove the triggers configuration from your wrangler.jsonc file.
    2. To change the retention period: Adjust the BUCKET_OBJECT_EXPIRATION_HOURS setting. This can be done by modifying the value in wrangler.jsonc or by setting the BUCKET_OBJECT_EXPIRATION_HOURS environment variable in your Cloudflare Workers configuration.

  12. Configure Cloudflare KV in wrangler.jsonc

    master

    After creating a KV namespace, you must bind it to your Worker by updating your wrangler.jsonc configuration file.

    Important: If you are switching to KV storage, ensure that the r2_buckets section is commented out to avoid conflicts.

    {
  "name": "turborepo-remote-cache",
  // Other settings...

  // "r2_buckets": [
  //   {
  //     "binding": "R2_STORE",
  //     "bucket_name": "turborepo-cache",
  //     "preview_bucket_name": "turborepo-cache-preview"
  //   }
  // ],
  "kv_namespaces": [
    {
      "binding": "KV_STORE",
      "id": "ea20b0eb60f44b13b8d013eeace98ca2",
      "preview_id": "ea20b0eb60f44b13b8d013eeace98ca2"
    }
  ]
}