Deployed your React app and getting 404 on refresh? Here's why Client-Side Routing breaks on static servers and how to fix it using Nginx, AWS S3, Apache, and Netlify redirects. Includes a debugging guide.
A comprehensive deep dive into client-side storage. From Cookies to IndexedDB and the Cache API. We explore security best practices for JWT storage (XSS vs CSRF), performance implications of synchronous APIs, and how to build offline-first applications using Service Workers.
Establishing TCP connection is expensive. Reuse it for multiple requests.
Tired of naming classes? Writing CSS directly inside HTML sounds ugly, but it became the world standard. Why?
HTTP is Walkie-Talkie (Over). WebSocket is Phone (Hello). The secret tech behind Chat and Stock Charts.
You just finished building your amazing React/Vue application.
It works perfectly on localhost:3000. You can navigate from Home to About, from About to Contact. Everything is smooth.
Excited, you run npm run build, upload the files to your server (AWS S3, Nginx, or GitHub Pages), and share the link.
Your friend clicks the link, lands on the Homepage. "Cool!"
Then they navigate to /about. "Nice!"
Then, purely out of habit, they press Refresh (F5) or copy the URL example.com/about and open it in a new tab.
The screen goes white. The browser says the file does not exist. You panic. "But it worked on my machine!" Why does clicking a link work, but typing the same URL fail?
To understand the fix, you must understand the architecture.
In traditional websites (like PHP, old HTML sites), the URL corresponds directly to a file on the server's hard drive.
example.com/about.htmlabout.html in the folder.Modern frameworks like React, Vue, and Angular are Single-Page Applications.
There is literally only ONE HTML file: index.html.
The /about, /contact, /users/123 pages do not exist as files. They are virtual pages created by JavaScript.
example.com. The server returns index.html. The React app starts.history.pushState) to change the URL bar to show /about and renders the About Component. The Server is oblivious to this change.example.com/about. The browser makes a fresh network request to the server: "Give me the file located at /about".about or a folder named about. It finds nothing. It dutifully returns 404 Not Found.The solution is to trick the server.
We need to tell the server:
"If a user asks for a file that doesn't exist, don't give them a 404 error. Instead, give them index.html."
When the browser receives index.html (even though it asked for /about), it loads your React app.
The React Router then wakes up, looks at the URL bar (/about), and says:
"Oh, the current URL is /about. I should render the About Page component immediately."
From the user's perspective, it looks like the page loaded correctly.
Here are the copy-paste configurations for the most common hosting environments.
If you manage your own VPS or Nginx container, edit your server block configuration (/etc/nginx/conf.d/default.conf usually).
server {
listen 80;
root /var/www/my-react-app;
index index.html;
location / {
# Check if file exists ($uri), if not check folder ($uri/),
# if neither, serve /index.html
try_files $uri $uri/ /index.html;
}
}
The try_files directive is standard for all SPAs.
If you are on a shared hosting (cPanel style) or using LAMP stack, create a .htaccess file in the root of your public folder.
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]
</IfModule>
Translation: "If the requested filename is NOT a file (!-f) and NOT a directory (!-d), then serve index.html."
If you host on an S3 Bucket directly:
index.html.index.html.Wait, setting Error document to index.html? Yes.
When S3 can't find /about, it triggers an error. You tell it "On error, serve index.html". S3 serves the file with a 200 OK status (or sometimes 404 but with the content).
If you use CloudFront (CDN) in front of S3 (which you should for SSL), the S3 Error Document trick might not work perfectly.
/index.html.Create a file named _redirects inside your public (or build) folder.
/* /index.html 200
This rule tells Netlify: "For ANY path (/*), serve /index.html with a 200 status code."
Create a vercel.json file in your root directory.
{
"rewrites": [
{ "source": "/(.*)", "destination": "/" }
]
}
There is one way to avoid all this server configuration: Hash Routing.
Instead of using https://example.com/about, you use https://example.com/#/about.
How it works:
# (the hash fragment) to the server.example.comexample.com (ignoring #/about).index.html.#/about, renders About page.It works on GitHub Pages (which doesn't support SPA rewrites natively easily) and file systems. Downside:
<a href="#section">) behave weirdly.Use BrowserRouter (React) or WebHistory (Vue) whenever possible. Use HashRouter only when you absolutely cannot configure the server.
If you use Server-Side Rendering (SSR) like Next.js or Nuxt.js, this problem usually doesn't exist.
Since there is a real server (Node.js) running, it receives the request for /about, renders the HTML on the fly, and sends it back.
From the browser's perspective, it looks just like a traditional file-based website.
However, if you use next export (Static Site Generation), you are back to square one and must use the Rewrite rules mentioned above (e.g., vercel.json or _redirects).
If you have applied the settings but still see 404 errors, check the following:
/api/users) are not being redirected to index.html by mistake. You might need to exclude /api/* from your rewrite rules.example.com/myapp/), ensure your Router's base path is configured correctly in your code (basename="/myapp" in React Router).The "404 on Refresh" error is the initiation rite for every SPA developer. It's a simple mismatch between the Client's routing logic and the Server's file-system logic.
index.html on 404.try_files $uri /index.html (Nginx) or Redirect Rules.Now that you know the secret, you never have to fear the refresh button again. Happy deploying!