Installation

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

yarn add @nuxt/image

pnpm add @nuxt/image

bun add @nuxt/image

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

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

Sharp Cross-Platform Installation

The default IPX provider uses sharp for image processing. At install time, your package manager downloads prebuilt sharp binaries only for your current OS and CPU architecture. This means if you build on macOS or Windows and deploy to a Linux server (or build on x64 and deploy to ARM64), the required sharp binaries might be missing, resulting in errors like:

[500] [IPX_ERROR] Could not load the "sharp" module using the linux-x64 runtime

To fix this, configure your package manager to install sharp binaries for all target platforms, e.g.:

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["current", "linux"],
      "cpu": ["current", "x64", "arm64"]
    }
  }
}

supportedArchitectures:
  os:
    - current
    - linux
  cpu:
    - current
    - x64
    - arm64

npm install --cpu=x64 --os=linux sharp
npm install --cpu=arm64 --os=linux sharp

After updating the configuration, reinstall dependencies to download the additional platform binaries.

For more details, see the sharp cross-platform documentation.

Configuration

Add an image section in your nuxt.config:

export default defineNuxtConfig({
  image: {
    // Options
  }
})

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:

{
  "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:

{
  "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:

• Ensure using LTS version of NodeJS (NodeJS Download page)
• Try to upgrade to latest versions:

npm up @nuxt/image

yarn upgrade @nuxt/image

pnpm up @nuxt/image

bun update @nuxt/image

• Try recreating lockfile:

npx nuxt upgrade --force

• If none of the above worked, please open an issue and include error trace, OS, Node version and the package manager used for installing.