Installation

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.
Edit this page on GitHub Updated at Fri, Sep 10, 2021