Vite Syntax Assets

vite-syntax-assets

Quick Reference

Asset Import Behavior

import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl

Assets smaller than assetsInlineLimit (default: 4096 bytes / 4 KiB) are inlined as base64 data URLs. Git LFS placeholders are ALWAYS excluded from inlining.

Query Suffixes Table

Critical Warnings

NEVER use variables or expressions in import.meta.glob arguments -- ALWAYS use string literals. Vite performs static analysis at build time and cannot evaluate runtime values.

NEVER rely on new URL(path, import.meta.url) in SSR code -- import.meta.url has different semantics in browsers vs Node.js. This pattern is client-only.

NEVER import public directory assets with import statements -- reference them as absolute URL paths (/icon.png). Public assets are copied as-is without processing.

ALWAYS use static strings in new URL() patterns -- dynamic expressions prevent Vite from analyzing and transforming the import at build time.

Asset Import Patterns

Standard Import (Auto-detected Types)

Common image, media, and font types are automatically detected:

import logo from './logo.svg'
import video from './intro.mp4'
import font from './custom.woff2'

CSS url() references are handled automatically with the same resolution logic.

Explicit URL Import (?url)

For file types NOT in the auto-detected list:

import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)

Raw String Import (?raw)

import shaderString from './shader.glsl?raw'

new URL() Pattern

Uses native ESM for asset resolution:

const imgUrl = new URL('./img.png', import.meta.url).href

Supports template literals for dynamic paths (static analysis still applies):

function getImageUrl(name) {
  return new URL(`./dir/${name}.png`, import.meta.url).href
}

Constraints: The URL string MUST be static or a template literal with a static prefix. Does NOT work with SSR.

Additional Asset Types (assetsInclude)

Register custom file types as assets:

// vite.config.js
export default defineConfig({
  assetsInclude: ['**/*.gltf', '**/*.hdr'],
})

Public Directory

Behavior:

• Files served at root / during development
• Copied to dist/ root during build (no hashing, no transforms)
• Reference as absolute paths: public/icon.png becomes /icon.png in code

When to use public directory:

• Files never referenced in source code (e.g., robots.txt, favicon.ico)
• Files that MUST retain exact filenames (no content hashing)
• Files that need no processing

ALWAYS prefer import for assets that ARE referenced in source code -- this enables hashing, tree-shaking, and assetsInlineLimit optimization.

JSON Imports

// Full object import
import json from './example.json'

// Named export (tree-shakeable)
import { field } from './example.json'

Glob Import (import.meta.glob)

Options Table

Lazy Loading (Default)

const modules = import.meta.glob('./dir/*.js')
// Result: { './dir/foo.js': () => import('./dir/foo.js'), ... }

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod)
  })
}

Eager Loading

const modules = import.meta.glob('./dir/*.js', { eager: true })
// Result: { './dir/foo.js': Module, ... }

Multiple and Negative Patterns

const modules = import.meta.glob(['./dir/*.js', './another/*.js'])
const filtered = import.meta.glob(['./dir/*.js', '!**/bar.js'])

Named Imports (Tree-Shakeable)

const setups = import.meta.glob('./dir/*.js', { import: 'setup', eager: true })
// Transforms to: import { setup as ... } from './dir/foo.js'

Use import: 'default' for default exports.

Custom Queries

const rawSvgs = import.meta.glob('./dir/*.svg', { query: '?raw', import: 'default' })
const svgUrls = import.meta.glob('./dir/*.svg', { query: '?url', import: 'default' })
const custom = import.meta.glob('./dir/*.js', { query: { foo: 'bar', bar: true } })

Base Path Option

const modules = import.meta.glob('./**/*.js', { base: './base' })
// Keys: './dir/foo.js' -> resolves to './base/dir/foo.js'

Base MUST be a relative directory path or absolute against project root. Aliases and virtual modules are NOT supported as base.

Glob Caveats

• Vite-only feature -- NOT a web or ES standard
• String literals ONLY -- NEVER use variables, expressions, or template literals as arguments
• Patterns MUST be relative (./), absolute (/), or alias paths
• Matching uses tinyglobby internally

WebAssembly

?init Import

import init from './example.wasm?init'

init().then((instance) => {
  instance.exports.test()
})

With Import Object

import init from './example.wasm?init'

init({
  imports: {
    someFunc: () => { /* ... */ },
  },
}).then(() => { /* ... */ })

Multiple Instances (URL Import)

import wasmUrl from './example.wasm?url'

const response = await fetch(wasmUrl)
const { module, instance } = await WebAssembly.instantiateStreaming(response)

Production: .wasm files smaller than assetsInlineLimit are inlined as base64.

Web Workers

Constructor Pattern (Recommended)

const worker = new Worker(new URL('./worker.js', import.meta.url))

// Module worker
const moduleWorker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
})

Constraint: new URL() MUST appear directly inside new Worker(). All options MUST be static values.

Query Suffix Pattern

import MyWorker from './worker?worker'
const worker = new MyWorker()

// Inline (base64)
import InlineWorker from './worker?worker&inline'

// URL only
import workerUrl from './worker?worker&url'

Worker scripts can use ESM import statements (native in dev, compiled for production).

Asset Configuration Reference

HTML Asset Elements

Vite processes asset references in these HTML elements: <script src>, <link href>, <img src>, <img srcset>, <video src>, <video poster>, <audio src>, <source src>, <embed src>, <object data>, <track src>, <input src>, <meta content>.

Add the vite-ignore attribute to any HTML element to skip asset processing for that element.

Reference Links

• references/import-patterns.md -- Complete import suffix reference, glob options, worker patterns
• references/examples.md -- Working code examples for assets, glob, JSON, WebAssembly, workers
• references/anti-patterns.md -- Common asset handling mistakes and how to avoid them

Official Sources

• https://vite.dev/guide/assets
• https://vite.dev/guide/features#glob-import
• https://vite.dev/guide/features#json
• https://vite.dev/guide/features#web-workers
• https://vite.dev/guide/features#webassembly
• https://vite.dev/config/shared-options#publicdir
• https://vite.dev/config/build-options#build-assetsinlinelimit