TemperStack
Find Tools
Intermediate8 min readUpdated Mar 18, 2026

How to configure custom routing with config json on Vercel

Quick Answer

Custom routing on Vercel is configured using a vercel.json file in your project root with routes array containing source patterns and destination targets. The configuration supports redirects, rewrites, headers, and dynamic routing patterns for full control over request handling.

Prerequisites

  1. Basic knowledge of JSON syntax
  2. Existing Vercel project or account
  3. Understanding of HTTP routing concepts
  4. Node.js project with package.json
1

Create vercel.json configuration file

Create a vercel.json file in your project root directory. This file will contain all your custom routing configuration:

{
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    }
  ]
}

The routes array is where you'll define all your custom routing rules.
Tip
Always validate your JSON syntax before deploying to avoid configuration errors.
2

Configure route patterns with source matching

Define your route patterns using the src property with regular expressions. Common patterns include:

{
  "routes": [
    {
      "src": "/blog/(.*)",
      "dest": "/blog.html?slug=$1"
    },
    {
      "src": "/api/users/([^/]+)",
      "dest": "/api/users.js?id=$1"
    }
  ]
}

Use (.*) for catch-all patterns and ([^/]+) for single segments.
Tip
Test your regex patterns online before implementing to ensure they match your expected URLs.
3

Set up redirects and rewrites

Configure different types of routing behavior using additional properties:

{
  "routes": [
    {
      "src": "/old-page",
      "status": 301,
      "headers": { "Location": "/new-page" }
    },
    {
      "src": "/api/(.*)",
      "dest": "/serverless-functions/$1"
    }
  ]
}

Use status and headers for redirects, or just dest for internal rewrites.
Tip
Use 301 status for permanent redirects and 302 for temporary redirects to maintain SEO rankings.
4

Add custom headers and CORS configuration

Configure custom headers for specific routes or globally:

{
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1",
      "headers": {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
        "Cache-Control": "s-maxage=86400"
      }
    }
  ]
}

This is essential for API routes that need CORS support or custom caching behavior.
Tip
Be specific with CORS origins in production instead of using wildcard (*) for better security.
5

Configure route priority and ordering

Arrange routes in order of specificity, with most specific routes first:

{
  "routes": [
    {
      "src": "/api/users/profile",
      "dest": "/api/profile.js"
    },
    {
      "src": "/api/users/(.*)",
      "dest": "/api/users.js?id=$1"
    },
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    }
  ]
}

Vercel processes routes from top to bottom, stopping at the first match.
Tip
Always place exact matches before wildcard patterns to ensure proper routing behavior.
6

Test configuration locally

Install Vercel CLI and test your routing configuration locally:

npm i -g vercel
vercel dev

Navigate to http://localhost:3000 and test your custom routes. Check the terminal output for any routing errors or warnings. Verify that your patterns match the expected URLs and destinations work correctly.
Tip
Use browser developer tools to inspect network requests and verify headers are applied correctly.
7

Deploy and verify routing configuration

Deploy your project with the new routing configuration:

vercel --prod

After deployment, test all your custom routes in production. Check the Functions tab in your Vercel dashboard to see if serverless functions are being invoked correctly. Monitor the deployment logs for any routing-related errors.
Tip
Use Vercel's preview deployments to test routing changes before deploying to production.

Troubleshooting

Routes not working after deployment
Check that your vercel.json is in the project root and has valid JSON syntax. Verify route patterns using regex testing tools and ensure there are no conflicting routes above your configuration.
404 errors on dynamic routes
Ensure your destination files exist and your regex capture groups match properly. Check that $1, $2 variables correspond to your parentheses groups in the source pattern.
CORS errors on API routes
Add proper CORS headers to your route configuration: "Access-Control-Allow-Origin": "*" and "Access-Control-Allow-Methods": "GET, POST, OPTIONS". Handle preflight OPTIONS requests separately.
Redirects not preserving query parameters
Use $1 to capture and preserve query strings in your destination: "dest": "/new-path?$1" or modify your source pattern to include query parameter matching.

Related Guides

More Vercel Tutorials

How to deploy Next.js app

How to deploy Astro site

How to set up custom domain

How to configure environment variables

Other Tool Tutorials

N

Netlify Tutorials

Ready to get started with Vercel?

Put this tutorial into practice. Visit Vercel and follow the steps above.

Visit Vercel →