Skip to content
Saimul Islam

redirect-lint: a redirect chain checker for _redirects, CSV and JSON

Find redirect chains, loops and clashes in a whole rule set, then flatten every chain to one hop before you ship.

Install
npm install redirect-lint

Overview

redirect-lint is a redirect chain checker that reads the whole list at once. Give it a Netlify or Cloudflare Pages _redirects file, a CSV (including a WordPress Redirection export) or a JSON array, and it reports loops, chains, duplicates, rules that an earlier rule hides, and redirects that shadow pages you actually have.

It can also collapse chains into one hop and write the result back out in any of the three formats. Netlify's @netlify/redirect-parser parses rules but does not check a rule set for loops, chains or clashes; that is the part this package does. It has no dependencies.

Examples

Check a _redirects file against your built site
npx redirect-lint _redirects --pages dist
Sample output
_redirects (redirects, 10 rules)

Errors (1)
  line 6  loop  /team → /about/team → /team is a loop, so none of them is served.

Warnings (8)
  line 2   chain        /pricing-old → /pricing-2025 → /pricing. Served as /pricing-old → /pricing.
  line 4   clash        /blog/* covers 3 live pages, such as /blog/hello.
  line 5   shadowed     /blog/hello is never reached: /blog/* (line 4) matches the same paths first on hosts that use the first match.
  line 5   clash        /blog/hello is a live page. The redirect hides it on hosts that apply redirects first.
  line 10  unsupported  /search?q=shoes: Query strings in the From are not supported. Matching on query parameters needs the host.
  line 11  clash        /contact is a live page. The redirect hides it on hosts that apply redirects first.
  line 12  unsupported  /api/*: 200 rewrites and proxies are not redirects, so they are not checked.
  line 13  chain        /old-contact → /contact → /contact-us. Served as /old-contact → /contact-us.

1 error, 8 warnings in 10 rules.
Flatten chains and write the cleaned rules
npx redirect-lint _redirects --flatten --out dist/_redirects
Use it from code
import { parseRedirects, lint, flatten, toRedirects } from 'redirect-lint';

const { rules, problems: parseProblems } = parseRedirects(text);
const problems = lint(rules, { livePaths: ['/about', '/blog/hello'] });

const { rules: flat } = flatten(rules);
await writeFile('_redirects', toRedirects(flat));

Features

01Loops and chains
A loop is an error and exits 1. A chain, where a target redirects again, is a warning that shows the path it takes and the single hop that flattening gives.
02Flatten to one hop
Chains collapse to their final target, a chain into a 410 becomes a 410, and loops, malformed rules and repeated Froms are left out. Exact paths come first, then placeholders, then wildcards with the longest prefix first.
03Duplicates and shadowed rules
Two rules with the same From, or a wildcard that matches everything a later rule does on hosts that take the first match, are reported with their line numbers.
04Clashes with live pages
Point --pages at a built site folder and redirects that hide a page you actually have are reported, including wildcards that cover live pages.
05CSV, _redirects and JSON
Read and write all three. Converting a WordPress Redirection export to a _redirects file is one command: redirect-lint wordpress-export.csv --flatten --out _redirects.
06Import planning
planImport() compares an incoming rule list with the rules you already have and returns which rows are adds, updates or skips, plus the loops and clashes the import would cause.

CLI usage

Usage
redirect-lint <file> [--format csv|redirects|json] [--pages <dir>] [--flatten [--out <file>]] [--json]
-f, --format <type>
csv, redirects or json. Default: from the file name (_redirects, .csv, .json), then content.
--pages <dir>
A built site folder. Each .html file is a live page; redirects that hide one are reported.
--flatten
Collapse chains and print the final rules in the file's format. The report goes to stderr.
--out <file>
With --flatten, write the rules to a file. A .csv, .json or _redirects name sets the format.
--max-rows <n>
Most rows a CSV file may have. Default: 5000.
--json
Print the result as JSON instead of text.

Limits

  • It reads paths. Query matching, conditions, host-specific rules, regex rules and 200 rewrites are reported as unsupported and left out of the checks and out of anything flatten writes.
  • A wildcard is a trailing /* and matches paths below the prefix, not the prefix itself: /blog/* matches /blog/post and not /blog. Check how your host treats the edge cases.
  • Paths are case-sensitive and a trailing slash is ignored.
  • Where two rules only partly overlap, it does not guess which one a request reaches.
  • A 410 in a _redirects file loses the page it names, so toRedirects writes /410.html by default. Check that your host supports 410 rules.
  • It never fetches anything. It cannot tell whether a target exists unless the page is in livePaths.

Frequently asked questions

How do I check a redirect chain before I deploy?

Run npx redirect-lint _redirects. Every chain is reported with the path it takes and the single hop it could be, and a loop is an error that makes the command exit 1. Add --flatten --out to write the cleaned-up rules.

Can it check a bulk list of redirects from a CSV?

Yes. It reads CSV as from,to,status[,note], with or without a header, semicolon or tab delimited, or a WordPress Redirection export. A CSV file may have 5000 rows by default; change that with --max-rows.

Does it work with Netlify and Cloudflare Pages _redirects files?

Yes. It parses the _redirects format, including wildcards (/blog/*), placeholders (/shop/:slug) and 410s, and writes it back out. Query-string rules and 200 rewrites are reported as unsupported.

Does it request my URLs to find redirect chains?

No. It reads your rules, not your live site, so it makes no network requests. That is why it can check a rule set before you deploy it, but it also cannot tell whether a target page exists unless you pass --pages.

  • Web QA

    static-preflight

    A broken link checker and launch checklist for a static site build: SEO basics, links and assets, redirects, share cards, icons, JSON-LD and old-URL coverage.

  • Web QA

    siteprobe

    A fetch-only security headers checker and website scanner: about a hundred security, SEO and speed checks, with a score and a fix hint for each finding.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.