Static Site Generators in Production

Remote Caching with Turborepo for SSG Monorepos

A monorepo with several static sites and shared packages builds the same things over and over. The design-token package is compiled on every CI run even though it changed last month. The blog is rebuilt on a colleague's laptop after they pulled a change that only touched the docs. Two pull requests that differ only in a README both rebuild all three sites.

Turborepo removes that repetition. It hashes each task's inputs, stores the outputs under that hash, and replays them instantly the next time any machine runs the same task with the same inputs. With a remote cache, a build done once in CI is reused by every other run and every developer. This guide sets it up for a static-site monorepo, configures inputs and outputs correctly for site builds, and debugs cache misses. It is part of Incremental Builds and Build Caching for SSGs.

Prerequisites

  • A workspace monorepo (npm, pnpm, Yarn or Bun) with sites under sites/ and shared code under packages/.
  • Node.js 20 or later.
  • A remote cache: Vercel's hosted cache, or a self-hosted server on S3, R2 or similar storage.

How Task Hashing Works

Turborepo treats each package#task pair — docs#build, ui#build — as a unit. Before running it, Turborepo computes a hash from everything that could affect its output. If the hash is in the local or remote cache, it restores the recorded outputs and logs and skips the task.

Inputs to a Turborepo task hash and the cache lookup The hash for docs#build combines the docs source files, the hash of ui#build, lockfile entries for its dependencies, declared environment variables and the turbo.json task definition. The hash is looked up in the local cache, then the remote cache. A hit restores dist and logs; a miss runs the build and uploads the result. docs#build: hash, then look up hash inputs sites/docs source files hash of ui#build, tokens#build lockfile entries used env: SITE_URL, CMS_ENV turbo.json task config not the date, not the machine hash 9f3c…e1 hit (local or remote) restore dist/ and logs seconds miss run build, save, upload minutes, once
Because dependency hashes feed into the site's hash, a change to a shared package invalidates exactly the sites that use it.

Configuring turbo.json

Install Turborepo at the root (npm install -D turbo) and add a turbo.json:

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.test.*"],
      "outputs": ["dist/**", ".output/public/**"],
      "env": ["SITE_URL", "CMS_ENV", "PUBLIC_*"]
    },
    "check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
  • dependsOn: ["^build"] builds a package's workspace dependencies first and includes their hashes in its own.
  • inputs starts from the default (all files in the package tracked by Git) and removes files that do not affect the build. Excluding READMEs and tests stops documentation edits from invalidating the build.
  • outputs lists what to cache and restore. For static sites, that is the build output folder; list every generator's folder if sites differ.
  • env declares environment variables that change the output. Any variable used at build time but not listed here is a source of wrong cache hits — a production build restored into a preview, for instance.

Run npx turbo run build from the root. The first run builds everything; the second, with nothing changed, finishes in under a second with "FULL TURBO" and every task marked as a cache hit.

Turning On the Remote Cache

Local caching helps one machine. The remote cache shares results across CI runs and developers. With Vercel's hosted cache, run npx turbo login and npx turbo link locally, and in CI set two variables:

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with: { node-version-file: .nvmrc, cache: npm }
  - run: npm ci
  - run: npx turbo run build check --affected

To self-host, run one of the open-source cache servers that implement Turborepo's HTTP API in front of an S3 or Cloudflare R2 bucket, and set TURBO_API to its URL along with a token. Keep artifact signing on ("remoteCache": { "signature": true } with TURBO_REMOTE_CACHE_SIGNATURE_KEY) so a compromised cache cannot inject build output.

--affected limits the run to packages changed compared with the base branch and their dependents, which pairs naturally with the per-site deploys in Matrix Builds for Multi-Site Monorepos.

What Stays Outside the Turborepo Cache

Turborepo caches a task's declared outputs. It does not know about generator-internal caches like Astro's node_modules/.astro or Hugo's resources/_gen. A cache hit makes those irrelevant, because the build does not run. A miss, though, runs the build from scratch unless those caches are also restored. Keep the generator cache step from Building Astro Sites with GitHub Actions alongside Turborepo: the remote cache handles "nothing changed in this site", the generator cache makes "one page changed" fast.

CI build step time by kind of change Without Turborepo, every change took 11 minutes to build three sites. With a remote cache: a README-only change took 20 seconds, a change to one site took 3 minutes 10 seconds, and a change to the shared ui package took 6 minutes 40 seconds because two sites rebuilt. Build step duration by kind of change before: any change 11:00 README only 0:20 one site's content 3:10 shared ui package 6:40 three sites, two shared packages; remote cache on Cloudflare R2
Build time now follows the size of the change rather than the size of the repository.

