Maaz Zindani

Loading the index…

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

Local images do not show up in a React app built with Vite

ErrorBroken image icon where <img src="./logo.png"> should show

Short answer

In a Vite React app, an image in src must be imported or referenced with new URL(..., import.meta.url); a plain relative string breaks after the build. Files in public are served from the root path and are never imported. TypeScript also needs the vite/client types to accept image imports.

  • Applies to Vite 7, React 19, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser network tab and look at the image request. A 404 shows the exact URL the browser asked for. Compare it with where the file really is.

    ls src/assets public
  2. 2Match what you see, then jump to its fix

    1. 1The image works in one place or in dev, but not after build, or the request returns 404The file is in src but used as a plain string pathFix
    2. 2404 for a public file referenced as ./public/x.png or imported in JSA file in public is referenced wronglyFix
    3. 3Images chosen by a variable name, such as `./img/${name}.png`, 404 only in the production buildThe path is built at runtimeFix
    4. 4TypeScript reports that the module cannot be found for an image import './logo.png' or its corresponding type declarationsTypeScript does not know image importsFix

What does the error look like?

  • Broken image icon where <img src="./logo.png"> should show
  • 404 for the image in the browser network tab

Cause 1 of 4

The file is in src but used as a plain string path

1Check

Vite handles assets that are imported. Importing returns the public URL: /src/img.png in dev, a hashed /assets/... path in production.

grep -rn "src=\"\./" src

2Fix

Import the file and use the result as the source.

import logo from './assets/logo.png'

export default function Header() {
  return <img src={logo} alt="Logo" />
}

3Verify

Build and preview. The image request should return 200 with a hashed name.

npm run build
npm run preview

Confirmed by vite.dev

Did this fix it?

Cause 2 of 4

A file in public is referenced wrongly

1Check

Files in public are served at the root in dev and copied to the root of dist unchanged. They are not imported in JavaScript.

ls public

2Fix

Reference them with a root-absolute path and leave out the folder name.

// public/icon.png
<img src="/icon.png" alt="Icon" />

3Verify

Open /icon.png in the browser directly; it should load.

curl -I http://localhost:5173/icon.png

Confirmed by vite.dev

Did this fix it?

Cause 3 of 4

The path is built at runtime

1Check

The URL string in new URL(path, import.meta.url) must be static for the production build to transform it. Dynamic paths are left as they are.

grep -rn "import.meta.url" src

2Fix

Use a static string for each file, or move the images to public and build the root-absolute path from the name.

const imgUrl = new URL('./img.png', import.meta.url).href
// or, for files in public:
const dyn = `/images/${name}.png`

3Verify

Run the production build and open the page that uses the image.

npm run build && npm run preview

Confirmed by vite.dev

Did this fix it?

Cause 4 of 4

TypeScript does not know image imports

1Check

By default TypeScript does not treat static asset imports as valid modules. Including vite/client in the project's types fixes that.

grep -rn "vite/client" tsconfig*.json src

2Fix

Add the Vite client types, either in a declaration file or in tsconfig types.

// src/vite-env.d.ts
/// <reference types="vite/client" />

3Verify

Run the type check.

npx tsc --noEmit

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Import images that live in src; keep public for files that need a fixed name.
  • Check the production build, not only the dev server, after adding images.
  • Keep vite/client in the project types.

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

Web apps

TypeScript rejects MUI Data Grid columns that set a type

A TypeScript error inside a column's renderCell callback

A columns array declared without a type is inferred with type as a plain string, which the Data Grid's column type union does not accept.

2 causes, each with a fix

Next step

Want this handled for good?

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