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

export const config: VercelConfig = {
  buildCommand: 'npm run build',
  framework: 'nextjs',

  rewrites: [
    // Simple rewrite
    routes.rewrite('/api/(.*)', 'https://backend.api.example.com/$1'),

    // Rewrite with transforms (no path params)
    routes.rewrite('/(.*)', 'https://api.example.com/$1', {
      requestHeaders: {
        authorization: `Bearer ${deploymentEnv('API_TOKEN')}`,
      },
    }),

    // Type-safe path parameters with callback
    routes.rewrite(
      '/users/:userId/posts/:postId',
      'https://api.example.com/users/$1/posts/$2',
      ({ userId, postId }) => ({
        requestHeaders: {
          'x-user-id': userId,
          'x-post-id': postId,
          authorization: `Bearer ${deploymentEnv('API_KEY')}`,
        },
      })
    ),
  ],

  redirects: [routes.redirect('/old-docs', '/docs', { permanent: true })],

  headers: [
    routes.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
• Type-safe path parameters - Extract :userId from patterns with full IntelliSense
• Deployment environment variables - Use deploymentEnv() for Vercel project env vars
• Readable syntax - Helper methods like routes.redirect(), routes.rewrite(), routes.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