Vite treats images, SVGs, and other static files as first-class modules. This lesson covers importing assets, automatic content hashing for caching, special query suffixes like ?url and ?raw, the small-asset inlining threshold, and handling dynamic asset paths at runtime.
1Images Are Modules, Too
Importing an image in Vite works like importing any other module: the import resolves to a string URL usable directly as a src attribute. This single import gets automatic optimization, cache-busting filenames, and dead-asset elimination without any extra configuration.
2Content-Hashed Filenames in Production
During the production build, Vite renames imported assets with a hash derived from their contents, so any change to a file produces a new filename. This makes it safe to configure aggressive, long-term browser caching for assets, since a genuinely changed file will always be requested under a new URL.
3Special Import Query Suffixes
Vite recognizes special query suffixes to change how an asset import resolves: ?url explicitly forces a string URL, ?raw imports the file's contents as plain text, and ?inline forces the asset to be inlined as a base64 data URI regardless of its size.
4The assetsInlineLimit Threshold
Assets smaller than a configurable size threshold (4KB by default) are automatically inlined as base64 data URIs directly inside the referencing JavaScript or CSS, avoiding an extra network request for tiny files. Larger assets are always emitted as separate, hashed files, tunable through build.assetsInlineLimit.
5Dynamic Asset URLs with new URL()
When an asset path is only known at runtime, a static import statement can't express it. Vite recognizes the standard new URL('./path', import.meta.url) pattern even with dynamic segments, and still processes and hashes the referenced files correctly at build time.
6Step-by-Step Breakdown
Images Are Modules, Too. In Vite, importing an image works just like importing a JavaScript module: import logo from './logo.png' gives you back a string URL you can drop into an <img src={logo} />. This one line gets you automatic optimization, cache-busting filenames, and dead-asset elimination for free.
Content-Hashed Filenames in Production. When you build for production, Vite renames every imported asset with a content hash: logo.png becomes something like logo.a3f9c1.png. If the file's contents ever change, the hash changes too, which means you can safely cache assets forever in the browser ā a new deploy automatically gets a new filename.
Why does Vite rename imported assets with a content hash in the production build?
- āSo changed files get a new URL, enabling safe long-term browser caching
- āTo prevent other websites from viewing the image
Special Import Query Suffixes. Vite recognizes special suffixes on asset imports to change what you get back. ?url explicitly forces a URL string (useful when the default behavior for that file type differs), ?raw imports a file's contents as a plain text string, and ?inline forces a small asset to be inlined as a base64 data URI instead of a separate file.
The assetsInlineLimit Threshold. By default, Vite automatically inlines very small assets (under 4KB by default) as base64 data URIs directly in your JavaScript or CSS, skipping a separate network request entirely. Larger assets are always emitted as separate hashed files. You can tune this threshold with the build.assetsInlineLimit config option.
What happens by default to a very small asset (under the inline limit) imported in your code?
- āIt's automatically inlined as a base64 data URI, avoiding a separate request
- āIt's always emitted as a separate hashed file regardless of size
Dynamic Asset URLs with new URL(). When an asset's filename is only known at runtime ā for example, building an image path from a variable ā a static import won't work. Vite supports the standard new URL('./path.png', import.meta.url) pattern for this case, which it still recognizes and processes at build time, hashing the referenced file correctly.
Mastery Achieved. You now know how Vite handles assets: images as regular module imports, automatic content-hashed filenames for safe caching, special ?url/?raw/?inline query suffixes, the small-asset inlining threshold, and the new URL() pattern for dynamic asset paths. Next, you'll see what actually happens when you run a production build.
Level Up š
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
The new URL(..., import.meta.url) pattern relies on native import.meta support, present in all modern browsers.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Optimized Images Still Need Meaningful alt Text
Vite's automatic asset optimization has nothing to do with accessibility ā every <img> using an imported asset still needs a descriptive alt attribute (or an empty alt="" for purely decorative images) written by the developer.
SEO Implications
- 1
Content-Hashed Assets Enable Aggressive Caching Without Stale Content Risk
Long-lived cache headers on hashed asset filenames improve repeat-visit load times, a factor in performance-based ranking signals, while guaranteeing users never see a stale cached version after a deploy.
Best Practices
Import Assets You Reference in JSX Rather Than Hardcoding Paths
Importing gives you build-time verification that the file exists, automatic optimization, and correct hashed URLs ā a hardcoded string path bypasses all of that and is prone to silently breaking after a file move.
Use ?raw Sparingly, for Genuinely Text-Based Needs
Reserve the ?raw suffix for cases like embedding raw SVG markup or a code snippet's source text directly ā for anything meant to be an image src, the default import behavior is almost always correct.
Frequent Bugs
An imported image works in development but 404s after the production build.
The image was likely referenced by a hardcoded string path somewhere instead of a proper ES module import ā only imported assets get processed, hashed, and correctly emitted into the build output.
A large background image ends up inlined as a bulky base64 string in the CSS bundle.
The file is under the current build.assetsInlineLimit threshold. Either explicitly force it to stay a separate file with the ?url suffix, or lower assetsInlineLimit in vite.config.ts.
Real-World Examples
Rendering a Dynamic Country Flag Icon
A settings page lets users pick their country from a dropdown, and each option needs a small flag icon whose filename depends on the selected country code, which isn't known until runtime. Using new URL(`./flags/${code}.svg`, import.meta.url).href let Vite still correctly process, optimize, and hash every flag file referenced across the whole flags/ folder.
function FlagIcon({ countryCode }: { countryCode: string }) {
const src = new URL(`./flags/${countryCode}.svg`, import.meta.url).href;
return <img src={src} alt={`${countryCode} flag`} width={20} />;
}