---
title: Dynamic redirects with Global Config and Next.js proxy
description: Learn how to create redirects that update instantly without redeploying by storing rules in Global Config and reading them from your Next.js proxy.
url: /kb/guide/dynamic-redirects-with-global-config-and-next-js-proxy
canonical_url: "https://vercel.com/kb/guide/dynamic-redirects-with-global-config-and-next-js-proxy"
published: 2026-01-23
last_updated: 2026-08-03
authors: Jonas Herrmannsdörfer
related:
  - /docs/global-config/migration-guide
  - /docs/global-config
  - /kb/guide/dynamic-redirects-with-edge-config-and-next-js-proxy
  - /docs/global-config/global-config-sdk
  - /docs/global-config/vercel-api
  - /docs/redirects/bulk-redirects
  - /docs/global-config/global-config-limits
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Redirects](https://vercel.com/docs/routing/redirects?from=related) — Learn how to use redirects on Vercel to instruct Vercel's platform to redirect incoming requests to a new URL.
- [Configuration Redirects](https://vercel.com/docs/routing/redirects/configuration-redirects?from=related) — Learn how to define static redirects in your framework configuration or vercel.json with support for wildcards, pattern
- [Redirecting](https://nextjs.org/docs/pages/guides/redirecting?from=related) — Learn the different ways to handle redirects in Next.js.
- [Manage Redirects at Scale](https://vercel.com/docs/routing/redirects/manage-redirects-at-scale?from=related) — Add, bulk upload, version, and roll back project-level redirects using the CLI.
- [Incremental Migration](https://vercel.com/docs/incremental-migration?from=related) — Learn how to migrate your app or website to Vercel with minimal risk and high impact.
- [Redirecting](https://nextjs.org/docs/app/guides/redirecting?from=related) — Learn the different ways to handle redirects in Next.js.
- [Bulk Redirects](https://vercel.com/docs/routing/redirects/bulk-redirects?from=related) — Learn how to import thousands of simple redirects from CSV, JSON, or JSONL files.
- [redirects](https://nextjs.org/docs/app/api-reference/config/next-config-js/redirects?from=related) — Add redirects to your Next.js app.
- [How can I increase the limit of redirects or use dynamic redirects on Vercel?](https://vercel.com/kb/guide/how-can-i-increase-the-limit-of-redirects-or-use-dynamic-redirects-on-vercel?from=related) — Instructions on how to use Serverless Functions to handle redirects on Vercel.
- [Migrate to Vercel from Netlify](https://vercel.com/kb/guide/migrate-to-vercel-from-netlify?from=related) — Migrate your website's configuration from Netlify to Vercel
- [How to migrate from Fastly to Vercel with zero downtime](https://vercel.com/kb/guide/how-to-migrate-from-fastly-to-vercel-with-zero-downtime?from=related) — Consolidate your CDN infrastructure on Vercel to reduce latency, simplify your configuration, and improve your developer
- [Can I use Vercel as a reverse proxy?](https://vercel.com/kb/guide/vercel-reverse-proxy-rewrites-external?from=related) — Learn how to use rewrites to proxy requests from Vercel to other deployments.

Full cross-link map for this page: [/kb/guide/dynamic-redirects-with-global-config-and-next-js-proxy.graph.md](/kb/guide/dynamic-redirects-with-global-config-and-next-js-proxy.graph.md)
<!-- /docsgraph:related -->


> Edge Config is now Global Config. Learn how to [migrate from Edge Config to Global Config](https://vercel.com/docs/global-config/migration-guide).

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

## Before you start

You'll need:

- A Next.js project deployed on Vercel
  
- A Vercel account ([Global Config](https://vercel.com/docs/global-config) is available on all plans)
  

## Step 1: Create an Global Config

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

Name it something descriptive like `redirects` or `routing-config`.

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

**Reference:** [Global Config quickstart](https://vercel.com/docs/global-config)

## Step 2: Connect Global Config to your project

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

This automatically adds the `GLOBAL_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:

```bash
vercel env pull .env.local
```

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

## Step 3: Add redirect rules to Global Config

In the Global Config dashboard, insert:

```json
{
  "redirects": [
    {
      "source": "/old-blog",
      "destination": "/blog",
      "permanent": true
    },
    {
      "source": "/docs/v1",
      "destination": "/docs/v2",
      "permanent": false
    }
  ]
}
```

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

For now, use exact paths. The [Advanced patterns section](https://vercel.com/kb/guide/dynamic-redirects-with-edge-config-and-next-js-proxy#advanced-patterns) shows how to add support for wildcards, parameters, and regex matching (like `/blog/:slug` or `/docs/:version/:path*`).

## Step 4: Install the Global Config SDK

```bash
npm install @vercel/global-config
```

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

**Reference:** [@vercel/global-config SDK](https://vercel.com/docs/global-config/global-config-sdk)

## Step 5: Create the middleware

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

```tsx
import { get } from '@vercel/global-config';
import { NextRequest, NextResponse } from 'next/server';

// Define the shape of your redirect rules
type Redirect = {
  source: string;
  destination: string;
  permanent: boolean;
};

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

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

    if (!redirects) {
      return NextResponse.next();
    }

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

    if (redirect) {
      return NextResponse.redirect(
        new URL(redirect.destination, request.url),
        redirect.permanent ? 308 : 307
      );
    }

    return NextResponse.next();
  } catch (error) {
    // If Global Config fails, continue without redirecting
    console.error('Global Config error:', error);
    return NextResponse.next();
  }
}
```

**What this does:**

1. Reads the `redirects` array from Global 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](https://nextjs.org/docs/app/getting-started/proxy)

## Step 6: Deploy and test

Deploy your project:

```bash
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
   

## Updating redirects without redeploying

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

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

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

### Update via API

You can also update redirects programmatically using the Vercel API:

```tsx
const response = await fetch(
  `https://api.vercel.com/v1/global-config/${GLOBAL_CONFIG_ID}/items`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${VERCEL_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      items: [
        {
          operation: 'update',
          key: 'redirects',
          value: [
            // Your updated redirect rules
            { source: '/new-campaign', destination: '/landing', permanent: false }
          ],
        },
      ],
    }),
  }
);
```

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

**Reference:** [Global Config API](https://vercel.com/docs/global-config/vercel-api)

## Advanced patterns

### Pattern matching with path-to-regexp

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):

```bash
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`:

```tsx
import { get } from '@vercel/global-config';
import { NextRequest, NextResponse } from 'next/server';
import { match } from "path-to-regexp";

type Redirect = {
  source: string;
  destination: string;
  permanent: boolean;
};

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

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

  const pathname = request.nextUrl.pathname;

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

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

      if (result.params) {
        for (const [key, value] of Object.entries(result.params)) {
          // Handle array params (wildcards)
          const param = Array.isArray(value)
            ? value.join("/")
            : (value as string);
          destination = destination.replace(`:${key}*`, param);
          destination = destination.replace(`:${key}`, param);
        }
      }

      return NextResponse.redirect(
        new URL(destination, request.url),
        redirect.permanent ? 308 : 307
      );
    }
  }

  return NextResponse.next();
}
```

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

**Named parameters:**

```json
{
  "source": "/blog/:slug",
  "destination": "/articles/:slug",
  "permanent": true
}
```

**Wildcard matching:**

```json
{
  "source": "/docs/:version/:path*",
  "destination": "/documentation/:version/:path*",
  "permanent": false
}
```

**Regex patterns:**

```json
{
  "source": "/user/:id(\\\\d+)",
  "destination": "/profile/:id",
  "permanent": true
}
```

**Optional segments:**

```json
{
  "source": "/posts{/:year}{/:month}",
  "destination": "/archive/:year/:month",
  "permanent": false
}
```

**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 Global Config.

**Reference:** [Next.js path-to-regexp patterns](https://github.com/pillarjs/path-to-regexp#usage)

## Limitations and considerations

### Global Config size limits

Global 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](https://vercel.com/docs/redirects/bulk-redirects) instead.

**Reference:** [Global Config limits](https://vercel.com/docs/global-config/global-config-limits)

### Proxy runs on every request

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

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

**Reference:** [Next.js proxy matcher](https://nextjs.org/docs/app/api-reference/file-conventions/proxy#matcher)

### Global Config reads are fast, but not free

Global 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.

## Troubleshooting

### "Global Config not found" error

Make sure:

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

### Redirects not updating

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

1. Check the Global 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)
   

### Proxy not running

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

## Summary

You now have redirects that update instantly without redeploying:

1. Store redirect rules in Global 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