DEV Community

Rahul Nair
Rahul Nair

Posted on Edited on

Managing Redirects Without Redeploys: A Sitecore Marketplace App Built on Vercel Global Config

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:

  1. A user opens the dashboard inside Sitecore as a full-screen Marketplace extension.
  2. They pick a Global Config from a dropdown, which lists only the configs you have connected through environment variables.
  3. They list, add, edit or delete redirect rules.
  4. The extension writes the change to Global Config through the Vercel API.
  5. 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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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.local holds your Vercel API token and secrets. Keep it in .gitignore and 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
Enter fullscreen mode Exit fullscreen mode

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')) ?? {};
}
Enter fullscreen mode Exit fullscreen mode

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: remote and the two-argument revalidateTag(tag, 'max') are Next.js 16 features. On Next.js 15, use unstable_cache with revalidateTag(tag) instead.
  • Cache Components: use cache must be enabled in next.config.ts with cacheComponents: 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 in proxy.ts directly. Exclude /api in the proxy matcher to avoid a redirect loop.
  • Cache lifetime: cacheLife('minutes') is a built-in profile. Use cacheLife({ revalidate: 300 }) for an explicit 5-minute window.
  • Public route: /api/redirects-cache returns your rules to anyone who requests it, so don't store anything sensitive in them.

App screenshots

Marketplace App Configurations

  1. Update the dashboard url(/dashboard) in the route url in Stand alone and Full screen.

  1. 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)