@power-seo/redirects

Define redirect rules once — apply them in Next.js, Remix, and Express with typed exact, glob, and regex URL matching.

@power-seo/redirects is a framework-agnostic URL redirect rule engine for TypeScript — define RedirectRule[] once in a shared config file and generate Next.js next.config.js redirect arrays, Remix loader functions, and Express middleware from the same typed source of truth. Evaluate rules with exact string matching, glob wildcards with :param segments, or full regular expressions. First-match-wins priority ordering, configurable trailing-slash handling, and named parameter substitution are included. All adapters are tree-shakeable — import only the framework you target.

Zero runtime dependencies — pure TypeScript, no native bindings, edge-compatible.

Why @power-seo/redirects?

| | Without | With | | --------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | | Cross-framework rules | ❌ Duplicated in next.config.js, Remix loaders, Express middleware | ✅ One RedirectRule[] — all three from a single file | | Pattern matching | ❌ Ad-hoc regex scattered across route files | ✅ Exact, glob, and regex with typed API | | Named params | ❌ Manual capture group indexing | ✅ :param substitution in destination URLs | | Trailing slash | ❌ Inconsistent per route | ✅ Configurable 'strip' / 'add' / 'ignore' | | TypeScript | ❌ statusCode typos detected at runtime | ✅ RedirectStatusCode union enforces 301 \| 302 at compile time | | Testing | ❌ Deploy to verify redirects work | ✅ engine.match() in unit tests — zero-cost synchronous check | | SEO | ❌ Missing 301s break link equity during migrations | ✅ Typed rules prevent status code mistakes |

Features

• Exact matching — byte-for-byte URL comparison with optional case sensitivity control
• Glob pattern matching — * wildcard and :param named segment support (e.g. /blog/:slug)
• Regex pattern matching — full regular expression matching with capture group extraction
• 301 and 302 status codes — permanent and temporary redirect support via RedirectStatusCode union type
• :param substitution — substituteParams() for named parameter placeholders in destination URLs
• Trailing slash normalization — configurable 'strip', 'add', or 'ignore' per engine
• Case-sensitive option — per-engine case sensitivity control
• Next.js adapter — toNextRedirects(rules) maps statusCode: 301 → permanent: true automatically
• Remix loader adapter — createRemixRedirectHandler(rules) returns a Remix-compatible loader function
• Express middleware adapter — createExpressRedirectMiddleware(rules) returns an Express RequestHandler
• Priority-ordered evaluation — rules are evaluated top-to-bottom; first match wins
• Zero runtime dependencies — no external libraries; edge-compatible
• Full TypeScript types — typed RedirectRule, RedirectMatch, RedirectEngine, RedirectEngineConfig
• Tree-shakeable — import only the adapters you use; "sideEffects": false

Comparison

| Feature | @power-seo/redirects | next/redirects (config) | vercel.json | nginx rewrite | | ---------------------------------- | :------------------: | :---------------------: | :---------: | :-----------: | | Works in Next.js | ✅ | ✅ | ✅ | ❌ | | Works in Remix | ✅ | ❌ | ❌ | ❌ | | Works in Express | ✅ | ❌ | ❌ | ✅ | | Typed TypeScript API | ✅ | ❌ | ❌ | ❌ | | Named :param substitution | ✅ | ✅ | ✅ | ✅ | | Regex pattern support | ✅ | ✅ | ✅ | ✅ | | Glob wildcard support | ✅ | ✅ | ✅ | ✅ | | Programmatic rule testing | ✅ | ❌ | ❌ | ❌ | | One rule set → multiple frameworks | ✅ | ❌ | ❌ | ❌ | | Zero runtime dependencies | ✅ | ✅ | ✅ | ✅ | | Tree-shakeable | ✅ | ❌ | ❌ | ❌ |

Installation

npm install @power-seo/redirects

yarn add @power-seo/redirects

pnpm add @power-seo/redirects

Quick Start

import { createRedirectEngine } from '@power-seo/redirects';

const engine = createRedirectEngine({
  rules: [
    { source: '/old-about', destination: '/about', statusCode: 301 },
    { source: '/blog/:slug', destination: '/articles/:slug', statusCode: 301 },
    { source: '/docs/*', destination: '/documentation/*', statusCode: 302 },
  ],
});

