_redirects File for Any Host — Not Just Netlify, Vercel, or Cloudflare Pages | RedirectIQ

Netlify's _redirects file is one of the best ideas in developer tooling: drop a file in your repo, commit it, and redirects go live on deploy. No dashboard, no tickets. The problem is it only works if you host with Netlify — or Vercel, or Cloudflare Pages. Every platform that offers this locks it to their own infrastructure.

We built the same thing for any host. Commit a redirectiq.json file, tell RedirectIQ where to find it, and your edge redirects stay in sync automatically — regardless of where your site runs.

We use it on this site. Here is the proof — both links below are real redirects managed by the file:

redirectiq.com/redirects-file — short URL for this post, try it
redirectiq.com/blog/gitops-redirects-manage-redirects-in-git — we renamed this post during editing; that redirect fires from the file

Here is the file that makes those work, served at redirectiq.com/redirectiq.json:

{
  "version": 1,
  "redirects": [
    { "from": "/redirect-without-hosting", "to": "/blog/redirect-domain-without-hosting", "type": "301" },
    { "from": "/blog/gitops-redirects-manage-redirects-in-git", "to": "/blog/redirects-file-for-any-host", "type": "301" },
    { "from": "/redirects-file", "to": "/blog/redirects-file-for-any-host", "type": "301" }
  ]
}

Commit a change to this file, push, and the rules are live at the edge within seconds. That is what this post is about.

---

Why redirects belong in your repo

Redirects are not a one-time task. They come up constantly:

A blog post slug changes during editing
A product gets renamed and the old URL needs to forward
A documentation restructure moves dozens of pages
A domain migration requires a comprehensive redirect map

The standard workflow for all of these is: engineer notices a broken link (or a Slack message from SEO), opens the redirect dashboard, adds the rule, clicks deploy. That is three context switches and a deploy for something that should be a one-line file edit.

Worse: the redirect often gets forgotten entirely. The URL change ships. The redirect ticket sits in the backlog. Google starts crawling 404s. By the time someone notices in Search Console, the ranking signal has already started to decay.

The file-based approach solves this by making redirects part of the same workflow as the URL change itself. The redirect lives next to the content. It gets reviewed in the same PR. It deploys when the code deploys.

Why _redirects is platform-locked

Netlify's _redirects file, Vercel's vercel.json redirects block, and Cloudflare Pages' _redirects support all work the same way: they bake redirect rules into the platform's edge layer at deploy time. Commit the file, push, and the platform reads it and reconfigures its CDN.

This is elegant — but it only works because those platforms control the full stack from your repo to the edge. The redirect config is consumed by the same system that builds and deploys your site.

If you are on a different host, or your infrastructure is more complex than a single platform, there is nothing to read the file. Your CDN and your deploy pipeline are separate systems.

RedirectIQ sits at the edge as a Cloudflare proxy layer in front of your origin. Because it is a separate service, it can poll a URL you control — regardless of where your site is hosted — and sync rules to the edge without being coupled to your deploy platform.

The redirectiq.json file format

The file is straightforward:

{
  "version": 1,
  "redirects": [
    { "from": "/old-blog-post", "to": "/blog/new-title", "type": "301" },
    { "from": "/docs/v1/*", "to": "/docs/v2/", "type": "301" },
    { "from": "/team", "to": "https://about.company.com/team", "type": "302" }
  ]
}

Each entry has three fields:

from — the source path, starting with /. Wildcards (/blog/*) and named parameters (/posts/[slug]) are supported.
to — the destination. Either a path on the same domain (/new-path) or an absolute URL to any destination.
type — "301" (permanent) or "302" (temporary). Defaults to "301" when omitted.

The file is served from your domain at any path you choose. A common convention is /redirectiq.json or /.well-known/redirects.json, but the path is up to you — you configure it once in the RedirectIQ dashboard.

How the sync works

RedirectIQ fetches your file on a schedule and diffs it against the rules currently at the edge. Only changed rules trigger a deploy — if the file has not changed since the last fetch, nothing happens.

There are two sync modes:

Hourly polling — RedirectIQ checks your file every hour. Works without any changes to your CI/CD pipeline. Good for teams that want the simplest possible setup.

Deploy webhook — Your CI/CD pipeline calls a webhook after each deploy. RedirectIQ fetches the file immediately and syncs any changes to the edge within seconds. This is the right choice if you want redirects to go live as part of the same deploy that changes the URLs.

With the webhook, the redirect is live before the first user hits the old URL — the same guarantee Netlify's _redirects gives you, on any host.

Security: how RedirectIQ knows the file is yours

If RedirectIQ is fetching a file from a URL, how does it know that file actually belongs to you?

The trust chain:

1. Domain ownership verification — before you can enable file sync, you must prove you control the domain by adding a TXT record to your DNS. If you can add DNS records to a domain, you control it.

2. URL hostname pinning — the sync URL must be on the same hostname as the domain you registered. You cannot point RedirectIQ at a URL on a different domain, even one you also own.

3. HTTPS only — RedirectIQ will not fetch over plain HTTP. TLS certificate validation ensures the file is served by the entity that controls the domain.

This is the same trust model as a _redirects file on Netlify — your repo access proves ownership.

Setting it up

1. Add the file to your repo

Create redirectiq.json in your public assets directory (or wherever static files are served at the root of your domain):

{
  "version": 1,
  "redirects": []
}

2. Deploy it

The file needs to be reachable at a public HTTPS URL on your domain — for example, https://yourdomain.com/redirectiq.json. Verify it loads in a browser before continuing.

3. Enable sync in RedirectIQ

Go to your domain in the RedirectIQ dashboard and open the File Sync section. Enter the URL of your file, choose a poll interval, and save. RedirectIQ will fetch the file immediately and sync any rules to the edge.

4. Add your first redirect

Edit redirectiq.json in your repo, commit, and push. If you configured a deploy webhook, the rule will be live within seconds of your pipeline completing. If you chose hourly polling, it will be live within the hour — or hit "Sync now" in the dashboard.

The pathMappings config (for monorepos and AI workflows)

There is an optional pathMappings block worth knowing about:

{
  "version": 1,
  "pathMappings": [
    {
      "fileGlob": "content/blog/**/*.mdx",
      "urlPrefix": "/blog",
      "slugFrom": "filename"
    }
  ],
  "redirects": []
}

This block is consumed by tooling — specifically the RedirectIQ Claude Code skill — to automatically detect URL changes. When a file is renamed, the skill reads pathMappings to understand what public URL that file maps to, generates the redirect entry, and writes it to redirectiq.json before the commit lands.

RedirectIQ strips pathMappings silently when it fetches the file. It is purely a hint for client-side tools.

---

Ready to set this up? Add your domain to RedirectIQ, drop a redirectiq.json file into your public assets, and configure the sync URL in the dashboard. The first sync takes under a minute.