Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Electron app shows 404 or a blank window once it is packaged

ErrorThe packaged app opens a blank window, the dev build works

Short answer

In development Electron loads your React dev server over http. In a package it loads a file from disk, so a wrong file path, asset URLs that start with a slash, or a router that reads the URL path all break. Load the built index.html with loadFile, build with a relative base, and use a hash router.

  • Applies to Electron 39, React 19, Vite 7, React Router 7
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open DevTools in the packaged app and read the Console and Network tabs. The failing URL tells you which cause below applies: a missing index.html, missing asset files, or a route that matched nothing.

    grep -n "loadURL\|loadFile" main.js
  2. 2Match what you see, then jump to its fix

    1. 1The window stays blank and the Network tab shows index.html failing to loadThe main process loads the wrong file in productionFix
    2. 2The Network tab shows the JS and CSS files failing, and their paths begin with /assets/Asset URLs start with a slash, so they point at the disk rootFix
    3. 3The page loads, then your own Not Found route renders on first startThe router reads the URL path, and a local file has no app routesFix

What does the error look like?

  • The packaged app opens a blank window, the dev build works
  • Your own Not Found route renders when the packaged app starts

Cause 1 of 3

The main process loads the wrong file in production

1Check

BrowserWindow.loadFile takes a path to an HTML file relative to the root of your application, while loadURL takes a remote address or a file:// URL. Check which one runs in production, and that the path points at your build output.

grep -n "loadURL\|loadFile" main.js

2Fix

Use loadURL for the dev server only, and loadFile with the build folder's index.html in production. Make sure the build folder is included in the packaged files.

const path = require('node:path');
// ELECTRON_START_URL is your own variable, e.g. http://localhost:5173 in development
if (process.env.ELECTRON_START_URL) {
  win.loadURL(process.env.ELECTRON_START_URL);
} else {
  win.loadFile(path.join(__dirname, 'dist', 'index.html'));
}

3Verify

Package the app again and start it. The window now shows your first screen.

npm run build && npm run package

Confirmed by electronjs.org

Did this fix it?

Cause 2 of 3

Asset URLs start with a slash, so they point at the disk root

1Check

Open dist/index.html and read the script and link tags. A path like /assets/index.js is resolved from the root of the file system when the page is a local file.

grep -n "src=\|href=" dist/index.html

2Fix

Build with a relative base so every generated URL is relative to the file that uses it.

// vite.config.js
export default defineConfig({
  base: './',
});

3Verify

Rebuild and check that index.html now references ./assets/ paths.

npm run build && grep -n "assets" dist/index.html

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The router reads the URL path, and a local file has no app routes

1Check

See which router your app creates. BrowserRouter matches the path part of the URL; a packaged app starts at a file path that none of your routes match.

grep -rn "BrowserRouter\|createBrowserRouter\|HashRouter" src/

2Fix

Use a hash router. It stores the location in the hash part of the URL, which is not sent anywhere, so it does not depend on the file path.

import { HashRouter, Routes, Route } from "react-router";

<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
</HashRouter>

3Verify

Start the packaged app. The address in DevTools ends with #/ and your home route renders.

console.log(window.location.href)

Confirmed by reactrouter.com

Did this fix it?

How do I stop it coming back?

  • Test the packaged build on your own machine before every release, not only the dev server.
  • Keep one config switch for dev and production loading in the main process.
  • Decide the router type when you create an Electron project, not after the first package.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.