nuxt-image-skilld

name	nuxt-image-skilld
description	ALWAYS use when writing code importing "@nuxt/image". Consult for debugging, best practices, or modifying @nuxt/image, nuxt/image, nuxt image, image.
metadata	{"version":"2.0.0","generated_by":"Google · Gemini 2.5 Flash","generated_at":"2026-05-29T00:00:00.000Z"}

nuxt/image @nuxt/image@2.0.0

Tags: rc: 1.0.0-rc.3, alpha: 2.0.0-alpha.1, latest: 2.0.0

References: package.json • README • Docs • Issues • Discussions • Releases

Search

Use skilld search "query" -p @nuxt/image instead of grepping .skilld/ directories. Run skilld search --guide -p @nuxt/image for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: Provider API — All providers now require defineProvider wrapper for type-safe configuration source

• BREAKING: layer0 and edgio providers — These deprecated providers have been removed source

• BREAKING: URL formatters — Custom providers using joinWith must now use formatter function with createOperationsGenerator source

• BREAKING: Screen sizes — Default screen sizes now match Tailwind CSS; xs (320px) and xxl (2560px) have been removed source

• BREAKING: Removed utilities — Several unused runtime utilities have been removed; check direct imports source

• NEW: defineProvider — Use defineProvider for type-safe image provider configuration source

• NEW: Typed composables — $img helper and useImage() composable now have full type inference source

• NEW: Server-side utilities — Image helpers can now be used directly in Nitro server endpoints source

• NEW: <NuxtImg> template refs — Exposes underlying <img> element via useTemplateRef() source

• NEW: Typed slots — <NuxtImg> and <NuxtPicture> now have properly typed default slots source

• NEW: Shopify provider — Added new image provider for Shopify stores source

• NEW: GitHub provider — Added new image provider for GitHub avatars and user content source

• NEW: Custom image directories in layers — Support for organizing images in modular projects source

• NEW: IPX v3 — Upgraded to IPX v3 for better performance and sharp binary handling source

Also changed: ipx: Pass all options changed in v1.0.0 source · ipx migrate to v2 in v1.0.0-rc.3 source · sizes default changed to responsive-first in v1.0.0-rc.2 source

Best Practices

• Avoid new Netlify Large Media configuration for nuxt/image as it is deprecated; existing configurations will continue to work but new setups are not recommended. source

• Prefer explicitly providing the url property for the Cloudimage provider over using a token when needing a custom CDN hostname or to bypass dynamic URL building. source

• Whitelist external hostnames in your Nuxt configuration when using external URLs with Vercel or AWS Amplify providers to ensure images outside the public/ directory can be optimized and to prevent abuse. source

• Utilize Imgix's auto parameter to automatically apply the best image format and compression, enhancing performance and optimizing image delivery. source

• Avoid explicitly setting the quality attribute when using the ImageEngine provider; ImageEngine automatically adapts image quality based on the visitor's device, browser, and network conditions for optimal delivery. source

• To completely disable ImageEngine optimizations for a specific image, use :modifiers="{ passThrough: 'true' }" instead of manually setting format and quality to ensure the unaltered image is served. source

• Employ Gumlet's format=auto parameter to enable automatic format selection and compression, which helps deliver optimized images tailored to user devices. source

• Always register custom image providers within the nuxt.config under image.provider after their creation to ensure they are properly integrated into the Nuxt Image module. source

• Store static images intended for use with the default provider in the public/ directory of your project, and reference them using an absolute path in the src attribute. source

• Provide the alt attribute for all <NuxtImg> and <NuxtPicture> components; the text should describe the image content or its link destination for accessibility. source

• Leverage the custom prop on <NuxtImg> when implementing custom functionalities, such as placeholders, as it disables default rendering and allows full control over image display. source

• Configure image.domains to whitelist external hostnames if you intend to optimize images from external websites; this security measure prevents potential abuse of external URLs. source

• Utilize the nonce prop on NuxtImg to enhance Content Security Policy (CSP) without resorting to the less secure unsafe-inline directive. source

• For Nuxt 3, ensure that /nuxt-icon.png is placed inside the public/ directory to make the <NuxtImg src="/nuxt-icon.png" /> example work correctly with the default provider. source