const match = engine.match('/blog/my-seo-guide');
// { rule: {...}, resolvedDestination: '/articles/my-seo-guide', statusCode: 301 }

const noMatch = engine.match('/no-redirect-here');
// null

Usage

Shared Rule File

Define rules once and import them into every framework adapter:

// redirects.config.ts
import type { RedirectRule } from '@power-seo/redirects';

export const rules: RedirectRule[] = [
  { source: '/old-about', destination: '/about', statusCode: 301 },
  { source: '/blog/:slug', destination: '/articles/:slug', statusCode: 301 },
  { source: '/docs/*', destination: '/documentation/*', statusCode: 302 },
  { source: '/products/:id(\\d+)', destination: '/items/:id', statusCode: 301 },
];

Next.js — next.config.js

toNextRedirects() converts RedirectRule[] to the format Next.js expects. statusCode: 301 maps to permanent: true.

// next.config.js
const { toNextRedirects } = require('@power-seo/redirects');
const { rules } = require('./redirects.config');

module.exports = {
  async redirects() {
    return toNextRedirects(rules);
  },
};

Remix — Catch-All Route

createRemixRedirectHandler() returns a Remix loader function for use in a $.tsx catch-all route.

// app/routes/$.tsx
import { createRemixRedirectHandler } from '@power-seo/redirects';
import { rules } from '~/redirects.config';

export const loader = createRemixRedirectHandler(rules);

Express — Middleware

createExpressRedirectMiddleware() returns an Express RequestHandler. Register it early in the middleware chain.

import express from 'express';
import { createExpressRedirectMiddleware } from '@power-seo/redirects';
import { rules } from './redirects.config';

const app = express();
app.use(createExpressRedirectMiddleware(rules));

Trailing Slash and Case Sensitivity

const engine = createRedirectEngine(rules, {
  caseSensitive: false, // match /About and /about equally
  trailingSlash: 'remove', // /about/ → /about before matching
});

Parameter Substitution

import { substituteParams } from '@power-seo/redirects';

substituteParams('/articles/:slug', { slug: 'react-seo-tips' });
// '/articles/react-seo-tips'

Testing Rules in CI

import { createRedirectEngine } from '@power-seo/redirects';
import { rules } from './redirects.config';

const engine = createRedirectEngine(rules);

const match1 = engine.match('/old-about');
expect(match1?.resolvedDestination).toBe('/about');
expect(match1?.statusCode).toBe(301);

const match2 = engine.match('/blog/my-post');
expect(match2?.resolvedDestination).toBe('/articles/my-post');
expect(match2?.statusCode).toBe(301);

expect(engine.match('/no-match')).toBeNull();

API Reference

createRedirectEngine(initialRules, config)

function createRedirectEngine(
  initialRules?: RedirectRule[],
  config?: RedirectEngineConfig,
): RedirectEngine;

| Parameter | Type | Default | Description | | ---------------------- | ----------------------------- | ---------- | --------------------------------------- | | initialRules | RedirectRule[] | [] | Initial ordered array of redirect rules | | config.caseSensitive | boolean | false | Case-sensitive URL matching | | config.trailingSlash | 'keep' \| 'remove' \| 'add' | 'remove' | Trailing slash normalization |

Returns RedirectEngine: { match(url: string): RedirectMatch | null; addRule(rule: RedirectRule): void; removeRule(source: string): boolean; getRules(): RedirectRule[] }.

matchExact(url, source, config?)

function matchExact(url: string, source: string, config?: RedirectEngineConfig): boolean;

Returns boolean. Byte-for-byte URL comparison after normalization.

matchGlob(url, pattern, config?)

function matchGlob(
  url: string,
  pattern: string,
  config?: RedirectEngineConfig,
): { matched: boolean; params: Record<string, string> };

Returns { matched: boolean; params: Record<string, string> }. Supports :param named segments and * wildcard matching.

matchRegex(url, pattern, destination, config?)

function matchRegex(
  url: string,
  pattern: string,
  destination: string,
  config?: RedirectEngineConfig,
): { matched: boolean; destination: string };

