Cache & Environment
How Boltdocs caching works, what gets cached, and the environment variables that control it.
Boltdocs caches parsed files and transformations so subsequent builds and dev server restarts are fast. This guide covers how caching works and how to configure it.
Cache Behavior
Development Mode
- Cache is loaded at startup for instant navigation
- Files are watched — changes invalidate relevant cache entries
- Full rebuild only when the configuration 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 cache behavior through environment variables:
| Variable | Type | Default | Description |
|---|---|---|---|
BOLTDOCS_CACHE_DIR | string | .boltdocs/cache | Directory for main processing cache files |
BOLTDOCS_NO_CACHE | boolean | false | Set to 1 to disable all caching |
BOLTDOCS_CACHE_LRU_LIMIT | number | 2000 | Maximum entries in the 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 cache options, Boltdocs resolves integration-specific keys from your environment variables safely:
| 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 owner username or organization of the target repository. |
BOLTDOCS_GITHUB_REPO_NAME | Custom Feedback | Overrides the name of the target repository. |
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 is invalidated automatically when:
- The file content changes — Detected via content hash
- The file is deleted — Cache entry removed
- The configuration changes — Full invalidation triggered
- The plugin version changes — MDX cache invalidated
Manual Invalidation
Delete the cache directory:
rm -rf .boltdocs
Or in development, the dev server invalidates automatically on file changes.
Cache Location
By default, the cache lives in .boltdocs/ at the root of your project:
my-docs/
├── .boltdocs/
│ ├── build/
│ │ ├── framework-hash.txt
│ │ ├── template-index.html
│ │ ├── render-cache.json
│ │ └── pages/ ← cached HTML per page
│ ├── cache/
│ │ ├── parser/ ← Parser results (JSON)
│ │ ├── mdx/ ← Compiled MDX 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
Corrupted cache
If you suspect corrupted cache entries:
# Clear all caches
rm -rf .boltdocs
# Restart dev server
pnpm docs:dev
Stale content in production
Make sure your CI pipeline starts clean:
# 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 — the cache is being populated
- Subsequent startups are nearly instant (< 100ms)
- The more pages you have, the more the cache helps
- Cache compression adds ~10% CPU overhead but saves ~70% disk
