| | |

Netlify 06 🌐 Redirects, Rewrites & Proxies — Configuring _redirects, SPA fallbacks, role-based routing, and signed proxy rules

⏱️ Estimated read: 8 min | |

Netlify’s routing engine is one of its most powerful features, operating entirely at the edge. By configuring rules in a _redirects file or a netlify.toml file, you can control how the browser interacts with your site without writing server-side code or managing complex web server configurations. Because these rules are processed before the content is served, they execute with near-zero latency, making them ideal for SEO, security, and application routing.

Routing on Netlify falls into three main categories: redirects (which change the browser’s URL), rewrites (which keep the URL but serve different content), and proxies (which fetch content from external sources while masking the origin). These tools solve the common problems of URL migration, Single Page Application (SPA) routing, and content shielding. Understanding how to sequence these rules—and knowing the precedence of status codes—is critical for building robust web applications on the platform.

This chapter covers the anatomy of the _redirects file, the implementation of SPA fallbacks to ensure client-side routers function correctly, role-based routing (RBAC) powered by Netlify Identity, and the advanced concept of signed proxies to secure dynamic content. We will also distinguish between file-based configuration and the programmatic power of Netlify Functions/Edge Functions.

Key point: Netlify routing rules are edge-side directives processed before any content is served; a 301 status code triggers a browser-level URL change, while a 200 status code performs a rewrite or proxy action, silently serving content from a different source without altering the user’s visible URL.


Why X exists

The legacy URL migration problem. Websites evolve, and content moves. If you delete an old page and create a new one at a different path, users get a 404 error and search engines penalize you. Redirects exist to preserve site authority and user experience by mapping old locations to new ones at the edge, ensuring no traffic is lost during site re-architecting.

The Single Page Application (SPA) routing problem. Modern frameworks (React, Vue, etc.) handle routing client-side via JavaScript. If a user navigates to /dashboard and refreshes the page, the browser asks the server for the /dashboard file. Since that file doesn’t exist on disk, the server returns a 404. SPA fallbacks exist to intercept these requests and serve index.html instead, allowing the client-side router to take over.

The content proxying requirement. Sometimes you need to serve content from an external API or a legacy backend as if it were a local path. Proxies allow you to fetch this external content seamlessly, bypassing CORS issues and providing a unified experience for the end-user without requiring a backend server.

The Role-Based Access Control (RBAC) need. In protected applications, certain pages should only be accessible to authorized users. Instead of writing complex server-side middleware for every route, Netlify allows you to attach role-based requirements directly to routing rules, shielding content before it is even fetched from the build.

The trade-off. The trade-off for edge-level routing is visibility and complexity. Because rules are defined in configuration files and processed by Netlify’s black-box edge, debugging complex chains of redirects can be difficult. Developers must be disciplined with their syntax and understand the order of operations to avoid infinite loops or shadowed routes.


a. Redirects vs. Rewrites

In Netlify, the status code used in your _redirects file determines the nature of the routing. A redirect (301, 302, 303) tells the browser: “The resource you are looking for is over there.” The browser updates the address bar to the new URL. A rewrite (200) tells the browser: “I am going to serve you the content of that other file, but you don’t need to know.”

# Syntax: /from /to status_code
/old-page /new-page 301

