Local images do not show up in a React app built with Vite
Broken image icon where <img src="./logo.png"> should showShort 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.
Fix it fast
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 public2Match what you see, then jump to its fix
- 1
The 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
404 for a public file referenced as ./public/x.png or imported in JSA file in public is referenced wronglyFix - 3
Images chosen by a variable name, such as `./img/${name}.png`, 404 only in the production buildThe path is built at runtimeFix - 4
TypeScript reports that the module cannot be found for an image import './logo.png' or its corresponding type declarationsTypeScript does not know image importsFix
- 1
What does the error look like?
Broken image icon where <img src="./logo.png"> should show404 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=\"\./" src2Fix
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 previewConfirmed by vite.dev
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 public2Fix
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.pngConfirmed by vite.dev
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" src2Fix
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 previewConfirmed by vite.dev
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 src2Fix
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 --noEmitConfirmed by vite.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
TypeScript refuses JSX because the jsx option is not set
TS17004: Cannot use JSX unless the '--jsx' flag is provided.
TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option.
2 causes, each with a fixWeb apps
TypeScript rejects a component that returns an array or other non-Element
Its return type 'Element[]' is not a valid JSX element.
TypeScript before 5.1 required every component to return JSX.Element or null, so arrays, strings and Promises were rejected even though React renders them.
2 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint reports no-unused-vars for React components and imports that are used
no-unused-vars reported for a component that is rendered as a JSX tag
ESLint's core no-unused-vars does not see variables used only as JSX tags, so a component imported and rendered as <Hello /> looks unused.
3 causes, each with a fixWeb 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 fixWeb apps
The renderInput prop stopped working on the MUI X DatePicker
The custom TextField (variant, size, helperText) is ignored
renderInput was removed from the MUI X date pickers in version 6.
3 causes, each with a fix