Explicit inline control with ?inline and ?no-inline suffixes
Assets can be explicitly imported with inlining or no inlining using the `?inline` or `?no-inline` suffix respectively.
assets/importing
47 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Import asset as string with ?raw suffix
Assets can be imported as strings using the `?raw` suffix, for example: `import shaderString from './shader.glsl?raw'`.
Static asset import returns resolved public URL
When importing a static asset, it returns the resolved public URL when served. During development, the URL is the absolute public path based on project root (e.g., `/src/img.png`). In production build, it includes a hash (e.g., `/assets/img.2d8efhg.png`). This behavior is similar to webpack's file-loader.
Common asset filetypes detected automatically
Common image, media, and font filetypes are detected as assets automatically. You can extend the internal list using the `assetsInclude` configuration option.
Assets inlined as base64 below assetsInlineLimit
Assets smaller in bytes than the `assetsInlineLimit` configuration option will be inlined as base64 data URLs.
CSS url() references handled like asset imports
`url()` references in CSS are handled the same way as asset imports, returning resolved public URLs.
Vue SFC templates auto-convert asset references to imports
If using the Vue plugin, asset references in Vue SFC templates are automatically converted into imports.
Referenced assets get hashed filenames in production
Referenced assets are included as part of the build assets graph, will get hashed file names, and can be processed by plugins for optimization.
Git LFS placeholders excluded from inlining
Git LFS placeholders are automatically excluded from inlining because they do not contain the content of the file they represent. To get inlining, make sure to download the file contents via Git LFS before building.
TypeScript does not recognize static asset imports by default
TypeScript, by default, does not recognize static asset imports as valid modules. To fix this, include `vite/client` in your project.
SVG url() wrapping requires double quotes
When passing a URL of SVG to a manually constructed `url()` by JavaScript, the variable should be wrapped within double quotes, for example: `url("${imgUrl}")`.
Explicit URL imports with ?url suffix
Assets that are not included in the internal list or in `assetsInclude` can be explicitly imported as a URL using the `?url` suffix. This is useful, for example, to import Houdini Paint Worklets.
HTML asset references
Assets referenced by HTML elements are processed and bundled as part of the app. Supported HTML elements include: `<audio src>`, `<embed src>`, `<img src>` and `<img srcset>`, `<image href>` and `<image xlink:href>`, `<input src>`, `<link href>` and `<link imagesrcset>`, `<object data>`, `<script type="module" src>`, `<source src>` and `<source srcset>`, `<track src>`, `<use href>` and `<use xlink:href>`, `<video src>` and `<video poster>`, and `<meta content>` (only with specific name or property attributes for app icons and OG/Twitter images).
vite-ignore attribute for HTML processing
To opt-out of HTML processing on certain elements, add the `vite-ignore` attribute on the element, which can be useful when referencing external assets or CDN.
CSS import injection via style tag
Importing .css files will inject its content to the page via a `<style>` tag with HMR support.
CSS @import inlining and URL rebasing
Vite is pre-configured to support CSS `@import` inlining via `postcss-import`. Vite aliases are also respected for CSS `@import`. In addition, all CSS `url()` references, even if the imported files are in different directories, are always automatically rebased to ensure correctness.
PostCSS automatic application
If the project contains valid PostCSS config (any format supported by postcss-load-config, e.g. `postcss.config.js`), it will be automatically applied to all imported CSS. CSS minification will run after PostCSS and will use the `build.cssTarget` option.
CSS Modules naming convention
Any CSS file ending with `.module.css` is considered a CSS modules file. Importing such a file will return the corresponding module object.
CSS Modules import example
Example of importing CSS Modules: ```css .red { color: red; } ``` ```js import classes from './example.module.css' document.getElementById('foo').className = classes.red ``` CSS modules behavior can be configured via the `css.modules` option.
CSS Modules camelCase named imports
If `css.modules.localsConvention` is set to enable camelCase locals (e.g. `localsConvention: 'camelCaseOnly'`), you can also use named imports: `import { applyColor } from './example.module.css'` where `.apply-color` is converted to `applyColor`.
CSS pre-processors supported
Vite provides built-in support for `.scss`, `.sass`, `.less`, `.styl` and `.stylus` files. There is no need to install Vite-specific plugins, but the corresponding pre-processor itself must be installed: `npm add -D sass-embedded` (or `sass`) for .scss/.sass, `npm add -D less` for .less, or `npm add -D stylus` for .styl/.stylus.
Sass and Less @import and URL rebasing
Vite improves `@import` resolving for Sass and Less so that Vite aliases are also respected. In addition, relative `url()` references inside imported Sass/Less files that are in different directories from the root file are also automatically rebased to ensure correctness. Rebasing `url()` references that start with a variable or an interpolation is not supported due to API constraints.
CSS modules with pre-processors
You can use CSS modules combined with pre-processors by prepending `.module` to the file extension, for example `style.module.scss`.
Disabling CSS injection with ?inline
The automatic injection of CSS contents can be turned off via the `?inline` query parameter. In this case, the processed CSS string is returned as the module's default export as usual, but the styles aren't injected to the page. Example: `import otherStyles from './bar.css?inline'`.
Lightning CSS for production minification
Vite uses Lightning CSS to minify CSS in production builds by default. However, PostCSS is still used for other CSS processing. There is experimental support for using Lightning CSS for CSS processing entirely via `css.transformer: 'lightningcss'`. To configure it, pass Lightning CSS options to the `css.lightningcss` config option.
Static asset import returns public URL
Importing a static asset will return the resolved public URL when it is served. Example: `import imgUrl from './img.png'` allows using the URL directly.
Asset import with ?url query
Use the `?url` query to explicitly load assets as URL (automatically inlined depending on the file size). Example: `import assetAsURL from './asset.js?url'`.
Asset import with ?raw query
Use the `?raw` query to load assets as strings. Example: `import assetAsString from './shader.glsl?raw'`.
JSON file direct import
JSON files can be directly imported - named imports are also supported. Example: `import json from './example.json'` imports the entire object, or `import { field } from './example.json'` imports a root field as named exports which helps with tree-shaking.
Glob import basic usage
Vite supports importing multiple modules from the file system via the special `import.meta.glob` function. Example: `const modules = import.meta.glob('./dir/*.js')` transforms to an object where keys are file paths and values are functions that return promises from dynamic imports.
Glob import eager loading
Glob imports are lazy-loaded by default and split into separate chunks. To import all modules directly, pass `{ eager: true }` as the second argument. This transforms the code to use static imports and creates a module object where keys map to imported modules.
Glob import multiple patterns
The first argument to `import.meta.glob` can be an array of globs. Example: `const modules = import.meta.glob(['./dir/*.js', './another/*.js'])`.
Glob import negative patterns
Negative glob patterns are also supported (prefixed with `!`). To ignore some files from the result, add exclude glob patterns to the first argument. Example: `const modules = import.meta.glob(['./dir/*.js', '!**/bar.js'])`.
Glob import named imports
Use the `import` option to only import parts of the modules. Example: `const modules = import.meta.glob('./dir/*.js', { import: 'setup' })` only imports the `setup` export. When combined with `eager: true`, tree-shaking is enabled for those modules.
Glob import default export
Set `import` to `default` to import the default export. Example: `const modules = import.meta.glob('./dir/*.js', { import: 'default', eager: true })`.
Glob import custom queries
Use the `query` option to provide queries to imports. Example: `const moduleStrings = import.meta.glob('./dir/*.svg', { query: '?raw', import: 'default' })` or `const moduleUrls = import.meta.glob('./dir/*.svg', { query: '?url', import: 'default' })`.
Glob import base path
Use the `base` option to provide a base path for the imports. Example: `const modulesWithBase = import.meta.glob('./**/*.js', { base: './base' })`. The base option can only be a directory path relative to the importer file or absolute against the project root. Only globs that are relative paths are interpreted as relative to the resolved base.
Glob import case-sensitive matching
By default, glob pattern matching is case-sensitive. You can use the `caseSensitive` option to change this behavior. Example: `const modules = import.meta.glob('./dir/module*.js', { caseSensitive: false })`.
Glob import caveats
Glob import is a Vite-only feature and is not a web or ES standard. The glob patterns are treated like import specifiers: they must be either relative (start with `./`) or absolute (start with `/`, resolved relative to project root) or an alias path. The glob matching is done via `tinyglobby`. All arguments in `import.meta.glob` must be passed as literals - you cannot use variables or expressions.
Dynamic import with variables
Vite supports dynamic import with variables similar to glob import. Example: `const module = await import(`./dir/${file}.js`)`. Note that variables only represent file names one level deep. If `file` is `'foo/bar'`, the import would fail.
Dynamic import bundling rules
For dynamic import to be bundled, imports must: start with `./` or `../` (e.g. `import(`./dir/${foo}.js`)` is valid, but `import(`${foo}.js`)` is not), end with a file extension (e.g. `import(`./dir/${foo}.js`)` is valid, but `import(`./dir/${foo}`)` is not), and specify a file name pattern for same directory imports (e.g. `import(`./prefix-${foo}.js`)` is valid, but `import(`./${foo}.js`)` is not).
WebAssembly ESM integration
A `.wasm` file can be imported directly as an ES module. Vite reads the module's imports and exports from the binary, instantiates it, and re-exposes its exports as named ES module exports. Example: `import { add } from './add.wasm'` then `console.log(add(1, 2))`. This follows the WebAssembly/ES Module Integration proposal. A directly imported `.wasm` file behaves as an async module and requires top-level `await` support.
WebAssembly module instantiation
If the WebAssembly module declares imports of its own, Vite resolves them from JavaScript modules. Each import's module name is treated as an import specifier (resolved relative to the `.wasm` file) and the requested members are wired into the instance automatically.
WebAssembly ?init query for manual initialization
When you need control over when and how the module is instantiated, import with `?init`. The default export will be an initialization function that returns a Promise of the `WebAssembly.Instance`. Example: `import init from './example.wasm?init'` then `init().then((instance) => { instance.exports.test() })`.
WebAssembly ?init with importObject
The init function can also take an importObject which is passed along to `WebAssembly.instantiate` as its second argument. Example: `init({ imports: { someFunc: () => { /* ... */ } } }).then(() => { /* ... */ })`.
WebAssembly inline threshold
In the production build, `.wasm` files smaller than `assetsInlineLimit` will be inlined as base64 strings. Otherwise, they will be treated as a static asset and fetched on-demand.
WebAssembly Module object access
To access the `Module` object (e.g. to instantiate it multiple times), use an explicit URL import to resolve the asset, then perform the instantiation manually. Example: `import wasmUrl from 'foo.wasm?url'` then `const responsePromise = fetch(wasmUrl)` and `const { module, instance } = await WebAssembly.instantiateStreaming(responsePromise)`.