@uploadcare/nextjs-loader

Uploadcare custom image loader for Next.js

Usage no npm install needed!

<script type="module">
  import uploadcareNextjsLoader from 'https://cdn.skypack.dev/@uploadcare/nextjs-loader';
</script>

README

Uploadcare custom image loader for Next.js

Test Status NPM version

The package helps you use the Uploadcare's transformation and CDN services from a Next.js app smoothly and easily.

It provides the uploadcareLoader function, which you can use as a custom loader for the Next's Image component, and the UploadcareImage component with the custom loader enabled by default.

Demo

Look at the demo here.

Dependencies

The only dependency is Next.js >= 10.0.5.

Installation

yarn add @uploadcare/nextjs-loader

Configuration

Inform Next that you're going to use a custom image loader through next.config.js:

// next.config.js
module.exports = {
  images: {
    loader: "custom"
  }
}

Add your public Uploadcare key to your .env* config file. You can copy it from Dashboard -> API Keys -> Public key.

#.env
NEXT_PUBLIC_UPLOADCARE_PUBLIC_KEY="YOUR_PUBLIC_KEY"

Alternatively, in case you're using a custom proxy, set the proxy domain.

#.env
NEXT_PUBLIC_UPLOADCARE_CUSTOM_PROXY_DOMAIN="proxy.example.com"

Then set the app base url (to get relative image urls processed in Production):

#.env
NEXT_PUBLIC_UPLOADCARE_APP_BASE_URL="https://example.com/"

That's it. You may now use @uploadcare/nextjs-loader in your app (see Usage).


Below are optional parameters which you may not need:

#.env
# A comma-separated list of transformation parameters. Default: format/auto, stretch/off, progressive/yes
NEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS="format/auto, stretch/off, progressive/yes"
# Uploadcare CDN domain. Default: ucarecdn.com
NEXT_PUBLIC_UPLOADCARE_CUSTOM_CDN_DOMAIN="cdn.example.com"

Please note NEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS override corresponding default parameters and keep others in place.

Usage

Option 1. Use the UploadcareImage component and leave us the reset ;)

import UploadcareImage from '@uploadcare/nextjs-loader';

<UploadcareImage
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
  quality="80"
/>

The UploadcareImage component supports the same parameters as the Next Image component.

Option 2. Pass uploadcareLoader to the Image component:

import Image from 'next/image';
import { uploadcareLoader } from '@uploadcare/nextjs-loader';

<Image 
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
  quality="80"
  loader={uploadcareLoader}
/>

Option 3. Use the next-image-loader plugin to enable Uploadcare image loader for all images by default

In that case, you may not need the loader: "custom" setting in your next.config.js.

  1. Install next-image-loader and enable it as described in its README.

  2. Create image-loader.config.js in the project root (in the same directory as next.config.js) and add this code to it:

// image-loader.config.js
import { imageLoader } from 'next-image-loader/build/image-loader';
import { uploadcareLoader } from '@uploadcare/nextjs-loader';

imageLoader.loader = uploadcareLoader;
  1. Use Image as usual, with Uploadcare loader enabled implicitly:
import Image from 'next/image';

<Image 
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
  quality="80"
/>

Please note that you can still use any other loader for a separate image like this:

import Image from 'next/image';
import anotherLoader from '[another-loader-project-name]';

<Image 
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
  quality="80"
  loader={anotherLoader}
/>

where anotherLoader will be used instead of the Uploadcare loader for this particular image.

Links

Known Issues

Issue 1: Console warning like this:

Image with src "${src}" has a "loader" property that does not implement width. Please implement it or use the "unoptimized" property instead. Read more: https://nextjs.org/docs/messages/next-image-missing-loader-width

Next checks whether the image url which loader generates has the exact value which user passed through the width property of the Image component. And because the Uploadcare loader doesn't process SVG and GIF images, it just returns the same src value without adding any transformation parameters to it (including width). That's why Next reports the console warning.

Fix: Ignore the warning for now.