Blank page or “page not found” after putting your app online

First, read the error

The page is blank, but the browser usually knows why. In Chrome, press F12 on Windows or Cmd+Option+J on a Mac, and the Console opens. Red lines are errors. Copy them into your AI tool together with the page's address. That is often enough for it to find the cause.

The project went online unbuilt

Many apps need a build step that turns the code you edit into files a browser can run. If the project folder goes online as it is, the page loads an index.html that points at a file like /src/main.tsx, which a browser can't run. The Console shows “Failed to load module script”, or a 404 for main.tsx.

The fix is to run the build, usually npm run build, and put the contents of the dist or build folder online. Or use a host that runs the build for you.

The app expects a different address

If your app lives in a sub-folder, like yourname.github.io/my-app/, but was built for the top of a site, it looks for its scripts in the wrong place, and each one comes back as a 404. In a Vite project the fix is the base setting in vite.config. Ask your AI tool to set it to your sub-folder, then build again.

A setting is missing online

On your computer the app reads its settings from .env. Online that file usually isn't there, so a value the app needs at startup is empty and the app stops before it draws anything. A typical Console line is “supabaseUrl is required.”

Add the same settings on your host. Settings whose names start with VITE_, NEXT_PUBLIC_ or REACT_APP_ are copied in when the app is built, so after adding them, build and publish again.

A file name with the wrong capital letter

Macs and Windows usually treat Logo.png and logo.png as the same file. Most hosts don't. If the code asks for one and the folder has the other, it works at home and breaks online, and the Console shows a 404 for that file. Make the name in the code match the file exactly.

“Page not found” when you refresh

A single-page app changes the address in the bar by itself as you click around, without asking the host for a new page. That works until someone refreshes, or opens a link like /about directly. Then the browser asks the host for a file called about, there isn't one, and the host answers 404.

The fix is a rule on the host: when an address has no matching file, send index.html and let the app take it from there. On Netlify, add a file called _redirects to the published folder with the line /* /index.html 200. On Vercel, add a vercel.json with a rewrite from /(.*) to /index.html. GitHub Pages has no such rule; the usual workaround is a copy of index.html named 404.html, or switching the app to addresses with a # in them.