Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Assets and CSS

Static Assets and the public Directory

Learn how Vite handles images, fonts and other assets, when to import them from src or place them in public, the ?url, ?raw and ?inline suffixes, hashing and assetsInlineLimit.

Images, fonts, icons, videos and data files are part of every web app. Vite gives you two ways to deal with them, and choosing the right one decides whether your files get cache-friendly hashed names and build-time checks, or are copied untouched to a fixed URL. This lesson explains both, plus the import suffixes that change how an asset is loaded.

Vite is not installed on this site, so the project examples are read-only. The runnable stand-ins model hashing and inlining decisions in Node.js and show how assets behave in an HTML page.

Way 1: import it from code

Any file you import from JavaScript or reference from CSS/HTML inside your project is treated as an asset in the module graph. By default an imported image resolves to its final URL string:

JavaScript
import logoUrl from './assets/logo.svg';

document.querySelector('#logo').src = logoUrl;
// development: '/src/assets/logo.svg'
// production : '/assets/logo-3f9a2c1b.svg'

What Vite does in a build:

  • copies the file to dist/assets/ with a content hash in the name (logo-3f9a2c1b.svg),
  • rewrites every reference to the hashed name,
  • applies the base option to the URL,
  • fails the build if the file is missing.

Content hashes are what make long-term caching safe. Serve hashed files with Cache-Control: max-age=31536000, immutable; when the file changes, its name changes, so users never see an old copy.

The same applies in templates and CSS:

HTML
<img src="/src/assets/hero.jpg" alt="Hero">          <!-- index.html -->
CSS
.hero { background: url('./assets/hero.jpg'); }       /* in a CSS file */

Both URLs are rewritten to hashed output names. Vue, Svelte and similar templates get the same treatment through their plugins (<img src="./hero.jpg"> is converted to an import).

Supported types

Out of the box: images (png, jpg, jpeg, gif, svg, webp, avif, ico), media (mp4, webm, ogg, mp3, wav, flac, aac) and fonts (woff, woff2, eot, ttf, otf) among others, plus webmanifest and pdf. Add more with the assetsInclude option:

JavaScript
export default defineConfig({
  assetsInclude: ['**/*.gltf', '**/*.glb'],
});

Way 2: the public directory

Files in public/ are served at the root path in development and copied to the output root as-is:

TEXT
public/robots.txt      ->  /robots.txt
public/favicon.svg     ->  /favicon.svg
public/data/cities.json ->  /data/cities.json

Use them with an absolute URL (/favicon.svg), never /public/favicon.svg. You cannot import them from JavaScript source (use the URL string directly). They are not hashed, not optimized and not checked at build time.

Pick public when:

  • the file must keep its exact name (robots.txt, sitemap.xml, manifest.json for some setups, .well-known/ files),
  • the URL must be stable and known by other systems (a link in an email, an Open Graph image path),
  • the file is huge or never referenced from code (downloads, large videos),
  • a third-party script expects a fixed path (a service worker at /sw.js).

Pick src/assets (import it) for everything else, especially images and fonts used by your UI.

Choosing at a glance

src/assets or public?

Import from src Hashed, optimized, checked
Put in public Copied as-is, fixed URL

Default to importing.

1 / 2

Import suffixes

A query suffix changes how an import behaves:

Import Result
import url from './a.png' The final URL string
import url from './a.png?url' Force URL, even for types Vite would treat as code (like .js or .css)
import raw from './note.txt?raw' File contents as a string
import inlined from './a.png?inline' A data: URL (base64), never a separate file
import Worker from './w.js?worker' A Web Worker constructor
import wasm from './m.wasm?init' A function that instantiates the WebAssembly module
import css from './a.css?inline' CSS text, not injected into the page

?raw is excellent for loading shaders, SQL, markdown or HTML snippets at build time. ?inline embeds small images in your JavaScript and saves a request.

Automatic inlining: assetsInlineLimit

In production, assets smaller than 4 KiB (4096 bytes) are inlined as base64 data: URLs automatically, because a tiny request costs more than the bytes. Change the threshold:

JavaScript
export default defineConfig({
  build: {
    assetsInlineLimit: 8192, // inline up to 8 KiB; 0 disables inlining
  },
});

public files are never inlined. SVGs are not inlined unless ?inline is used, in some Vite versions, so check the output when in doubt.

This stand-in applies the decision rules and computes a hash-like name for each file. It is a model: Vite uses a different hash function, but the logic is the same.

Node.js Stand-in: inline or emit with a hash?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Using assets in an HTML page

This runnable page shows two assets from our own sample files. In a Vite project, the src would point to a file in src/assets or public.

An image and its alt text

Dynamic URLs and the new URL pattern

A variable path cannot be analysed at build time:

JavaScript
const img = './assets/' + name + '.png';   // Vite cannot know which files you mean

The safe pattern is new URL(relative, import.meta.url), which Vite understands for static strings:

JavaScript
const logo = new URL('./assets/logo.png', import.meta.url).href;

For a family of files chosen at run time, use import.meta.glob, covered in Asset URLs and Glob Imports.

Common mistakes

  • Writing /public/logo.png in code. The real URL is /logo.png.
  • Referencing a src image with a wrong case. Works on Windows or macOS, 404 on a Linux server.
  • Expecting public files to change names. They never get hashes, so set cache headers carefully.
  • Dynamic string concatenation for imports. Use new URL with a literal or import.meta.glob.
  • Deploying under a sub-folder without base. Absolute URLs then point at the wrong place; set base.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the URL of public/robots.txt in your site?

    Files in public are served from the site root, and the folder name is not part of the URL.
  2. 2. Why does Vite add a content hash to imported asset filenames?

    Hashed names let you use immutable, long-lived cache headers safely.
  3. 3. How do you read a file's text content at build time?

    The ?raw suffix returns the file contents as a string.
  4. 4. What does build.assetsInlineLimit control?

    The default is 4096 bytes. Smaller assets are inlined to save requests.

Summary

  • Imported assets get hashed names, optimization and build-time checks; public files are copied untouched to a fixed URL.
  • Use public for fixed names and stable URLs; import everything else.
  • Suffixes: ?url, ?raw, ?inline, ?worker, ?init change how an import resolves.
  • Assets under 4 KiB are inlined by default; tune with build.assetsInlineLimit.
  • Use new URL('./x.png', import.meta.url) or import.meta.glob for dynamic paths.

Next: Importing CSS and CSS Modules