@vercel/config

@vercel/config

TypeScript SDK for defining Vercel configuration programmatically.

Installation

npm install @vercel/config

Usage

Create a vercel.ts file in your project root:

import { createRouter } from '@vercel/config';

const router = createRouter();

// Basic rewrite
router.rewrite('/api/(.*)', 'https://backend.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 });

// Cache control
router.cacheControl('/static/(.*)', {
  public: true,
  maxAge: '1week',
  immutable: true
});

// Global settings
router.cleanUrls = true;
router.trailingSlash = true;

// Bulk redirects
router.bulkRedirectsPath = './bulkRedirectsDemo.json';

// Cron jobs
router.cron('/api/cleanup', '0 0 * * *');

export default router.getConfig();

Automatic Compilation

Your vercel.ts file is automatically compiled when you run:

vercel build   # For local builds
vercel dev     # For local development  
vercel deploy  # For deployment

The Vercel CLI automatically compiles vercel.ts to .vercel/vercel.json before building or deploying.

API Reference

createRouter()

Creates a new router instance.

router.rewrite(source, destination, options?)

Add a rewrite rule. Options can be an object or a callback function that receives path parameters and environment variables.

// With callback for transforms
router.rewrite('/users/:userId', 'https://api.example.com/users/$1', ({userId, env}) => ({
  requestHeaders: {
    'x-user-id': userId,
    'authorization': `Bearer ${env.API_TOKEN}`
  },
  responseHeaders: {
    'x-powered-by': 'My API'
  },
  requestQuery: {
    'version': '2.0'
  }
}));

// Simple rewrite without transforms
router.rewrite('/api/(.*)', 'https://backend.com/$1');

router.redirect(source, destination, options?)

Add a redirect rule. Options include permanent and statusCode.

router.redirect('/old-page', '/new-page', { permanent: true });
router.redirect('/temp', '/elsewhere', { statusCode: 302 });

router.header(source, headers, options?)

Add custom headers for a path pattern.

router.header('/api/(.*)', [
  { key: 'X-Custom-Header', value: 'value' }
]);

router.cacheControl(source, options)

Set cache control headers. Options include public, private, maxAge, sMaxAge, immutable, etc.

router.cacheControl('/static/(.*)', {
  public: true,
  maxAge: '1week',
  immutable: true
});

router.cleanUrls

Set whether to enable clean URLs (removes file extensions).

router.cleanUrls = true;

router.trailingSlash

Set whether to normalize paths to include trailing slashes.

router.trailingSlash = true;

router.bulkRedirectsPath

Set the path to a bulk redirects JSON file.

router.bulkRedirectsPath = './bulkRedirectsDemo.json';

Important Notes

• One config file only: You cannot have both vercel.ts and vercel.json. The build will fail if both exist.
• Automatic gitignore: The generated .vercel/vercel.json file is automatically ignored by git (in the .vercel/ directory).
• No manual compilation needed: The Vercel CLI handles compilation automatically - no need to run a separate command.

Learn More

• Vercel Configuration Documentation
• Routing Documentation