Redirects & Rewrites

Overview

Add a _redirects file to the root of your deployment directory to configure:

• Redirects — Send visitors to a different URL (301, 302, 307, 308)
• Rewrites — Serve different content without changing the URL (200)
• Proxying — Forward requests to external APIs

Basic Syntax

Each line in the _redirects file follows this format:

/source-path    /destination-path    [status]

Lines starting with # are comments. Empty lines are ignored.

Redirects

Redirects tell the browser to navigate to a different URL. Use status codes 301, 302, 307, or 308.

# Permanent redirect (SEO-friendly)
/old-page    /new-page    301

# Temporary redirect
/blog/2023/*    /blog/archive/:splat    302

Rewrites

Rewrites serve different content while keeping the original URL in the browser. Use status code 200.

# Serve /docs/index.html for all /docs/* paths
/docs/*    /docs/index.html    200

# Clean URLs - serve /about.html for /about
/about    /about.html    200

This is useful for:

• SPA routing (serve index.html for all routes)
• Clean URLs (serve .html files without extension)
• A/B testing (serve different pages at same URL)

Pattern Matching

Wildcards (*)

Use * to match any path segment. The matched value is available as :splat in the destination.

# /docs/quickstart -> /documentation/quickstart
/docs/*    /documentation/:splat    200

# /api/users/123 -> /v2/api/users/123
/api/*     /v2/api/:splat           200

Named Parameters

Use :name to capture a single path segment.

# /blog/hello-world -> /posts/hello-world
/blog/:slug    /posts/:slug    301

# /user/42 -> /profile/42
/user/:id      /profile/:id    302

Combined Patterns

Mix named parameters and wildcards:

# /api/v1/users/123 -> /api/v2/users/123
/api/:version/*    /api/v2/:splat    200

External Proxying

Forward requests to external APIs by using a full URL as the destination. Only works with status 200.

# Proxy API requests to your backend
/api/*    https://api.example.com/:splat    200

# Proxy specific endpoints
/auth/*   https://auth.example.com/:splat   200

This lets you:

• Avoid CORS issues by proxying API calls through your domain
• Keep your API endpoint private
• Add a layer of caching between users and your API

Force Flag

By default, rewrites only apply if the original file doesn’t exist. Add ! after the status code to force the rewrite even when a file exists.

# Always rewrite, even if /docs/index.html exists
/docs/*    /docs/app.html    200!

SPA Configuration

For single-page applications, redirect all routes to index.html:

# SPA fallback - serve index.html for all routes
/*    /index.html    200

Plan Limits

The number of redirect rules you can use depends on your plan:

Common Examples

Website Migration

# Old blog paths to new structure
/blog/:year/:month/:slug    /posts/:slug    301

# Legacy pages
/about-us    /about    301
/services    /products    301
/contact-us  /contact   301

API Versioning

# Redirect old API version to new
/api/v1/*    /api/v2/:splat    301

# Proxy external API
/api/v2/*    https://api.mybackend.com/:splat    200

Language/Region Redirects

# Redirect old language paths
/en-us/*    /en/:splat    301
/en-gb/*    /en/:splat    301