Nuxt Image

https://image.nuxt.com/get-started
Admin
Nuxt Image provides plug-and-play image optimization for Nuxt applications, enabling automatic...
Tokens:3,545
Snippets:60
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Installation

Source: https://image.nuxt.com/get-started/installation

Install the @nuxt/image dependency using your preferred package manager.

```bash
npm i @nuxt/image
```

```bash
yarn add @nuxt/image
```

```bash
pnpm add @nuxt/image
```

```bash
bun add @nuxt/image
```

--------------------------------

### Troubleshooting Installation

Source: https://image.nuxt.com/get-started/installation

Commands to upgrade the module or force a re-installation of dependencies.

```bash
npm up @nuxt/image
```

```bash
yarn upgrade @nuxt/image
```

```bash
pnpm up @nuxt/image
```

```bash
bun update @nuxt/image
```

```bash
npx nuxt upgrade --force
```

--------------------------------

### Automatic Installation

Source: https://image.nuxt.com/get-started/installation

Use the Nuxt CLI to automatically add the image module to your project.

```bash
npx nuxt module add image
```

--------------------------------

### Alias Usage Examples

Source: https://image.nuxt.com/get-started/configuration

Demonstrates the difference in component usage and generated HTML before and after applying an alias.

```html
<NuxtImg src="https://images.unsplash.com/<id>" />
```

```html
<img src="/_ipx/https://images.unsplash.com/<id>">
```

```html
<NuxtImg src="/unsplash/<id>" />
```

```html
<img src="/_ipx/unsplash/<id>">
```

--------------------------------

### Implement custom formatter in provider

Source: https://image.nuxt.com/get-started/migration

Example of using createOperationsGenerator with a custom formatter for parameter string construction.

```typescript
import { createOperationsGenerator, defineProvider } from '@nuxt/image/runtime'

const operationsGenerator = createOperationsGenerator({
  keyMap: { width: 'w', height: 'h' },
  joinWith: '&',
  formatter: (key, value) => `${key}=${encodeURIComponent(value)}`
})

export default defineProvider({
  getImage(src, { modifiers, baseURL = '/' }) {
    const operations = operationsGenerator(modifiers)
    return {
      url: `${baseURL}${src}?${operations}`
    }
  }
})
```

--------------------------------

### Update @nuxt/image dependency

Source: https://image.nuxt.com/get-started/migration

Commands to install the latest version of @nuxt/image using various package managers.

```shell
pnpm add @nuxt/image
```

```shell
yarn add @nuxt/image
```

```shell
npm install @nuxt/image
```

```shell
bun add @nuxt/image
```

```shell
deno add npm:@nuxt/image
```

--------------------------------

### Update NuxtImg sizes attribute

Source: https://image.nuxt.com/get-started/migration

Example of updating deprecated 'xs' and 'xxl' breakpoints to 'sm' and '2xl' in NuxtImg components.

```html
  <NuxtImg 
    src="/image.jpg"
-   sizes="xs:100vw sm:50vw md:400px"
+   sizes="sm:100vw md:50vw lg:400px"
  />
```

--------------------------------

### Add modifier types to custom provider

Source: https://image.nuxt.com/get-started/migration

Example of defining custom modifier types for a provider using ImageModifiers.

```typescript
import { defineProvider } from '@nuxt/image/runtime'
import type { ImageModifiers } from '@nuxt/image'

interface MyProviderModifiers extends ImageModifiers {
  watermark?: 'logo' | 'text' | 'none'
  rotate?: number
}

export default defineProvider<MyProviderModifiers>({
  getImage(src, { modifiers }) {
    // ...
    return { url }
  }
})
```

--------------------------------

### Sharp Cross-Platform Configuration

Source: https://image.nuxt.com/get-started/installation

Configure package managers to download sharp binaries for multiple target platforms to avoid runtime errors.

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

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

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

--------------------------------

### Migrate custom provider to defineProvider

Source: https://image.nuxt.com/get-started/migration

Comparison of v1 and v2 syntax for defining custom image providers.

```typescript
export const getImage = (src, { modifiers }) => {
  // ...
  return { url }
}
```

```typescript
import { defineProvider } from '@nuxt/image/runtime'

export default defineProvider({
  getImage(src, { modifiers }) {
    // ...
    return { url }
  }
})
```

--------------------------------

### Enable global $img helper

Source: https://image.nuxt.com/get-started/configuration

Set inject to true to globally initialize the $img helper throughout the application.

```typescript
export default defineNuxtConfig({
  image: {
    inject: true
  }
})
```

--------------------------------

### Configure Remote Image Domains via Environment Variable

Source: https://image.nuxt.com/get-started/providers

Set the NUXT_IMAGE_DOMAINS environment variable to allow optimization of images from external domains.

```bash
NUXT_IMAGE_DOMAINS="example.com,yourdomain.com"
```

--------------------------------

### Define and use image presets

Source: https://image.nuxt.com/get-started/configuration

Create reusable image configurations and apply them to NuxtImg components using the preset attribute.

