Get Started

Installation

Using image module in your Nuxt project is only one command away.
You are reading the v1 documentation compatible with Nuxt 3.
Checkout v0.image.nuxtjs.org for Nuxt 2 compatible version. (Announcement).

Automatic Installation

To get started, add @nuxt/image to your project:

npx nuxt module add image

Manual Installation

Add @nuxt/image dependency to your project:

npm i @nuxt/image

Then, add it to the modules in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/image'
  ]
})

Configuration

Add an image section in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    // Options
  }
})
Checkout the image configuration for all available options and features to customize.

Edge Channel

After each commit is merged into the main branch of @nuxt/image and passing all tests, we trigger an automated npm release using GitHub Actions publishing a @nuxt/image-nightly package.

You can opt in to use this release channel and avoid waiting for the next release and helping the module by beta testing changes.

The build and publishing method and quality of edge releases are the same as stable ones. The only difference is that you should often check the GitHub repository for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release.

Opting into the edge channel

Update @nuxt/image dependency inside package.json:

package.json
{
  "devDependencies": {
-   "@nuxt/image": "^1.0.0"
+   "@nuxt/image": "npm:@nuxt/image-nightly@latest"
  }
}

Remove lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) and reinstall dependencies.

Opting out from the edge channel

Update @nuxt/image dependency inside package.json:

package.json
{
  "devDependencies": {
-   "@nuxt/image": "npm:@nuxt/image-nightly@latest"
+   "@nuxt/image": "^1.0.0"
  }
}

Remove lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) and reinstall dependencies.

Troubleshooting

If an error occurs during installation:

npm up @nuxt/image
  • Try recreating lockfile:
npx nuxt upgrade --force
  • If there is still an error related to sharp and node-gyp, it is probably because your OS architecture or NodeJS version is not included in pre-built binaries and needs to be 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.

Configuration

Nuxt Image is configured with sensible defaults.