Performance

What is optimized

The current 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 and should stay 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 flag when you know you are doing a local iterative rebuild and 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 when 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

That lets the builder narrow component rebuild work to affected registry items instead of checking every generated payload equally.

Parallelism

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

Override it with:

performance: {
  parallelism: 6,
}

performance: {
  parallelism: 6,
}

Use a lower number if your workspace lives on slower storage or if the generated outputs compete with another heavy process.

When files are rewritten

The builder rewrites files only when their generated content changes.

That 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 should usually show Files as - for every phase.

Turning incremental mode off

performance: {
  incremental: false,
}

performance: {
  incremental: false,
}

Do that only when you need to debug cache behavior or compare with a fully uncached build. The normal default should stay on.

Troubleshooting