A 301 (Permanent Redirect) is the standard for SEO-friendly migrations. It informs search engines that the move is final and they should transfer the page’s ranking authority to the new URL. A 200 (Rewrite), by contrast, is the mechanism for proxying. If you define /api/* /external-api/:splat 200, the user stays on /api/something, but the content is pulled from the external host. This is invisible to the user and crucial for avoiding cross-origin resource sharing (CORS) blocks.

b. SPA Fallbacks and Proxying

The most common use case for a rewrite in Netlify is the “SPA Fallback.” Without this, deep-linking in applications built with frameworks like React Router or Vue Router would fail on page refresh. The rule is simple: if the requested path is not found on disk, serve the main application entry point.

# Catch-all for SPA
/* /index.html 200

Proxying is an extension of the rewrite logic, often used to fetch assets or API data from a separate server. By adding a specific flag to the rule, Netlify can proxy to an external URL. This is invaluable for micro-frontend architectures where one project needs to fetch assets from another domain without the browser ever leaving the primary context.

c. Role-Based Routing and Signed Proxies

Netlify Identity allows you to restrict access to specific paths based on user roles (e.g., admin, editor, subscriber). You append the Role= attribute to a redirect rule. Netlify checks the user’s JSON Web Token (JWT) provided by Netlify Identity before deciding whether to serve the content or redirect to a login page.

# Role-based restriction
/admin/* /admin 200! Role=admin

Signed proxies take this a step further by securing the proxying mechanism itself. When proxying content, you can sign the request with a secret key. The target backend can then verify the request signature, ensuring that only requests coming through your Netlify proxy (and not direct requests) are allowed to access protected backend resources. This effectively turns your edge layer into a secure gateway for your private microservices.


Complete Example Session

# ============================================
# PART 1: BASIC REDIRECTS (SEO MIGRATION)
# ============================================
# Map legacy URLs to new structure
/blog/post-one      /posts/2023/post-one  301!
/about-us           /about                301!

# ============================================
# PART 2: SPA FALLBACK (ROUTING)
# ============================================
# Keep URLs clean for React/Vue client routers
/*                  /index.html           200

# ============================================
# PART 3: PROXYING EXTERNAL API
# ============================================
# Hide the backend API behind a local route
/api/*              https://api.myapp.com/:splat  200

# ============================================
# PART 4: ROLE-BASED ACCESS CONTROL
# ============================================
# Protect the admin panel via Netlify Identity
/admin/*            /admin/login          301!  Role=admin
/admin/*            /admin/dashboard      200   Role=admin

# ============================================
# PART 5: FORCED REDIRECTS (THE "!")
# ============================================
# Force redirect even if the file exists on disk
/maintenance        /maintenance-page     301!

# ============================================
# PART 6: QUERY PARAMETER REDIRECTS
# ============================================
# Redirect based on query strings
/search?q=:query    /results/:query       301!

# ============================================
# PART 7: LANGUAGE-BASED REDIRECTS
# ============================================
# Redirect based on browser headers
/                   /es                   302!  Language=es

# ============================================
# PART 8: COUNTRY-BASED REDIRECTS
# ============================================
/shop               /us-store             302!  Country=us

# ============================================
# PART 9: HEADERS CONFIGURATION
# ============================================
# Defined in _headers (often adjacent to _redirects)
/*
  X-Frame-Options: DENY
  Content-Security-Policy: default-src 'self'

# ============================================
# PART 10: COMPLEX SIGNED PROXY (CONCEPT)
# ============================================
# Use Netlify Functions for signing proxies
# Rule remains /api/* -> /.netlify/functions/proxy 200

The example demonstrates a complete _redirects file handling SEO, SPA routing, proxying, RBAC, and conditional logic.


Quick Reference

Status Codes and Meaning

CodeTypeBehavior
301RedirectPermanent, URL changes
302RedirectTemporary, URL changes
200RewriteInternal, URL stays same

Special Syntax Flags

FlagDescription
!Force redirect (ignore existing files)
:splatWildcard capture for URL segments
Role=Netlify Identity attribute
Language=Header-based routing

Rule Precedence

OrderLayer
1Netlify Functions / Edge Functions
2_redirects rules
3Asset/File handling

Best Practices

✅ Do This:

# Use 301! for permanent SEO moves                // ✅
# Always include SPA fallback /* /index.html 200   // ✅
# Keep _redirects file at the root of /dist        // ✅
# Use :splat for wildcard URL segments             // ✅
# Test redirect logic with `netlify dev`           // ✅

❌ Don’t Do This:

# Use 302 for permanent migrations                 // ❌
# Forget the "!" on forced redirects               // ❌
# Place _redirects in the source folder root       // ❌
# Overlap conflicting redirect rules               // ❌
# Proxy external APIs without CORS safety          // ❌

Common Pitfalls

PitfallWhy It HappensFix
Infinite Loop/old /new -> /new /oldCheck rule direction
Asset 404Redirect rule catches assetsUse more specific paths
SPA Refresh 404Missing SPA fallbackAdd /* /index.html 200
Force failFile exists on diskUse the ! flag
Cache issuesBrowser remembers 302Use 301 for final moves

Real-World Examples

1. SEO Migration

/blog/old-article /blog/new-article 301!

2. SPA Setup

/* /index.html 200

3. API Proxy

/api/v1/* https://backend.internal.api/v1/:splat 200

4. Maintenance Mode

/ /maintenance 302!

5. User Portal

/dashboard/* /dashboard 200! Role=authenticated

6. Regional Shop

/store /us-store 302! Country=us

7. Pretty URLS

/product /product.html 200

8. Canonicalization

https://example.com/* https://www.example.com/:splat 301!

9. Asset Security

/uploads/* / 404! (Block access to uploads dir)

10. Language Detection

/ /fr 302! Language=fr


Visual

Redirect vs. Rewrite

┌──────────────────────────────────────────────┐
│  REDIRECT (301)                              │
│  Browser ──► Netlify ──► Browser (New URL)   │
│  (Client side changes)                       │
│                                              │
│  REWRITE (200)                               │
│  Browser ──► Netlify ──► Content (Hidden)    │
│  (Server side fetch)                         │
└──────────────────────────────────────────────┘

SPA Fallback Logic

┌──────────────────────────────────────────────┐
│  REQUEST: /dashboard                         │
│  1. Check disk: Exists? NO                   │
│  2. Rule: /* /index.html 200                 │
│  3. Serve: index.html                        │
│  4. JS Router takes over: loads dashboard    │
└──────────────────────────────────────────────┘

Proxy Chain

┌──────────────────────────────────────────────┐
│  USER ──► Netlify Edge                       │
│             │                                │
│             ▼                                │
│        Proxy Rewrite (200)                   │
│             │                                │
│             ▼                                │
│        EXTERNAL API                          │
│        (Data returned to Netlify)            │
│             │                                │
│             ▼                                │
│        USER (Receives data)                  │
└──────────────────────────────────────────────┘

Summary

ItemValue
Primary File_redirects
301SEO Permanent
200Rewrite/Proxy
SPA Pattern/* /index.html 200
Force Flag!
Edge LogicPre-build/Pre-render

Key takeaways:

  • Redirects are browser-level; Rewrites are server-level. Use 301s for permanent content moves (SEO) and 200s for masking, proxying, and SPA fallbacks.
  • SPA Fallback is mandatory. Every modern JS-routed application needs the /* /index.html 200 catch-all rule to prevent 404s on refresh.
  • The “!” flag forces the rule. When you want to override existing files (like a maintenance page), use the exclamation mark.
  • Order matters. Rules are processed from top to bottom. Place more specific rules at the top and general ones (like the SPA fallback) at the bottom.
  • Keep files in the build output. The _redirects and _headers files must exist in your final build folder (e.g., dist/ or build/) for Netlify to see them.

Remember: Routing is the nervous system of your web application. Keep your _redirects file organized, version-controlled, and tested. By leveraging Netlify’s edge routing, you offload processing from your application code, resulting in faster page loads, better SEO, and a more secure architecture.

Was this helpful?


Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!