Custom Provider

If a CDN provider is not supported, you can define it yourself.

Provider Entry

The runtime will receive a source, image modifiers and its provider options. It is responsible for generating a url for optimized images, and needs to be isomorphic because it may be called on either server or client.

import { joinURL } from 'ufo'
import type { ProviderGetImage } from '@nuxt/image'
import { createOperationsGenerator } from '#image'

const operationsGenerator = createOperationsGenerator()

export const getImage: ProviderGetImage = (
  { modifiers = {}, baseURL } = {}
) => {

  if (!baseURL) {
    // also support runtime config 
    baseURL = useRuntimeConfig().public.siteUrl

  const operations = operationsGenerator(modifiers)

  return {
    url: joinURL(baseURL, src + (operations ? '?' + operations : '')),


  • src: Source path of the image.
  • modifiers: List of image modifiers that are defined in the image component or as a preset.
  • ctx: (ImageCTX) Image module runtime context
    • options: (CreateImageOptions) Image module global runtime options
    • $img: The $img helper

Note: Values in ctx might change. Use it with caution.


  • url: Absolute or relative url of optimized image.

Use your provider

Register provider

After you create your own provider, you should register it in the nuxt.config. In order to do that create a property inside image.provider.

export default defineNuxtConfig({
  // ...
  image: {
    providers: {
      myProvider: {
        name: 'myProvider', // optional value to overrider provider name
        provider: '~/providers/my-provider.ts', // Path to custom provider
        options: {
          // ... provider options
          baseURL: ""

There are plenty of useful utilities that can be used to write providers by importing from #image. See src/runtime/providers for more info.


Set attribute provider as your custom provider name.

<NuxtImg provider="myProvider" src="/image.png" >
<!-- <img src="" /> -->