Handling Routes and Finishing Deployment
When you deploy a React app that uses client-side routing, the home page loads fine but refreshing or directly opening a URL like /products/7 often shows a "404 Not Found" page. Handling routes on the server is the final step that makes deep links work, after which the deployment is genuinely finished.
Why deep links break after deployment
A single page application has only one real HTML file: index.html. React Router reads the URL in the browser and decides which component to show. During development, the dev server quietly sends index.html for every path, so everything works.
A static host behaves differently. When the browser asks for /products/7, the server looks for a file or folder with that name, finds nothing, and returns a 404. React never gets a chance to run. Clicking links inside the app still works because those navigations happen in JavaScript without asking the server, which is why the problem only appears on refresh or when someone shares a link.
The fix: a fallback to index.html
Tell the server: "if no real file matches this path, send index.html". Real files such as JavaScript bundles, images and CSS are still served normally. How you write that rule depends on the host.
# Build the production bundle first
npm run build # Vite writes to dist/, Create React App to build/
# Netlify: create public/_redirects (copied into the build)
/* /index.html 200
# Firebase Hosting: firebase.json
{
"hosting": {
"public": "dist",
"rewrites": [{ "source": "**", "destination": "/index.html" }]
}
}
# nginx server block
location / {
try_files $uri $uri/ /index.html;
}
The "200" in the Netlify rule is important. It makes the rule a rewrite rather than a redirect, so the URL in the address bar stays as /products/7 and React Router can read it.
Serving the app from a sub-folder
If the app lives at something like example.com/shop/ instead of the root, two more settings are needed. The build tool must know the base path (the base option in Vite's config, or the homepage field for Create React App) so asset URLs are correct, and React Router needs the same path through the basename prop on BrowserRouter. Missing either one gives a blank page with 404 errors for the JavaScript files in the console.
A mistake to avoid: redirect loops and wrong status codes
Some people "fix" deep links by redirecting every unknown path to the home page with a 301 or 302. That throws away the path the user asked for, and it can cause loops if the rule also catches the asset files. Use a rewrite that serves index.html with a 200 status instead. Also make sure your app shows its own "page not found" component for paths that really do not exist, using a catch-all route such as path="*", so visitors are not left staring at an empty screen.
Final checks before calling it done
- Open a nested URL directly in a new tab and refresh it.
- Check the console and network tab for 404s on JS or CSS files.
- Verify environment variables for the production API URL were set at build time.
- Try a made-up path and confirm your not-found page appears.
- Test on a phone, since caching and HTTPS issues sometimes show only there.
Takeaway: a client-routed app needs a server rewrite that returns index.html for unknown paths, plus a matching base path when hosted in a sub-folder; test by refreshing deep links.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.