How to Host a React App on Netlify (Manual Deploy)

Deploying a React app to Netlify by hand takes two minutes. Run the build, drag the output folder, done.

Then you click a link, refresh the page, and get a 404. Your app works locally and breaks in production.

That is the React-specific problem with static hosting, and it has a one-line fix. This guide covers the deploy plus the three things that go wrong after it: routing 404s, missing environment variables, and a blank white page.

Build First, Then Deploy the Output

The most common mistake is dragging the project folder. That uploads your source code — src, node_modules, package.json — and Netlify has no way to run it.

You deploy the build output, not the project.

Run the build:

npm run build

Vite produces a folder named dist. Create React App produces one named build. Check which you have before you go looking for the wrong folder.

Inside it you will find index.html, an assets folder with hashed filenames, and any static files you had in public. That folder is what you drag.

Preview It Locally Before Deploying

Worth thirty seconds. The production build behaves differently from the dev server.

For Vite:

npm run preview

For CRA:

npx serve -s build

If it breaks here, it will break on Netlify — and debugging locally is far easier than debugging a deployed site.

Deploying

Sign in at app.netlify.com.

Find the drag-and-drop area on your team dashboard, or go to Add new site, then Deploy manually.

Drag dist (or build) onto it. Not the parent folder. The build output folder itself.

Netlify assigns a random subdomain and your site is live. Rename it under Site configuration, then Site details, then Change site name — do that before sharing the link, because the old URL stops resolving once you change it.

Fixing the 404 on Page Refresh

This is the one that brings people here.

Your app loads at the root. You navigate to /dashboard and it works, because React Router handled that in the browser. Then you refresh, and Netlify returns a 404.

Here is why. When you refresh, the browser asks Netlify for /dashboard. Netlify looks for a file at that path. There is no such file — your app is a single index.html and the routing happens in JavaScript after it loads. So Netlify correctly returns a 404.

The fix is to tell Netlify to serve index.html for every path and let React Router take over.

Create a file named _redirects, with no extension, in your public folder:

1
/*    /index.html   200

The 200 matters. A 301 or 302 would redirect the browser and change the URL. 200 serves index.html while keeping the requested path intact, which is what React Router needs to read.

Because the file sits in public, your build copies it into the output folder automatically. Rebuild and redeploy.

Confirm it worked by checking that _redirects actually exists inside dist or build. If it does not, the file is in the wrong place.

If you are using hash-based routing with URLs like /#/dashboard, you do not need this. Everything after the # never reaches the server.

The Environment Variable Trap

This one is specific to manual deploys and catches almost everyone.

Environment variables in a React app are baked in at build time. They are not read at runtime. Whatever was in your .env when you ran npm run build is compiled into the bundle.

With a Git-connected deploy, you set variables in the Netlify dashboard and they are injected during Netlify's build. With a manual deploy, Netlify never runs a build — so dashboard variables do nothing at all. Your .env file at build time is the only thing that matters.

Two rules follow from that.

Set your production values locally before running npm run build, or you will ship your development API URL.

And never put a secret in a frontend environment variable. Anything compiled into the bundle is readable in the browser by anyone who opens devtools. API keys, database credentials, and tokens belong on a server. This is true regardless of how you deploy.

Note the prefixes: Vite exposes only variables starting with VITE_, accessed via import.meta.env. CRA uses REACT_APP_ via process.env.

Fixing a Blank White Page

The deploy succeeds, the URL loads, and you get nothing. Open devtools and check the console.

404s on the JS and CSS files. The base path is wrong. If you are deploying to the site root, base should be / in vite.config.ts, or homepage should be absent from package.json in CRA. A homepage field left over from a GitHub Pages deploy is a common culprit.

A JavaScript error in the console. The app crashed on mount. Something that worked in development is failing in the production build — often an undefined environment variable, or code that assumed a dev-only condition.

Nothing in the console at all. You probably dragged the wrong folder and Netlify is serving an empty directory. Check that index.html is at the top level of what you uploaded.

When to Stop Deploying Manually

Manual deploys are fine for a demo, a portfolio piece, or showing a client something on a Friday afternoon.

They stop being fine quickly, and for a React app the reasons are sharper than for a static site.

Every update means rebuilding locally and dragging again. Whoever deploys has to have the right .env on their machine, which means environment configuration lives on individual laptops instead of in the platform.

There is no deploy history worth using. When a build breaks production, you cannot roll back to a known-good commit — you can only rebuild from whatever your local code happens to be.

And there is no way for two people to deploy safely. Whoever ran npm run build most recently defines what is live.

Connecting a Git repository takes about two minutes and removes all of it. Add new site, Import an existing project, authorise GitHub, pick the repo. Set the build command to npm run build and the publish directory to dist or build. Netlify rebuilds on every push, gives you deploy previews on pull requests, and lets you roll back to any previous deploy in one click.

Do the manual deploy to understand what is happening. Then connect the repo.

Committing the Config Instead

Once you are on Git deploys, move your redirect rule into a netlify.toml at the project root:

1
2
3
4
5
6
7
[build]
  command = "npm run build"
  publish = "dist"
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

This keeps deployment configuration in version control alongside the code, which means a new team member gets it automatically rather than discovering it after their first broken deploy.

Where This Fits in a Real Project

Static hosting handles a client-rendered React app well. The calculation changes once you need SEO on public pages, server-side rendering, or an API layer — at which point Next.js on a platform that runs server code is usually the better shape.

Our team builds and ships production React and Next.js applications for client software, including the deployment and observability around them. You can see the stack we work across on our technologies page and browse shipped work in our projects portfolio.

If you are earlier in the process, the React with TypeScript tutorial covers project setup, and the NVM on Windows tutorial handles Node version management. For plain static sites, the HTML and CSS Netlify guide covers the simpler case.

More walkthroughs are on the tutorials hub, and longer technical writing lives on the blog.