The problem
On a headless Sitecore site, redirects usually end up in one of two places: hardcoded in the Next.js app (next.config.js or middleware), or managed inside the CMS. The first means every redirect change needs a code change and a redeploy. The second can be heavy, and it ties redirect handling to content publishing.
I wanted something simpler: a small admin UI where redirects can be added, edited or deleted, and the change goes live without touching the headless application's code or triggering a deployment.
The solution
Redirect Manager is a Sitecore Marketplace extension that manages pathname redirects stored in Vercel Global Config. Global Config is a globally distributed key-value store on Vercel, built for configuration data that is read often and changed rarely. That fits redirect rules well.
The extension stores all rules under a single item called redirects. It reads and writes that item, and it does not modify the main headless application.
Add a screenshot of the dashboard here.
How it works
The flow is straightforward:
- A user opens the dashboard inside Sitecore as a full-screen Marketplace extension.
- They pick a Global Config from a dropdown, which lists only the configs you have connected through environment variables.
- They list, add, edit or delete redirect rules.
- The extension writes the change to Global Config through the Vercel API.
- If configured, it calls a revalidate endpoint on the headless app so the cached redirect rules are cleared and the new rules take effect.
Routes
| Route | Marketplace extension point | Purpose |
|---|---|---|
/ |
Standalone (optional) | Landing page with a link to the dashboard |
/dashboard |
Full screen | Pick a Global Config, then list, add, edit and delete redirects
|
/api/global-configs |
n/a | Lists Global Configs through the Vercel API |
/api/redirects |
n/a | Lists, creates, updates and deletes redirects, and purges the headless app's redirect cache when configured |
/api/redirects/revalidate-cache |
n/a |
POST that clears the site:global-config:redirects cache on the headless app (used by the dashboard button) |
The redirect shape
All rules live under a single redirects key in Global Config. Each rule is keyed by the source path, with a destination and a status code:
{
"redirects": {
"/old-blog": {
"destination": "/blog",
"status": 301
},
"/legacy/pricing": {
"destination": "/pricing",
"status": 301
}
}
}
The rules are simple on purpose:
- Sources must start with
/.
Setup
Environment variables
Copy .env.local.example to .env.local and fill in the values:
| Variable | Required | Purpose |
|---|---|---|
GLOBAL_CONFIG_REDIRECTS_1 to _3
|
Yes (read) | Global Config connection strings, one per config you use |
VERCEL_API_TOKEN |
Yes (write) | Used for PATCH /v1/global-config/{id}/items (Vercel API docs) |
GLOBAL_CONFIG_ID |
No | Overrides the ecfg_... ID if needed; otherwise it is parsed from the connection string |
VERCEL_TEAM_ID |
Team stores | Required as ?teamId= on PATCH when the config is not on your personal Hobby scope |
NEXT_PUBLIC_APP_BASE_URL |
Cache purge button | Origin of the headless app, for example http://localhost:3000
|
SITECORE_REVALIDATE_SECRET |
Cache purge button | Must match the headless app; sent as the x-revalidate-secret header |
Security note:
.env.localholds your Vercel API token and secrets. Keep it in.gitignoreand never commit it. If a token ever ends up in a public repo, revoke it and create a new one.
Run it locally
cd extensions/RedirectManager
pnpm install
pnpm dev
Then open http://localhost:3000/dashboard.
Reading the redirects in your Next.js app
The extension only manages the data. The headless app reads the redirects item and applies it at request time. Vercel's guide covers the basic proxy approach: Dynamic redirects with Global Config and Next.js proxy.
That guide reads Global Config on every request. I wrapped the read in a tagged remote cache, so the rules are fetched once per cache window and the extension can purge them on demand:
// lib/redirects.ts
import { get } from '@vercel/global-config';
import { cacheLife, cacheTag } from 'next/cache';
export const REDIRECTS_TAG = 'site:global-config:redirects';
export async function getRedirects() {
'use cache: remote';
cacheTag(REDIRECTS_TAG);
cacheLife('minutes');
return (await get('redirects')) ?? {};
}
When the extension saves or deletes a rule, it calls the revalidate endpoint, which runs revalidateTag(REDIRECTS_TAG, 'max') and clears the cache.
Things to check
-
Next.js version:
use cache: remoteand the two-argumentrevalidateTag(tag, 'max')are Next.js 16 features. On Next.js 15, useunstable_cachewithrevalidateTag(tag)instead. -
Cache Components:
use cachemust be enabled innext.config.tswithcacheComponents: true, otherwise the build fails. - Directive placement: put the directive inside the function body (as above) or at the top of the file, as a string statement.
-
Proxy limitation: call
getRedirects()from a route handler (for example/api/redirects-cache) and have the proxy fetch it, instead of calling it inproxy.tsdirectly. Exclude/apiin the proxymatcherto avoid a redirect loop. -
Cache lifetime:
cacheLife('minutes')is a built-in profile. UsecacheLife({ revalidate: 300 })for an explicit 5-minute window. -
Public route:
/api/redirects-cachereturns your rules to anyone who requests it, so don't store anything sensitive in them.
App screenshots
Marketplace App Configurations
- Update the dashboard url(/dashboard) in the route url in Stand alone and Full screen.
- Update the deployment url(Non-prod/prod deployment url can be updated here)
Note : For local development the localhost url can be updated - http://localhost:3000)
Gotchas
PATCH returns 404 or not_found. Check that your VERCEL_API_TOKEN is scoped to the same team as the Global Config store, and set VERCEL_TEAM_ID. This is the most likely problem if reads work but writes fail.
Changes do not appear on the site. The headless app caches redirect rules. On save and delete, the extension calls POST /api/admin/global-config-redirects/revalidate when NEXT_PUBLIC_APP_BASE_URL and SITECORE_REVALIDATE_SECRET are both set. If they are not set, use the Purge redirects cache button on the dashboard.
Why this approach
- No redeploys for redirect changes. Rules live in Global Config, not in the app's code.
- Globally distributed. Global Config is built for fast reads close to users.
- Separate from the headless app. The extension does not modify the main application, so it is easy to adopt or remove.
- Simple data model. One item, one JSON shape, easy to inspect and debug.
What I would improve next
Add your own ideas here, for example bulk import from CSV, validation for redirect loops, audit history of who changed what, or wildcard and regex rules.
Wrap up
If you manage redirects on a headless Sitecore site, moving them out of code and into a small managed store takes a recurring chore off the development team.
The source is here: https://github.com/rahulnair-labs/vercel-redirects
I would love to hear how you handle redirects in your own Sitecore projects. Let me know in the comments.



Top comments (0)