Installation

Using image module in your Nuxt 2 project is only one command away. ✨


Image module only works with Nuxt 2 and is not compatible with Nuxt 3, yet. Track the progress in this issue.

Add @nuxt/image devDependency to your project:

yarn
yarn add --dev @nuxt/image
npm
npm install -D @nuxt/image

Add the module to buildModules in your nuxt.config:

nuxt.config.js
export default {  target: 'static',  buildModules: [    '@nuxt/image',  ]}

If you use server target (default) and are using the default provider, add @nuxt/image to modules section instead:

nuxt.config.js
export default {  modules: [    '@nuxt/image',  ]}
You can now start using <nuxt-img> and <nuxt-picture> components in your Nuxt app ✨

Configuration

Add an image section in your nuxt.config.js:

nuxt.config.js
export default {  image: {    // Options  }}

See module options for available options.

TypeScript

If you're using Typescript, add the types to your "types" array in tsconfig.json after the @nuxt/types (Nuxt 2.9.0+) or @nuxt/vue-app entry.

tsconfig.json
{  "compilerOptions": {    "types": ["@nuxt/types", "@nuxt/image"]  }}

Upgrading

Behavior and API changes might happen in 0.x releases of image module. Update with caution.

Troubleshooting

If an error occurs during installation:

  • Ensure using LTS version of NodeJS or latest update of 12.x, 14.x or 16.x (NodeJS Downloads page)
  • Try to upgrade to latest versions:
yarn
yarn upgrade @nuxt/image
npm
npm up @nuxt/image
  • Try recreating lock-file:
yarn
rm yarn.lock && yarn
npm
rm package-lock.json && npm i
  • If there is still an error related to sharp and node-gyp, it is is probably becase your OS architecture or NodeJS version is not included in pre-built binaries and needs to built from source (for example, this sometimes occurs on Apple M1). Checkout node-gyp for install requirements.
  • If none of the above worked, please open an issue and include error trace, OS, Node version and the package manager used for installing.