Performance

What is optimized

The performance model focuses on five things:

1. file-hash caching
2. skip writing identical files
3. incremental index and component rebuilds
4. bounded concurrent work
5. changed-only local rebuild mode

Cache location

By default, the builder writes cache state to:

<output.dir>/.registry-build/build-cache.json

<output.dir>/.registry-build/build-cache.json

Override it with:

performance: {
  cacheDir: '.registry-build',
}

performance: {
  cacheDir: '.registry-build',
}

The cache directory is local build state — keep it ignored by Git.

How warm builds work

On warm runs the builder:

• Reuses cached file hashes when mtime and size are unchanged.
• Reuses cached index entries when signatures match.
• Reuses cached component payload decisions when signatures match.
• Skips component-index and colors writes when generated output is unchanged.
• Removes stale generated files when previous outputs disappear from the current build.

--changed-only

Use this for local iterative rebuilds when you want the builder to lean on the cache aggressively:

registry-build build --changed-only

registry-build build --changed-only

Pair it with explicit changed paths if you know which files moved:

registry-build build --changed-only --changed ../../packages/registry-ui/src/button/button.tsx

registry-build build --changed-only --changed ../../packages/registry-ui/src/button/button.tsx

The builder then narrows component rebuild work to affected registry items instead of checking every generated payload.

Parallelism

The builder uses bounded concurrency for discovery and generation. Default: Math.max(1, Math.min(cpuCount, 8)) — CPU-aware, capped at 8.

Override it with:

performance: {
  parallelism: 6,
}

performance: {
  parallelism: 6,
}

Lower it if the workspace lives on slower storage or if generated outputs compete with another heavy process.

When files are rewritten

The builder rewrites files only when generated content changes.

This applies to:

• index.json
• per-item component JSON files
• generated component index files
• colors/theme JSON files
• generated themes.css

On a true no-op warm build, the summary table usually shows Files as - for every phase.

Turning incremental mode off

performance: {
  incremental: false,
}

performance: {
  incremental: false,
}

Only do this to debug cache behavior or compare against a fully uncached build. Otherwise leave it on.

Troubleshooting