Netlify Developers

Compose Conference 2024 is coming!  Submit a talk

Avoiding lock-in for your image pipeline with Nuxt Image and Netlify Image CDN

by Phil Hawksworth

Resizing and optimizing image assets in our web projects has become both an important part of the efforts to safeguard performance, and also a common developer experience or code efficiency wrinkle. Many frameworks seek to streamline this for users and developers alike, and often leverage image services such as Netlify Image CDN, Cloudinary, or Imgix. Nuxt Image does this in a way that does not lock you in to any one provider, and is incredibly simple to set up with Netlify.


Here, we’ll look at the steps to adding Nuxt Image to a Nuxt project, and see how it is automatically powered by Netlify Image CDN when deployed to Netlify. We’ll also see how this can be used and tested in a local development context.


To code along as we go, you’ll need:

JFDI (just deploy it)

If you’d prefer to just clone and deploy an example to explore, click the button below and you’ll very quickly have an example Nuxt site using Netlify Image to power Nuxt Image deployed and ready to tinker with.

Deploy to Netlify

Adding Nuxt Image to a Nuxt project

Nuxt Image is a module dedicated to providing image asset optimization, resizing, and associated markup generation for your Nuxt sites. If you have a project already, you can add it that, or if you’d prefer a totally clean start, use the Nuxt CLI (nuxi) to quickly create a new starter Nuxt project to experiment with.

Terminal window
npx nuxi@latest init my-app

Add the Nuxt Image module as a dependency to your project

The Nuxt CLI can help us with this too, which for convenience, we can use via npx like this:

Terminal window
npx nuxi@latest module add image

Tell your Nuxt project that you’re using the module

Adding the module to your Nuxt configuration file, nuxt.config.js, will make <NuxtImg> and <NuxtPicture> components available to use in your application.

export default defineNuxtConfig({
modules: ["@nuxt/image"],

Add an image to your application using <NuxtImg>

Nuxt Image and Netlify Image CDN can serve images assets which are part of the site repo or sourced from an external resource. To start, let’s add a local image and display it in a page template.

Various attributes and modifiers can be set and passed along to the underlying image service provider.

<NuxtImg src="owl.jpg" height="400" width="600" fit="cover" />

Testing Nuxt Image in your local environment

During development, you’ll want to get a realistic picture (Yes, I saw this pun coming, and did nothing to avoid it. You’re welcome) of how everything is working using the underlying image provider, in our case Netlify Image CDN. Luckily, we can gain access to this by simply running our local build with Netlify Dev.

Netlify Dev is bundled into Netlify CLI and will detect your local site characteristics and run your build for you when you run the command netlify dev in your project directory (or ntl dev if you want to save a few keystrokes)

By running your project with netlify dev you’ll gain local access to a number of the facilities of the Netlify platform such as redirects, serverless and edge functions, blob storage, and Image CDN (which is what we care about here)

More specific local dev command control

If for some reason your project is not correctly detected and run by netlify dev, or if you have some exotic local dev commands that you run, you can configure this with a netlify.toml file.

Explicitly specifying Netlify Image CDN as a provider

Although Netlify will default to using Netlify CDN automatically, you can explicitly specify this by adding an image object to your nuxt.config.ts file and declaring your provider.

export default defineNuxtConfig({
modules: ["@nuxt/image"],
image: {
provider: "netlify",

Allowing external image sources

To use images from external sources in Nuxt Image, with the same optimizations, CDN caching, and manipulation as with your local images, you need to declare the allowed domains by adding a domains array to your nuxt.config.ts file.

export default defineNuxtConfig({
modules: ["@nuxt/image"],
image: {
provider: "netlify",
domains: [""],

Ummm… that’s it

The tl;dr could perhaps have been:

  • Add the dependency
  • Add it to the config
  • Use the component
  • Ship it

Thanks to the thoughtful abstractions provided by Nuxt Image, this is all you need to do to use <NuxtImg> with Netlify powering the image optimizations and manipulations. You might have noticed that we’ve not even added any mention of Netlify Image CDN to the codebase at this stage.

Nuxt Image will automatically detect when it’s being deployed to Netlify and use Netlify Image under the hood.

The power of primitives

One of the principles we value at Netlify is providing developers and framework authors access to powerful primitives to power their applications (or the frameworks that power the applications of others).

Nuxt Image makes use of one such primitive perfectly here, offering convenience to Nuxt users without the need to learn about the underlying primitives (although you could use the Image CDN directly if you wished, or if your site didn’t justify the use of a framework).

More information