Cache Management

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

Capabilities

Prepare Cache Function

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

/**
 * Prepares cache files for subsequent builds to improve performance
 * @param options - Cache preparation configuration
 * @returns Promise resolving to Files object containing cache entries
 */
function prepareCache(options: PrepareCacheOptions): Promise<Files>;

interface PrepareCacheOptions {
  /** Downloaded files from the deployment */
  files: Files;
  /** Entry point file (typically package.json) */
  entrypoint: string;
  /** Repository root path (required for monorepos) */
  repoRootPath: string;
  /** Working directory path */
  workPath: string;
  /** Build configuration */
  config: Config;
}

Usage Examples:

import { prepareCache } from "@vercel/static-build";
import type { Files, Config, PackageJson, Framework } from "@vercel/build-utils";

// Type definitions
interface Files {
  [filePath: string]: File;
}

interface File {
  mode: number;
  contentType?: string;
  toStream: () => NodeJS.ReadableStream;
  toStreamAsync?: () => Promise<NodeJS.ReadableStream>;
}

interface Framework {
  slug: string;
  dependency?: string;
  cachePattern?: string | string[];
  name: string;
  // ... other framework properties
}

// Basic cache preparation
const cacheFiles = await prepareCache({
  files: inputFiles,
  entrypoint: "package.json",
  repoRootPath: "/build/repo",
  workPath: "/build/workspace",
  config: {
    zeroConfig: true
  }
});

// Cache preparation with repository root
const cacheFilesMonorepo = await prepareCache({
  files: projectFiles,
  entrypoint: "packages/frontend/package.json",
  repoRootPath: "/build/repo",
  workPath: "/build/repo/packages/frontend",  
  config: {
    framework: "nextjs"
  }
});

console.log(Object.keys(cacheFiles)); // Array of cached file paths

Cache Strategy Priority

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

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

Build Output V3 Cache

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

interface BuildOutputV3Config {
  cache?: string[];
}

Example v3 cache configuration:

{
  "cache": [
    "node_modules/**",
    ".next/cache/**",
    ".vercel/cache/**"
  ]
}

Build Output V1 Cache

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

interface BuildConfig {
  cache: string[];
}

Example v1 cache configuration:

{
  "cache": [
    "node_modules/**",
    "dist/.cache/**",
    ".nuxt/**"
  ]
}

Framework-Specific Caching

Different frameworks have optimized cache patterns for their build artifacts:

Next.js:

// Caches .next/cache for build optimization
cachePattern: ".next/cache/**"

Nuxt.js:

// Caches .nuxt directory for module resolution
cachePattern: ".nuxt/**"

Gatsby:

// Caches .cache and public directories
cachePattern: [".cache/**", "public/**"]

Vue CLI:

// Caches node_modules for dependency resolution
cachePattern: "node_modules/**"

Default Cache Patterns

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

const defaultCachePatterns = [
  "**/{.shadow-cljs,node_modules}/**"
];

Default cache includes:

• node_modules/** - JavaScript dependencies
• .shadow-cljs/** - ClojureScript build cache
• Framework detection based cache patterns

Cache File Processing

The cache preparation process:

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

Framework Detection for Caching

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

/**
 * Detects framework from package.json and config
 * @param config - Build configuration
 * @param pkg - Package.json contents
 * @returns Detected framework or undefined
 */
function getFramework(
  config: Config | null, 
  pkg?: PackageJson | null
): Framework | undefined;

Framework detection for caching:

1. Only works when config.zeroConfig is true
2. Only works when entrypoint basename is 'package.json'
3. Reads package.json from entrypoint directory
4. Checks config.framework for manual override
5. Matches dependencies against known framework patterns
6. Applies framework's cachePattern if available

Cache Optimization Benefits

Proper caching provides significant performance improvements:

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

Typical cache hit improvements:

• Node.js projects: 50-80% faster builds
• Large dependencies: 90%+ improvement in install time
• Framework builds: 30-60% faster compilation
• Monorepos: Significant improvement in changed package detection