- Related: Public Base Path
- Related:
assetsInclude
config option
Importing a static asset will return the resolved public URL when it is served:
import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
For example, imgUrl
will be /img.png
during development, and become /assets/img.2d8efhg.png
in the production build.
The behavior is similar to webpack's file-loader
. The difference is that the import can be either using absolute public paths (based on project root during dev) or relative paths.
-
url()
references in CSS are handled the same way. -
If using the Vue plugin, asset references in Vue SFC templates are automatically converted into imports.
-
Common image, media, and font filetypes are detected as assets automatically. You can extend the internal list using the
assetsInclude
option. -
Referenced assets are included as part of the build assets graph, will get hashed file names, and can be processed by plugins for optimization.
-
Assets smaller in bytes than the
assetsInlineLimit
option will be inlined as base64 data URLs.
Assets that are not included in the internal list or in assetsInclude
, can be explicitly imported as an URL using the ?url
suffix. This is useful, for example, to import Houdini Paint Worklets.
import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)
Assets can be imported as strings using the ?raw
suffix.
import shaderString from './shader.glsl?raw'
Scripts can be imported as web workers with the ?worker
or ?sharedworker
suffix.
// Separate chunk in the production build
import Worker from './shader.js?worker'
const worker = new Worker()
// Inlined as base64 strings
import InlineWorker from './shader.js?worker&inline'
Check out the Web Worker section for more details.
If you have assets that are:
- Never referenced in source code (e.g.
robots.txt
) - Must retain the exact same file name (without hashing)
- ...or you simply don't want to have to import an asset first just to get its URL
Then you can place the asset in a special public
directory under your project root. Assets in this directory will be served at root path /
during dev, and copied to the root of the dist directory as-is.
The directory defaults to <root>/public
, but can be configured via the publicDir
option.
Note that:
- You should always reference
public
assets using root absolute path - for example,public/icon.png
should be referenced in source code as/icon.png
. - Assets in
public
cannot be imported from JavaScript.