Deploying From Cache Hits

A cache hit restores the site's dist folder exactly as the original build produced it, so the deploy step does not need to know whether the build ran. That is convenient, and it raises one question: should an unchanged site be redeployed at all? Usually not. Combine --affected or a per-site change check with the deploy step, and skip deploying sites whose build was a cache hit from a previous commit already in production. The site's output is byte-for-byte what is live, and redeploying it only adds noise to the deploy history and purges CDN caches for nothing.

Where a platform requires a deploy on every commit — some preview systems do — the restored output makes that deploy fast, because the upload step sends only changed files and nothing changed.

Treat remote cache storage like any other build infrastructure. Set a retention policy on the bucket so old artifacts expire after a few weeks, restrict write access to CI, and give developers a read-only token so a local experiment cannot poison the shared cache.

Debugging Cache Misses

A cache that misses when it should hit wastes time; one that hits when it should miss ships wrong output. Both come from the hash inputs. Turborepo shows what went into every hash:

  • npx turbo run build --dry=json prints each task's hash and its inputs without running anything.
  • npx turbo run build --summarize writes a run summary to .turbo/runs/ listing hashes, cache status and the environment variables that were included.

Compare two summaries from runs that should have matched. Typical culprits:

  1. Undeclared environment variables. A variable read by the build but missing from env is ignored in the hash. Turborepo's strict environment mode (the default) removes undeclared variables from the task's environment, which surfaces these as build errors rather than wrong hits.
  2. Generated files in inputs. A build that writes a timestamp or a sitemap into the source tree changes its own inputs; exclude generated paths or write them to the output folder.
  3. Lockfile churn. Reinstalling with a different package manager version can rewrite lockfile entries and invalidate everything.
Causes of unexpected cache misses found in run summaries In the first month, unexpected misses were caused by a build timestamp written into a source file in 9 cases, by an undeclared environment variable in 5 cases, and by lockfile changes from a different npm version in 3 cases. Unexpected misses in the first month, by cause timestamp in a source file 9 undeclared env variable 5 lockfile rewritten 3 each found by diffing two --summarize outputs
Every miss had a concrete cause in the hash inputs; none was random.

Measured Impact

A monorepo with an Astro docs site, an Eleventy blog, an Astro marketing site and two shared packages added Turborepo with a self-hosted remote cache on Cloudflare R2. Before, every CI run built all three sites in about eleven minutes. Afterwards, README and configuration-only changes finished in about 20 seconds, single-site content changes in about three minutes, and shared UI changes in under seven. Developers pulling main got cached builds for sites they had not touched, cutting local turbo run build from minutes to seconds. Monthly CI minutes fell by 58%.

Pitfalls & Rollback

  • Missing outputs. A hit restores nothing and the deploy step finds an empty folder; list every output directory.
  • Caching dev or deploy tasks. Only cache pure build and check tasks; mark others cache: false.
  • Unsigned remote artifacts. Turn on signatures so the cache cannot be used to inject output.
  • Secrets in logs. Cached logs are replayed on hits; keep secrets out of build output.
  • Rollback: run tasks with --force to bypass the cache, or remove TURBO_TOKEN to fall back to local caching.

Conclusion

Turborepo makes a static-site monorepo build only what changed: each task is hashed from its files, dependencies, lockfile entries and declared environment, and outputs are restored from a local or remote cache on a match. Declare inputs, outputs and environment variables carefully, share a signed remote cache between CI and developers, keep generator caches for the builds that do run, and use run summaries to explain every miss.

FAQ

What does Turborepo's remote cache store?

The outputs of each task - such as a site's dist folder - and its terminal logs, keyed by a hash of the task's inputs. When any machine runs the same task with the same inputs, Turborepo downloads the outputs instead of running the task.

What goes into a Turborepo task hash?

The files in the package that the task's inputs setting covers, the hashes of its internal dependencies' tasks, the lockfile entries for its external dependencies, declared environment variables and the task configuration itself. Change any of them and the hash changes.

Can I self-host a Turborepo remote cache?

Yes. Turborepo speaks a documented HTTP API, and open-source servers implement it on top of S3, Cloudflare R2, Google Cloud Storage or a local disk. Point turbo at it with the API URL, team and token settings.

Why does my Turborepo cache miss when nothing changed?

Usually because an input outside the declared ones varies between runs - an environment variable not listed in env, a timestamp written into a generated file, or build output accidentally included in inputs. The --summarize flag and turbo run --dry show exactly what went into each hash.