How to configure custom routing with config json on Vercel

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.

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.

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.

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.

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.

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.

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.