When I deployed my very first React app, I thought it would be simple. Just run npm run build, toss the output into some hosting service, and boom—live! Yeah... not quite. I ended up staring at a white screen and a cryptic “Cannot GET /” error. Turns out, deployment is one of those areas that feels like it should be plug-and-play, but often bites you with edge cases, config gotchas, and environment quirks. Let's walk through how to get your React app production-ready without losing your mind.

Build, Preview, Ship (in That Order, Please)

Before you go wild with FTP uploads or GitHub Actions, build your app locally.

React gives you this handy command:

          npm run build
        

It generates a build/ folder, which contains everything you need: HTML, minified JavaScript, optimized assets, and even hashed filenames for cache-busting. Pro tip? Always run a local server to preview that folder before deploying. Use a simple tool like `serve`:

          npx serve -s build
        

Why? Because the dev server (npm start) uses things like hot reloading and history fallbacks that don’t exist in production. What works in dev might break in prod—and it's better to find out before your users do.

Environment Variables and Builds (Set Them Early, Set Them Right)

One of the sneakiest deployment bugs I ever hit was due to a missing environment variable. I had a REACT_APP_API_URL set in .env.local, but forgot to replicate it on Vercel. The app built just fine… but every fetch went to undefined.

React only exposes env variables prefixed with REACT_APP_ at build time. That means:

You must define them before building. Changing them after a build has no effect unless you rebuild. * They must be accessible to the front end (don’t store secrets here—ever).

Set up .env.production with sane defaults, and make sure your deployment pipeline respects them. Most platforms (Netlify, Vercel, Cloudflare Pages) have UI or CLI options to define these.

Common Deployment Pitfalls (aka "Things That Broke My App at 2AM")

Here’s my personal hit list of React deployment mistakes:

Missing `index.html` fallback for client-side routing*: React Router needs a rewrite rule to serve index.html for all routes. Without it, users hitting /profile directly will see a 404. Fix this by configuring rewrites (Netlify has _redirects, Vercel uses routes.json, etc.).

Not building before deploy*: Sounds silly, but I’ve pushed raw source files to servers thinking they’d “just work.” They don’t.

Hardcoded URLs*: If your app relies on absolute URLs (http://localhost:3000/api), it will break once deployed. Use environment variables or window.location.origin.

Overwriting static paths*: Hosting on a subdirectory (like GitHub Pages)? You’ll need to set the homepage in your package.json, or paths to JS/CSS will be wrong.

Forgotten `.env.production`*: Already mentioned, but deserves a second shout. It’s that common.

Deploying React is mostly smooth once you understand the traps. It’s also a great excuse to learn about build tools, CDN caching, and how the browser loads apps.

If you're ready to scale from "it works on my machine" to "it works for everyone," you've just crossed the final step in shipping. Congrats.

And if you're wondering how to keep your app rock-solid after deployment, head over to the final lesson: Performance Optimization: Stop Re-rendering Everything.