Cache & Environment

Boltdocs caches parsed files and transformations to make subsequent builds and dev server restarts fast. This guide covers how the cache works and how to configure it.

How Caching Works

Boltdocs uses a multi-layer caching system:

Memory LRU Cache — Fast in-process cache for hot data
Disk Cache — Persisted to .boltdocs/ directory (organized under .boltdocs/cache/, .boltdocs/build/, .boltdocs/generated/, .boltdocs/reports/) for reuse across restarts
Invalidation — Automatic based on file mtime and content hash

What Gets Cached

Cache Type	What's Stored	Location
Parser Cache	Frontmatter, headings, metadata for each `.md`/`.mdx` file	`.boltdocs/cache/parser/`
MDX Transform	Compiled MDX code for each file	`.boltdocs/cache/mdx/`
Route Cache	Built route objects with all metadata	`.boltdocs/cache/routes/`

Cache Behavior

Development Mode

Cache is loaded on startup for instant navigation
Files are watched — changes invalidate relevant cache entries
Full rebuild only when config or plugins change

Production Build

Cold start builds from scratch
Cache written to disk for future use
CI/CD environments get consistent builds

Environment Variables

Configure caching behavior via environment variables:

Variable	Type	Default	Description
`BOLTDOCS_CACHE_DIR`	`string`	`.boltdocs/cache`	Directory for core processing cache files
`BOLTDOCS_NO_CACHE`	`boolean`	`false`	Set to `1` to disable all caching
`BOLTDOCS_CACHE_LRU_LIMIT`	`number`	`2000`	Max entries in memory LRU cache
`BOLTDOCS_CACHE_LRU_TTL`	`number`	`14400000`	TTL in ms (default 4 hours)
`BOLTDOCS_CACHE_COMPRESS`	`boolean`	`true`	Enable gzip compression for cache files

Integration Environment Variables

In addition to caching options, Boltdocs resolves integration-specific keys from your environment variables securely:

Variable	Scope	Description
`BOLTDOCS_GITHUB_TOKEN`	Custom Feedback	A personal access token (PAT) with write access to GitHub Discussions.
`BOLTDOCS_GITHUB_REPO_OWNER`	Custom Feedback	Overrides the target repository owner username or organization.
`BOLTDOCS_GITHUB_REPO_NAME`	Custom Feedback	Overrides the target repository name.
`GITHUB_APP_ID`	GitHub App Auth	The unique App ID generated by your GitHub App.
`GITHUB_PRIVATE_KEY`	GitHub App Auth	The RSA private key of the GitHub App.
`GITHUB_INSTALLATION_ID`	GitHub App Auth	The installation ID associated with your target repository.

Usage Examples

# Disable all caching (useful for debugging)
BOLTDOCS_NO_CACHE=1 pnpm docs:dev

# Use custom cache directory
BOLTDOCS_CACHE_DIR=.cache/boltdocs pnpm docs:dev

# Increase cache size for large projects
BOLTDOCS_CACHE_LRU_LIMIT=5000 pnpm docs:dev

Cache Invalidation

The cache automatically invalidates when:

File content changes — Detected via content hash
File is deleted — Cache entry removed
Config changes — Full invalidation triggered
Plugin version changes — MDX cache invalidated

Manual Invalidation

Delete the cache directory:

rm -rf .boltdocs

Or in development, the dev server auto-invalidates on file changes.

Cache Location

By default, cache lives in .boltdocs/ at your project root:

my-docs/
├── .boltdocs/
│   ├── build/
│   │   ├── framework-hash.txt
│   │   ├── template-index.html
│   │   ├── render-cache.json
│   │   └── pages/         ← Per-page cached HTML
│   ├── cache/
│   │   ├── parser/        ← Parser results (JSON)
│   │   ├── mdx/           ← MDX compiled code
│   │   ├── routes/        ← Route metadata
│   │   └── assets/        ← Processed assets
│   ├── generated/
│   │   ├── types.d.ts
│   │   └── link-tree.json
│   ├── reports/
│   │   ├── doctor.json
│   │   └── performance.json
│   └── backups/           ← Doctor fix backups
├── docs/
└── boltdocs.config.ts

Troubleshooting

Cache corruption

If you suspect corrupted cache entries:

# Clear all caches
rm -rf .boltdocs

# Restart dev server
pnpm docs:dev

Stale content in production

Ensure your CI pipeline starts fresh:

# Clean before build
rm -rf .boltdocs
pnpm docs:build

Large cache size

For very large documentation sites:

# Disable compression to save CPU at the cost of disk space
BOLTDOCS_CACHE_COMPRESS=0 pnpm docs:build

Performance Notes

First startup is slower — cache is being populated
Subsequent startups are near-instant (< 100ms)
The more pages you have, the more cache helps
Cache compression adds ~10% CPU overhead but saves ~70% disk

Last updated on July 27, 2026

Was this page helpful?