Maaz Zindani

Loading the index…

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

React page is blank when a backend serves the HTML for Vite

ErrorUncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.

Short answer

The React plugin has to initialise Fast Refresh before any component loads. When Vite serves index.html it injects that code itself. When your own server renders the HTML, nothing injects it, so the page throws. Add the preamble script, plus the @vite/client script, before your entry script in the template.

  • Applies to Vite 7, Vite 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    View the HTML your backend actually sends and look for the Vite scripts. The tags must come before your entry file.

    curl -s http://localhost:5000/ | grep -n -E 'vite/client|react-refresh|main'
  2. 2Match what you see, then jump to its fix

    1. 1The page source has your entry script but no import from /@react-refreshThe template has no React refresh preambleFix
    2. 2Network tab shows failed requests to localhost:5173, or none at allThe @vite/client script is missing or points at the wrong originFix
    3. 3You render React on the server and never call Vite's index.html transformA server-rendered app skips the HTML transformFix

What does the error look like?

  • Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.

Cause 1 of 3

The template has no React refresh preamble

1Check

Vite can only modify the HTML it serves itself. A page rendered by another server does not get the preamble.

grep -rn "react-refresh" templates/ 2>/dev/null

2Fix

Paste the preamble into the template, before the other Vite scripts. Replace the address with the origin your Vite dev server runs on.

<script type="module">
  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.__vite_plugin_react_preamble_installed__ = true
</script>

3Verify

Reload the page; the console no longer shows the preamble error.

curl -s http://localhost:5000/ | grep -c react-refresh

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The @vite/client script is missing or points at the wrong origin

1Check

The backend integration guide requires the @vite/client script in development, loaded from the address Vite listens on. A different port or host in the template breaks it.

curl -sI http://localhost:5173/@vite/client

2Fix

Add the client script with the correct origin, and use the same origin in the preamble import.

<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/src/main.jsx"></script>

3Verify

The three requests (react-refresh, client, entry) all return 200.

curl -sI http://localhost:5173/@react-refresh | head -1

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

A server-rendered app skips the HTML transform

1Check

The plugin README says its preamble import exists for SSR apps that do not use transformIndexHtml. Without either one, nothing sets up the runtime.

grep -rn "transformIndexHtml\|plugin-react/preamble" src server 2>/dev/null

2Fix

Import the preamble at the top of the client entry file, or run your HTML through transformIndexHtml on the server.

// client entry, first line
import '@vitejs/plugin-react/preamble'

3Verify

Restart the dev server and hard-reload the page.

npm run dev

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Wrap the dev tags in your template behind a debug flag, so production loads the built files from the manifest instead.
  • Keep the dev server origin in one setting that both the template and vite.config read.

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.