Netlify 06 🌐 Redirects, Rewrites & Proxies — Configuring _redirects, SPA fallbacks, role-based routing, and signed proxy rules
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
| Code | Type | Behavior |
|---|---|---|
| 301 | Redirect | Permanent, URL changes |
| 302 | Redirect | Temporary, URL changes |
| 200 | Rewrite | Internal, URL stays same |
Special Syntax Flags
| Flag | Description |
|---|---|
! | Force redirect (ignore existing files) |
:splat | Wildcard capture for URL segments |
Role= | Netlify Identity attribute |
Language= | Header-based routing |
Rule Precedence
| Order | Layer |
|---|---|
| 1 | Netlify Functions / Edge Functions |
| 2 | _redirects rules |
| 3 | Asset/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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Infinite Loop | /old /new -> /new /old | Check rule direction |
| Asset 404 | Redirect rule catches assets | Use more specific paths |
| SPA Refresh 404 | Missing SPA fallback | Add /* /index.html 200 |
| Force fail | File exists on disk | Use the ! flag |
| Cache issues | Browser remembers 302 | Use 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
| Item | Value |
|---|---|
| Primary File | _redirects |
| 301 | SEO Permanent |
| 200 | Rewrite/Proxy |
| SPA Pattern | /* /index.html 200 |
| Force Flag | ! |
| Edge Logic | Pre-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 200catch-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
_redirectsand_headersfiles must exist in your final build folder (e.g.,dist/orbuild/) 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.
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!