0
# Cache Management
1

2
Cache preparation functionality for optimizing build performance across deployments with framework-specific caching strategies and Build Output API support.
3

4
## Capabilities
5

6
### Prepare Cache Function
7

8
Prepares cache files for subsequent builds, improving build performance by preserving dependencies and build artifacts.
9

10
```typescript { .api }
11
/**
12
 * Prepares cache files for subsequent builds to improve performance
13
 * @param options - Cache preparation configuration
14
 * @returns Promise resolving to Files object containing cache entries
15
 */
16
function prepareCache(options: PrepareCacheOptions): Promise<Files>;
17

18
interface PrepareCacheOptions {
19
  /** Downloaded files from the deployment */
20
  files: Files;
21
  /** Entry point file (typically package.json) */
22
  entrypoint: string;
23
  /** Repository root path (required for monorepos) */
24
  repoRootPath: string;
25
  /** Working directory path */
26
  workPath: string;
27
  /** Build configuration */
28
  config: Config;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { prepareCache } from "@vercel/static-build";
36
import type { Files, Config, PackageJson, Framework } from "@vercel/build-utils";
37

38
// Type definitions
39
interface Files {
40
  [filePath: string]: File;
41
}
42

43
interface File {
44
  mode: number;
45
  contentType?: string;
46
  toStream: () => NodeJS.ReadableStream;
47
  toStreamAsync?: () => Promise<NodeJS.ReadableStream>;
48
}
49

50
interface Framework {
51
  slug: string;
52
  dependency?: string;
53
  cachePattern?: string | string[];
54
  name: string;
55
  // ... other framework properties
56
}
57

58
// Basic cache preparation
59
const cacheFiles = await prepareCache({
60
  files: inputFiles,
61
  entrypoint: "package.json",
62
  repoRootPath: "/build/repo",
63
  workPath: "/build/workspace",
64
  config: {
65
    zeroConfig: true
66
  }
67
});
68

69
// Cache preparation with repository root
70
const cacheFilesMonorepo = await prepareCache({
71
  files: projectFiles,
72
  entrypoint: "packages/frontend/package.json",
73
  repoRootPath: "/build/repo",
74
  workPath: "/build/repo/packages/frontend",  
75
  config: {
76
    framework: "nextjs"
77
  }
78
});
79

80
console.log(Object.keys(cacheFiles)); // Array of cached file paths
81
```
82

83
### Cache Strategy Priority
84

85
The cache preparation follows this priority order (each returns immediately if found):
86

87
1. **Build Output API v3**: Uses `config.json` cache configuration (returns early if found)
88
2. **Build Output API v1**: Uses `build.json` cache configuration (returns early if found)
89
3. **Default patterns applied first**: Always applies `**/{.shadow-cljs,node_modules}/**`
90
4. **Framework-specific patterns applied additively**: Framework cache patterns are added to defaults
91

92
### Build Output V3 Cache
93

94
For projects using Build Output API v3, cache files are determined by the `config.json` file:
95

96
```typescript { .api }
97
interface BuildOutputV3Config {
98
  cache?: string[];
99
}
100
```
101

102
**Example v3 cache configuration:**
103

104
```json
105
{
106
  "cache": [
107
    "node_modules/**",
108
    ".next/cache/**",
109
    ".vercel/cache/**"
110
  ]
111
}
112
```
113

114
### Build Output V1 Cache
115

116
For projects using Build Output API v1, cache files are specified in `build.json`:
117

118
```typescript { .api }
119
interface BuildConfig {
120
  cache: string[];
121
}
122
```
123

124
**Example v1 cache configuration:**
125

126
```json
127
{
128
  "cache": [
129
    "node_modules/**",
130
    "dist/.cache/**",
131
    ".nuxt/**"
132
  ]
133
}
134
```
135

136
### Framework-Specific Caching
137

138
Different frameworks have optimized cache patterns for their build artifacts:
139

140
**Next.js**:
141
```typescript
142
// Caches .next/cache for build optimization
143
cachePattern: ".next/cache/**"
144
```
145

146
**Nuxt.js**:
147
```typescript  
148
// Caches .nuxt directory for module resolution
149
cachePattern: ".nuxt/**"
150
```
151

152
**Gatsby**:
153
```typescript
154
// Caches .cache and public directories
155
cachePattern: [".cache/**", "public/**"]
156
```
157

158
**Vue CLI**:
159
```typescript
160
// Caches node_modules for dependency resolution
161
cachePattern: "node_modules/**"
162
```
163

164
### Default Cache Patterns
165

166
When no specific cache configuration is found, default patterns are applied:
167

168
```typescript
169
const defaultCachePatterns = [
170
  "**/{.shadow-cljs,node_modules}/**"
171
];
172
```
173

174
**Default cache includes:**
175
- `node_modules/**` - JavaScript dependencies
176
- `.shadow-cljs/**` - ClojureScript build cache
177
- Framework detection based cache patterns
178

179
### Cache File Processing
180

181
The cache preparation process:
182

183
1. **Detects Build Output API version** (v3, v1, or none)
184
2. **Reads cache configuration** from appropriate config files
185
3. **Applies framework-specific patterns** if detected
186
4. **Falls back to default patterns** if no configuration found
187
5. **Globs files** matching cache patterns
188
6. **Returns Files object** with cache entries
189

190
### Framework Detection for Caching
191

192
Cache preparation uses the same framework detection as the build function:
193

194
```typescript { .api }
195
/**
196
 * Detects framework from package.json and config
197
 * @param config - Build configuration
198
 * @param pkg - Package.json contents
199
 * @returns Detected framework or undefined
200
 */
201
function getFramework(
202
  config: Config | null, 
203
  pkg?: PackageJson | null
204
): Framework | undefined;
205
```
206

207
**Framework detection for caching:**
208
1. Only works when `config.zeroConfig` is true
209
2. Only works when entrypoint basename is `'package.json'`
210
3. Reads `package.json` from entrypoint directory
211
4. Checks `config.framework` for manual override
212
5. Matches dependencies against known framework patterns
213
6. Applies framework's `cachePattern` if available
214

215
### Cache Optimization Benefits
216

217
Proper caching provides significant performance improvements:
218

219
- **Dependency Installation**: Skip reinstalling unchanged dependencies
220
- **Build Artifacts**: Reuse compiled assets and intermediate files
221
- **Framework Cache**: Preserve framework-specific optimization data
222
- **Module Resolution**: Cache resolved module paths and compilation results
223

224
**Typical cache hit improvements:**
225
- Node.js projects: 50-80% faster builds
226
- Large dependencies: 90%+ improvement in install time
227
- Framework builds: 30-60% faster compilation
228
- Monorepos: Significant improvement in changed package detection