```typescript
export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        modifiers: {
          format: 'jpg',
          width: 50,
          height: 50
        }
      }
    }
  }
})
```

```html
<template>
  <NuxtImg
    preset="avatar"
    src="/nuxt-icon.png"
  />
</template>
```

--------------------------------

### Manage Edge Channel

Source: https://image.nuxt.com/get-started/installation

Switch between stable and nightly versions of the module in package.json.

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

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

--------------------------------

### Register and use custom providers

Source: https://image.nuxt.com/get-started/configuration

Define custom image providers in the configuration and reference them in components.

```typescript
export default defineNuxtConfig({
  image: {
    providers: {
      random: {
        provider: '~/providers/random',
        options: {}
      }
    }
  }
})
```

```html
<template>
  <NuxtImg
    provider="random"
    src="main.png"
    width="300"
    height="169"
  />
</template>
```

--------------------------------

### Configure Source Directory

Source: https://image.nuxt.com/get-started/configuration

Specifies the location of source images for the ipx or ipxStatic providers.

```typescript
export default defineNuxtConfig({
  image: {
    dir: 'assets/images'
  }
})
```

--------------------------------

### Configure Image Densities

Source: https://image.nuxt.com/get-started/configuration

Sets the device pixel ratio values for which images should be adapted.

```typescript
export default defineNuxtConfig({
  image: {
    densities: [1, 2, 3]
  }
})
```

--------------------------------

### Check and upgrade Nuxt version

Source: https://image.nuxt.com/get-started/migration

Commands to verify the current Nuxt version and upgrade to the latest v3 release.

```shell
npm list nuxt
```

```shell
npx nuxt upgrade --channel v3
```

--------------------------------

### Configure default image formats

Source: https://image.nuxt.com/get-started/configuration

Specify the default image formats for NuxtPicture, ordered by browser preference.

```typescript
export default defineNuxtConfig({
  image: {
    format: ['webp']
  }
})
```

--------------------------------

### Search for deprecated screen sizes

Source: https://image.nuxt.com/get-started/migration

Grep commands to identify usage of removed 'xs' and 'xxl' breakpoints in Vue files.

```shell
grep -r "sizes.*xs:" --include="*.vue"
grep -r "sizes.*xxl:" --include="*.vue"
```

--------------------------------

### Configure allowed domains for image optimization

Source: https://image.nuxt.com/get-started/configuration

Specify external domains allowed for image optimization to prevent abuse of remote URLs.

```typescript
export default defineNuxtConfig({
  image: {
    domains: ['nuxtjs.org']
  }
})
```

--------------------------------

### Restore screen sizes in configuration

Source: https://image.nuxt.com/get-started/migration

Configuration snippet to manually re-add removed screen breakpoints in nuxt.config.ts.

```typescript
export default defineNuxtConfig({
  image: {
    screens: {
      xs: 320,
      xxl: 1536
    }
  }
})
```

--------------------------------

### Configure URL Aliases

Source: https://image.nuxt.com/get-started/configuration

Defines aliases for image source URLs to simplify usage and optimize external links.

```typescript
export default defineNuxtConfig({
  image: {
    domains: [
      'images.unsplash.com'
    ],
    alias: {
      unsplash: 'https://images.unsplash.com'
    }
  }
})
```

--------------------------------

### Define custom screen sizes

Source: https://image.nuxt.com/get-started/configuration

Set predefined screen sizes used for generating optimized image versions via the sizes modifier.

```typescript
export default defineNuxtConfig({
  image: {
    // The screen sizes predefined by `@nuxt/image`:
    screens: {
      'sm': 640,
      'md': 768,
      'lg': 1024,
      'xl': 1280,
      '2xl': 1536
    }
  }
})
```

--------------------------------

### Configure Image Module

Source: https://image.nuxt.com/get-started/installation

Add the image section to your nuxt.config to customize module options.

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

--------------------------------

### Set default provider

Source: https://image.nuxt.com/get-started/configuration

Configure the default image provider to be used globally when not specified in components.

```typescript
export default defineNuxtConfig({
  image: {
    provider: 'twicpics',
    twicpics: {
      baseURL: 'https://nuxt-demo.twic.pics'
    }
  }
})
```

--------------------------------

### Set default image quality

Source: https://image.nuxt.com/get-started/configuration

Define the default quality for generated images, which can be overridden at the component level.

```typescript
export default defineNuxtConfig({
  image: {
    quality: 80
  }
})
```

--------------------------------

### Register Module in nuxt.config

Source: https://image.nuxt.com/get-started/installation

Add the module to the modules array in your nuxt.config file.

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

--------------------------------

### Configure default provider modifiers

Source: https://image.nuxt.com/get-started/configuration

Set default image modifiers for a specific provider to apply consistent transformations.

```typescript
export default defineNuxtConfig({
  image: {
    provider: 'cloudinary',
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/<company>/image/fetch',
      modifiers: {
        effect: 'sharpen:100',
        quality: 'auto:best'
      }
    }
  }
})
```
Tokens:
Raw