Installation - Nuxt Image

You are reading the v1 documentation compatible with Nuxt 3.
Checkout v0.image.nuxtjs.org for Nuxt 2 compatible version. (Announcement).

Add @nuxt/image dependency to your project:

pnpm add @nuxt/image

Add it to modules in your nuxt.config:

nuxt.config.ts

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

You can now start using <NuxtImg> and <NuxtPicture> components in your application ✨

Configuration

Add an image section in your nuxt.config:

nuxt.config.ts

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-edge 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-edge@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-edge@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:

Ensure using LTS version of NodeJS (NodeJS Download page)
Try to upgrade to latest versions:
```
pnpm up @nuxt/image
```
Try recreating lock-file:
```
npx nuxt@latest upgrade --force
```
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.

Configuration

Nuxt Image is configured with sensible defaults.