@vercel/config

@vercel/config

TypeScript SDK for programmatically defining Vercel configuration. Write type-safe routing rules and build configuration in TypeScript instead of JSON.

Installation

npm install @vercel/config

Quick Start

Create a vercel.ts file in your project root:

import { createRouter, VercelConfig } from '@vercel/config/v1';

const router = createRouter();

export const config: VercelConfig = {
  buildCommand: 'npm run build',
  framework: 'nextjs',
  
  routes: [
    // Headers
    router.cacheControl('/static/(.*)', {
      public: true,
      maxAge: '1 week',
      immutable: true
    }),
    
    // Rewrites with transforms
    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', 
      ({ userId, env }) => ({
        requestHeaders: {
          'x-user-id': userId,
          'authorization': `Bearer ${env.API_TOKEN}`
        }
      })
    ),
    
    // Simple redirects
    router.redirect('/old-docs', '/docs', { permanent: true })
  ],

  crons: [
    { path: '/api/cleanup', schedule: '0 0 * * *' }
  ]
};

Features

• Type-safe configuration - Full TypeScript support with IDE autocomplete
• Readable syntax - Helper methods like router.redirect(), router.rewrite(), router.header()
• Static validation - Catch configuration errors at development time
• Transforms - Modify request/response headers and query parameters on the fly
• Conditions - Advanced routing with has and missing conditions
• CLI tools - compile and validate commands for development

Build-Time Compilation

Your vercel.ts is automatically compiled to vercel.json during:

vercel build
vercel dev
vercel deploy

No manual build step needed - the Vercel CLI handles compilation automatically.

CLI Commands

For development and validation:

# Compile vercel.ts to JSON (output to stdout)
npx @vercel/config compile

# Validate config for errors and show summary
npx @vercel/config validate

# Generate vercel.json locally (for development)
npx @vercel/config generate

Validation

Static fields are validated to ensure they only contain literal values (strings, booleans, objects with primitives):

// ✅ Valid - static string
export const buildCommand = 'npm run build';

// ❌ Invalid - computed value
export const buildCommand = process.env.BUILD_CMD;

// ✅ Valid - static object
export const git = {
  deploymentEnabled: {
    'main': true,
    'dev': false
  }
};

Static fields that are validated:

• buildCommand, devCommand, installCommand
• framework, nodeVersion, outputDirectory
• github.enabled, github.autoAlias, github.autoJobCancelation
• git.deploymentEnabled
• relatedProjects

Important Notes

• One config file only: You cannot have both vercel.ts and vercel.json. The build will fail if both exist.

• Versioned API: Use @vercel/config/v1 for imports to enable future versioning.

Learn More

• Vercel Configuration Documentation
• Routing Documentation