Fixing SPA 404s and Same‑Origin API Calls with Netlify Redirects and Rewrites

Problem: 404s on deep links and CORS errors on third‑party APIs

When a React or Vue app is built and deployed to Netlify, the static build contains only index.html and bundled assets. Navigating to /dashboard from a fresh browser or a bookmark triggers a 404 because the server looks for a file named dashboard. Likewise, calling https://api.example.com/data from the browser causes a CORS preflight because the origin is different.

Both issues can be solved with Netlify’s redirect and rewrite system, but the configuration can be confusing. The goal of this post is to show a concrete, tested approach that works for most SPAs and API proxies, while highlighting ordering, force flags, and caching pitfalls.

Redirects vs. Rewrites: What Netlify Actually Does

Netlify distinguishes two kinds of rules:

• Redirect – Sends a 301/302 response to the browser. The browser’s address bar changes to the new URL.
• Rewrite – Keeps the original URL in the address bar, but the requested resource comes from a different path or a proxied endpoint. The response status is usually 200.

For SPA deep‑linking you need a rewrite that serves /index.html for any unknown path. For API proxying you need a rewrite that forwards the request to the external service.

Rule Syntax and Ordering

Both _redirects files (placed in the publish directory) and netlify.toml blocks use the same line‑based syntax:

from   to   status   [force]   [headers]

Key points:

• /* and /:slug are splats and named placeholders that capture the rest of the URL or a single segment.
• The first rule that matches wins. Subsequent rules are ignored for that request.
• When a real file exists that matches from, the rule is shadowed unless you add force = true (or a trailing ! in _redirects).
• In most Netlify projects, netlify.toml rules are processed before _redirects rules. Verify this in the UI if you have both.

Concrete Example: SPA Fallback + API Proxy

Assume a build output folder called dist. Inside dist we place a _redirects file with the following content:

# Serve the SPA for any unknown route
/*  /index.html  200

# Proxy API requests to the third‑party service
/api/*  https://api.example.com/:splat  200  force

Explanation:

• The first rule rewrites all unknown paths to /index.html with a 200 status, enabling client‑side routing.
• The second rule proxies any path under /api/ to the external API, preserving the path after /api/ via the :splat placeholder. The force flag ensures this rule runs even if a file named api exists in the build.

In netlify.toml you could write the same rules inside a [[redirects]] block, which is often cleaner for larger projects:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200
  force = true

Testing the Rules Locally

Before deploying, run:

netlify dev

Then in another terminal, use curl to check the behavior:

curl -I http://localhost:8888/dashboard
# Expect:
# HTTP/1.1 200 OK
# Content-Type: text/html; charset=UTF-8

curl -I http://localhost:8888/api/users
# Expect:
# HTTP/1.1 200 OK
# (headers from the third‑party API)

Deploy a preview to confirm the same rules work in the real environment before promoting to production.

Trade‑offs and Limitations

• Permanent Redirects (301) are cached aggressively. If you accidentally set a 301 for a route that should be a rewrite, users will see the old URL until the cache expires. While you can use 302 during development, stick to 200 for SPA fallbacks and API proxies.
• Proxy Limits – Netlify’s edge proxy inherits the same timeout and payload limits as serverless functions (currently 10 s and ~10 MB). Long‑running or streaming APIs may fail.
• Rule Count – Free plans allow up to 100 rules. If your project needs more, consider consolidating or moving to a paid plan.
• Query Strings – By default, Netlify ignores query strings when matching rules. If you need query‑specific behavior, use the advanced query syntax, but test thoroughly.
• File System Clean‑ups – Some build tools delete the _redirects file during the final copy step. Ensure your build pipeline preserves it.

Practical Checklist Before Going Live

1. Place _redirects or netlify.toml in the publish directory.
2. Run netlify dev and test all target URLs with curl -I.
3. Create a Deploy Preview and verify the same URLs resolve correctly.
4. Check the Netlify UI’s Redirects panel to confirm the rules were parsed.
5. Deploy to production and monitor the 404 logs for any missed routes.

By following this workflow, you can reliably solve SPA deep‑link 404s and CORS‑blocked API calls without touching your client code.