Configuration
Nuxt Image is configured with sensible defaults.
To configure the image module and customize its behavior, you can use the image
property in your nuxt.config
:
export default defineNuxtConfig({
image: {
// Options
}
})
screens
List of predefined screen sizes.
These sizes will be used to generate resized and optimized versions of an image (for example, with the sizes
modifier).
export default defineNuxtConfig({
image: {
// The screen sizes predefined by `@nuxt/image`:
screens: {
xs: 320,
sm: 640,
md: 768,
lg: 1024,
xl: 1280,
xxl: 1536,
'2xl': 1536
},
}
})
domains
To enable image optimization on an external website, specify which domains are allowed to be optimized. This option will be used to detect whether a remote image should be optimized or not. This is needed to ensure that external urls can't be abused.
export default defineNuxtConfig({
image: {
domains: ['nuxtjs.org']
}
})
presets
Presets are collections of pre-defined configurations for your projects. Presets will help you to unify images all over your project.
export default defineNuxtConfig({
image: {
presets: {
avatar: {
modifiers: {
format: 'jpg',
width: 50,
height: 50
}
}
}
}
})
providers
In order to create and use a custom provider, you need to use the providers
option and define your custom providers.
export default defineNuxtConfig({
image: {
providers: {
random: {
provider: '~/providers/random',
options: {}
}
}
}
})
provider
Default: static
We can specify default provider to be used when not specified in component or when calling $img
.
export default defineNuxtConfig({
image: {
provider: 'twicpics',
twicpics: {
baseURL: 'https://nuxt-demo.twic.pics'
}
}
})
modifiers
You can set default modifiers for the selected provider.
export default defineNuxtConfig({
image: {
provider: 'cloudinary',
cloudinary: {
baseURL: 'https://res.cloudinary.com/<company>/image/fetch/',
modifiers: {
effect: 'sharpen:100',
quality: 'auto:best',
}
}
}
})
staticFilename
You can use this option to change filename and location for the static image generation.
Parameters
[name]
: Only filename, without extension or path[hash]
: The hash of url[ext]
: Extension with leading dot.png
[publicPath]
: Default isbuild.publicPath
(/_nuxt
)
export default defineNuxtConfig({
image: {
// Generate images to `/_nuxt/images/file.png`
staticFilename: '[publicPath]/images/[name]-[hash][ext]'
}
})
dir
Default: static
This option allows you to specify the location of the source images when using the static
or ipx
provider.
For example you might want the source images in assets/images
directory rather than the default static
directory so the source images don't get copied into dist
and deployed:
export default defineNuxtConfig({
image: {
dir: 'assets/images'
}
})
Notes:
- For
static
provider, if images weren't crawled during generation (unreachable modals, pages or dynamic runtime size), changingdir
fromstatic
causes 404 errors. - For
ipx
provider, make sure to deploy customizeddir
as well. - For some providers (like vercel), using a directory other than
static/
for assets is not supported since resizing happens at runtime (instead of build/generate time) and source fetched from thestatic/
directory (deployment URL)
alias
This option allows you to specify aliases for src
.
When using the default ipx provider, URL aliases are shortened on the server-side. This is especially useful for optimizing external URLs and not including them in HTML.
When using other providers, aliases are resolved in runtime and included in HTML. (only the usage is simplified)
Example:
export default defineNuxtConfig({
image: {
domains: [
'images.unsplash.com'
],
alias: {
unsplash: 'https://images.unsplash.com'
}
}
})
Before using alias:
<nuxt-img src="https://images.unsplash.com/<id>" />
Generates:
<img src="/_ipx/https://images.unsplash.com/<id>">
After using alias:
<nuxt-img src="/unsplash/<id>" />
Generates:
<img src="/_ipx/unsplash/<id>" />
Both usage and output are simplified!