🚀 React Deployment Demystified: Solving Common Issues Across Platforms

You’ve built a shiny React app… now comes the real challenge — deployment.

Whether it’s deploying to Netlify, Vercel, GitHub Pages, Firebase Hosting, or custom servers, developers often face frustrating issues like:

• ⚠️ White screens after deployment

• 🔄 Routes not working (404 errors)

• 📦 Incorrect asset paths or broken images

• 🔐 Environment variable misconfigurations

• 🔄 CI/CD pipeline problems

Let’s walk through why these issues happen, how to solve them, and which platform fits your needs best.

🌐 1. React Deployment Basics: Understanding npm run build

Before deploying, always generate a production build:

npm run build

This creates an optimized build/ folder with minified JS, preprocessed HTML, and static assets — ready for the web!

🧭 2. Platform-Specific Challenges & Solutions

🔵 Netlify

Issue: App works locally but gives a blank screen or broken links after deploy.

✅ Solution:

• Add a _redirects file in public/ for SPA routing:

/*    /index.html   200

Set build command: npm run build

Set publish directory: build/

📌 Bonus: Use netlify.toml for advanced configs.

⚫ Vercel

Issue: Dynamic routes (React Router) result in 404s.

✅ Solution:

• Use vercel.json to define rewrites for SPA:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

• Vercel automatically detects React builds — minimal setup needed!

🔥 Firebase Hosting

Issue: Refreshing a routed page results in 404.

✅ Solution:

• Add firebase.json with rewrite rule:

{
  "hosting": {
    "public": "build",
    "rewrites": [
      { "source": "**", "destination": "/index.html" }
    ]
  }
}

• Use Firebase CLI:

firebase init
firebase deploy

🟣 GitHub Pages

Issue: Routes break, and page reloads show 404.

✅ Solution:

• Set "homepage" field in package.json:

"homepage": "https://yourusername.github.io/repo-name"

• Use gh-pages package:

npm install --save gh-pages

Add scripts:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

🧱 Custom Servers (Node, Nginx)

Issue: Routing and asset handling issues.

✅ Solution:

• On Nginx, add this config for SPA routing:

location / {
  try_files $uri /index.html;
}

• On Node/Express, serve index.html for all unmatched routes:

app.use(express.static(path.join(__dirname, 'build')));
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'build', 'index.html'));
});

🔐 3. Environment Variables in Production

Issue: Variables like API keys don’t work after deploy.

✅ Solution:

• React only exposes env vars prefixed with REACT_APP_

• Define in .env.production and rebuild:

REACT_APP_API_URL=https://api.example.com

---

🔄 4. CI/CD Pipeline Tips

For teams using GitHub Actions, GitLab CI, or other pipelines:

✅ Checklist:

• Run npm install and npm run build

• Cache dependencies for faster builds

• Set correct environment and secrets

• Use artifacts to upload the build/ folder

🚀 Bonus: Vite Deployment

Using Vite instead of Create React App?

Set base in vite.config.js:

export default defineConfig({
  base: '/your-repo-name/',
});

Then build and deploy as usual.

📚 References

• React Deployment Docs

• Netlify SPA Routing

• Firebase Hosting Docs

• GitHub Pages Guide

• Vercel Config

---

🧠 Final Thoughts

Deployment is more than just uploading files — each platform has quirks that can break your app if you're not careful. But once you understand the rules of each system, deployment becomes a breeze.

👉 Follow Code Reacher for more in-depth React engineering guides, tool breakdowns, and real-world solutions.