Dynamic redirects with Edge Config and Next.js proxy

This guide shows you how to create redirects that update instantly without redeploying. Store redirect rules in Edge Config and read them from your Next.js proxy.

You'll need:

• A Next.js project deployed on Vercel
• A Vercel account (Edge Config is available on all plans)

Go to your Vercel dashboard and navigate to Storage > Edge Config > Create Edge Config.

Name it something descriptive like redirects or routing-config.

After creation, you'll see your Edge Config ID (starts with ecfg_). You'll need this later.

Reference: Edge Config quickstart

In your Edge Config's settings, click Connect Project and select your Next.js project.

This automatically adds the EDGE_CONFIG environment variable to your project. The variable contains your connection string, which the SDK uses to read data.

For local development, pull the environment variable:

1
vercel env pull .env.local

This downloads all your project's environment variables, including EDGE_CONFIG, into .env.local.

In the Edge Config dashboard, insert:

1
{
2
  "redirects": [
3
    {
4
      "source": "/old-blog",
5
      "destination": "/blog",
6
      "permanent": true
7
    },
8
    {
9
      "source": "/docs/v1",
10
      "destination": "/docs/v2",
11
      "permanent": false
12
    }
13
  ]
14
}

The structure is simple: an array of objects with source, destination, and permanent properties.

For now, use exact paths. The Advanced patterns section shows how to add support for wildcards, parameters, and regex matching (like /blog/:slug or /docs/:version/:path*).

1
npm install @vercel/edge-config

The SDK provides a get() function that reads data from your Edge Config with ultra-low latency.

Reference: @vercel/edge-config SDK