Returns { matched: boolean; destination: string }. Full regular expression matching with capture group substitution into the destination.

substituteParams(template, params)

substituteParams('/articles/:slug', { slug: 'react-seo-tips' });
// '/articles/react-seo-tips'

toNextRedirects(rules)

Converts RedirectRule[] to Next.js redirects() array format. Maps statusCode: 301 → permanent: true, statusCode: 302 → permanent: false.

createRemixRedirectHandler(rules)

Returns a Remix LoaderFunction that issues redirect() when a rule matches, or returns null otherwise.

createExpressRedirectMiddleware(rules)

Returns an Express RequestHandler that calls res.redirect() on match or next() when no rule matches.

Types

| Type | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | RedirectStatusCode | 301 \| 302 \| 308 \| 307 \| 410 (from @power-seo/core) | | RedirectRule | { source: string; destination: string; statusCode: RedirectStatusCode; isRegex?: boolean } (from @power-seo/core) | | RedirectMatch | { rule: RedirectRule; resolvedDestination: string; statusCode: RedirectStatusCode } | | RedirectEngineConfig | { caseSensitive?: boolean; trailingSlash?: 'keep' \| 'remove' \| 'add' } | | RedirectEngine | { match(url: string): RedirectMatch \| null; addRule(rule: RedirectRule): void; removeRule(source: string): boolean; getRules(): RedirectRule[] } | | NextRedirect | { source: string; destination: string; permanent: boolean } |

Use Cases

• Site migrations — redirect hundreds of old URLs to new paths with a typed rule array
• URL restructuring for SEO — enforce new URL patterns with 301 redirects to preserve link equity
• Trailing slash normalization — enforce consistent URL format across all routes
• Locale redirects — redirect /en/about to /about with glob patterns
• Legacy URL handling — redirect old numeric IDs to slug-based URLs with regex patterns
• Canonical URL enforcement — redirect http: to https:, www. to non-www
• Multi-framework monorepos — define rules once, generate Next.js, Remix, and Express configs from the same file

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — no external libraries; safe on any runtime
• Framework-agnostic core — createRedirectEngine() has no framework imports; adapters are separate named exports
• First-match-wins — rules are evaluated top-to-bottom; order matters for overlapping patterns
• SSR compatible — toNextRedirects() runs at build time; Remix and Express adapters run at request time
• Edge runtime safe — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — "sideEffects": false; import only the adapters you use
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

| Package | Install | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- | | @power-seo/core | npm i @power-seo/core | Framework-agnostic utilities, types, validators, and constants | | @power-seo/react | npm i @power-seo/react | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs | | @power-seo/meta | npm i @power-seo/meta | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR | | @power-seo/schema | npm i @power-seo/schema | Type-safe JSON-LD structured data — 23 builders + 22 React components | | @power-seo/content-analysis | npm i @power-seo/content-analysis | Yoast-style SEO content scoring engine with React components | | @power-seo/readability | npm i @power-seo/readability | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI | | @power-seo/preview | npm i @power-seo/preview | SERP, Open Graph, and Twitter/X Card preview generators | | @power-seo/sitemap | npm i @power-seo/sitemap | XML sitemap generation, streaming, index splitting, and validation | | @power-seo/redirects | npm i @power-seo/redirects | Redirect engine with Next.js, Remix, and Express adapters | | @power-seo/links | npm i @power-seo/links | Link graph analysis — orphan detection, suggestions, equity scoring | | @power-seo/audit | npm i @power-seo/audit | Full SEO audit engine — meta, content, structure, performance rules | | @power-seo/images | npm i @power-seo/images | Image SEO — alt text, lazy loading, format analysis, image sitemaps | | @power-seo/ai | npm i @power-seo/ai | LLM-agnostic AI prompt templates and parsers for SEO tasks | | @power-seo/analytics | npm i @power-seo/analytics | Merge GSC + audit data, trend analysis, ranking insights, dashboard | | @power-seo/search-console | npm i @power-seo/search-console | Google Search Console API — OAuth2, service account, URL inspection | | @power-seo/integrations | npm i @power-seo/integrations | Semrush and Ahrefs API clients with rate limiting and pagination | | @power-seo/tracking | npm i @power-seo/tracking | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License