@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 } from '@vercel/config';
import type { VercelConfig } from '@vercel/config';

const router = createRouter();

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

  headers: [
    router.cacheControl('/static/(.*)', {
      public: true,
      maxAge: '1 week',
      immutable: 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()
• 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

Important Notes

• One config file only: You cannot have both vercel.ts and vercel.json.
• Transforms compile to routes: When you add transforms to rewrites/redirects (like requestHeaders), they're compiled to the lower-level routes primitive internally.
• Automatic compilation: The Vercel CLI compiles vercel.ts automatically.

Learn More

• Vercel Configuration Documentation
• Routing Documentation