Create a proxy.ts file in /src or the root of your project (if you don't have a /src directory):

1
import { get } from '@vercel/edge-config';
2
import { NextRequest, NextResponse } from 'next/server';
3

4
// Define the shape of your redirect rules
5
type Redirect = {
6
  source: string;
7
  destination: string;
8
  permanent: boolean;
9
};
10

11
export const config = {
12
  // Skip static files
13
  matcher: '/((?!_next/static|_next/image|favicon.ico).*)',
14
};
15

16
export default async function proxy(request: NextRequest) {
17
  try {
18
    // Read redirect rules from Edge Config
19
    const redirects = await get<Redirect[]>('redirects');
20

21
    if (!redirects) {
22
      return NextResponse.next();
23
    }
24

25
    // Check if the current path matches any redirect rule
26
    const redirect = redirects.find(
27
      (r) => r.source === request.nextUrl.pathname
28
    );
29

30
    if (redirect) {
31
      return NextResponse.redirect(
32
        new URL(redirect.destination, request.url),
33
        redirect.permanent ? 308 : 307
34
      );
35
    }
36

37
    return NextResponse.next();
38
  } catch (error) {
39
    // If Edge Config fails, continue without redirecting
40
    console.error('Edge Config error:', error);
41
    return NextResponse.next();
42
  }
43
}

What this does:

1. Reads the redirects array from Edge Config on every request
2. Checks if the current URL path matches any source path (exact match only)
3. If matched, redirects to the destination with the appropriate status code
4. If anything fails, the request continues normally

This basic example uses exact path matching. See the Advanced patterns section to add support for wildcards (:slug*), parameters (:id), and regex patterns.

File naming: Use proxy.ts for Next.js 16+, or middleware.ts for Next.js 15 and earlier.

Reference: Next.js proxy

Deploy your project:

1
vercel --prod

Then test your redirects:

1. Visit your old URL (e.g., https://your-site.vercel.app/old-blog)
2. You should be redirected to the new URL (/blog)
3. Check the network tab: you'll see a 307 or 308 status code

This is where Edge Config shines. To add, modify, or remove redirects:

1. Go to your Edge Config in the Vercel dashboard
2. Edit the redirects item
3. Save your changes

Changes propagate globally in under a second. No redeploy needed.

You can also update redirects programmatically using the Vercel API:

1
const response = await fetch(
2
  `https://api.vercel.com/v1/edge-config/${EDGE_CONFIG_ID}/items`,
3
  {
4
    method: 'PATCH',
5
    headers: {
6
      Authorization: `Bearer ${VERCEL_API_TOKEN}`,
7
      'Content-Type': 'application/json',
8
    },
9
    body: JSON.stringify({
10
      items: [
11
        {
12
          operation: 'update',
13
          key: 'redirects',
14
          value: [
15
            // Your updated redirect rules
16
            { source: '/new-campaign', destination: '/landing', permanent: false }
17
          ],
18
        },
19
      ],
20
    }),
21
  }
22
);

This is useful for building admin interfaces or integrating with CMS webhooks.

Reference: Edge Config API

The basic example uses exact path matching. For advanced patterns like wildcards, parameters, and regex matching, update your proxy.ts to use path-to-regexp (the same library that powers next.config.js redirects).

First, install path-to-regexp version 6.3.0 (the same version Next.js uses):

1
npm install path-to-regexp@6.3.0

This ensures your redirect patterns work identically to next.config.js redirects. At runtime, your code still uses Next.js's bundled version (no duplication in your bundle).

Then update your proxy.ts:

1
import { get } from '@vercel/edge-config';
2
import { NextRequest, NextResponse } from 'next/server';
3
import { match } from "path-to-regexp";
4

5
type Redirect = {
6
  source: string;
7
  destination: string;
8
  permanent: boolean;
9
};
10

11
export const config = {
12
  matcher: '/((?!_next/static|_next/image|favicon.ico).*)',
13
};
14

15
export default async function proxy(request: NextRequest) {
16
  const redirects = await get<Redirect[]>('redirects');
17
  if (!redirects) return NextResponse.next();
18

19
  const pathname = request.nextUrl.pathname;
20

21
  for (const redirect of redirects) {
22
    // Use Next.js's path matching - same as next.config.js
23
    const matcher = match(redirect.source, { decode: decodeURIComponent });
24
    const result = matcher(pathname);
25

26
    if (result) {
27
      // Build destination with captured params
28
      let destination = redirect.destination;
29

30
      if (result.params) {
31
        for (const [key, value] of Object.entries(result.params)) {
32
          // Handle array params (wildcards)
33
          const param = Array.isArray(value)
34
            ? value.join("/")
35
            : (value as string);
36
          destination = destination.replace(`:${key}*`, param);
37
          destination = destination.replace(`:${key}`, param);
38
        }
39
      }
40

41
      return NextResponse.redirect(
42
        new URL(destination, request.url),
43
        redirect.permanent ? 308 : 307
44
      );
45
    }
46
  }
47

48
  return NextResponse.next();
49
}

This approach supports all the same patterns as next.config.js redirects:

Named parameters:

1
{
2
  "source": "/blog/:slug",
3
  "destination": "/articles/:slug",
4
  "permanent": true
5
}

Wildcard matching:

1
{
2
  "source": "/docs/:version/:path*",
3
  "destination": "/documentation/:version/:path*",
4
  "permanent": false
5
}

Regex patterns:

1
{
2
  "source": "/user/:id(\\\\d+)",
3
  "destination": "/profile/:id",
4
  "permanent": true
5
}

Optional segments:

1
{
2
  "source": "/posts{/:year}{/:month}",
3
  "destination": "/archive/:year/:month",
4
  "permanent": false
5
}

Why this works: Next.js bundles path-to-regexp internally, so you don't need to install any additional dependencies. You get the exact same path matching that next.config.js uses, but with the ability to update rules via Edge Config.

Reference: Next.js path-to-regexp patterns

Edge Config has size limits per plan:

• Hobby: 8 KB
• Pro: 64 KB
• Enterprise: 512 KB

For most redirect use cases, 8 KB is plenty. A simple redirect rule is about 100 bytes, so you can fit roughly 80 rules in the Hobby plan limit.

If you need thousands of redirects, use Bulk Redirects instead.

Reference: Edge Config limits

The matcher config determines which requests trigger your proxy. Be specific to avoid unnecessary Edge Config reads:

1
export const config = {
2
  // Only run on specific paths that might have redirects
3
  matcher: ['/old-blog/:path*', '/docs/v1/:path*', '/legacy/:path*'],
4
};

Reference: Next.js proxy matcher

Edge Config reads are globally distributed and have no rate limits. However, reading on every request does add latency (typically 1-5ms). For most sites, this is negligible. For extremely high-traffic sites, consider using Bulk Redirects for static rules.

Make sure:

1. Your Edge Config is connected to your project
2. The EDGE_CONFIG environment variable exists in your project settings
3. You've deployed after connecting the Edge Config

Edge Config changes should propagate in under a second. If they don't:

1. Check the Edge Config dashboard to confirm your changes saved
2. Verify you're hitting the production deployment (not a preview)
3. Clear your browser cache (browsers cache 307/308 redirects)

Check your matcher config. Make sure your redirect paths aren't accidentally excluded. The default excludes _next, api, and static files.

You now have redirects that update instantly without redeploying:

1. Store redirect rules in Edge Config
2. Read them from Next.js proxy on each request
3. Update rules via dashboard or API, changes propagate globally in under a second