feat!: add a getBlurDataURL server-side helper to generate base64 blurred placeholder

BREAKING CHANGE: previously implemented `blurDataURL` auto-generation won't work in Next.js v13. It was a bad way because the blurry image was requested from the server in runtime. A New way is to generate a blurry image base64 string at build time.

Author: nd0ut

README.md

@@ -56,7 +56,7 @@ Add your public Uploadcare key to your `.env*` config file. You can copy it from
 NEXT_PUBLIC_UPLOADCARE_PUBLIC_KEY="YOUR_PUBLIC_KEY"
 ```
 
-Alternatively, in case you're using a custom proxy, set the proxy domain.
+Alternatively, in case you're using a [custom proxy endpoint][docs-custom-proxy-endpoint], set the proxy domain.
 
 ```ini
 #.env
@@ -118,7 +118,34 @@ import { uploadcareLoader } from '@uploadcare/nextjs-loader';
 />
 ```
 
-**Option 3**. Use the [next-image-loader](https://www.npmjs.com/package/next-image-loader) plugin to enable Uploadcare image loader for all images by default
+**Option 3 (Next.js v13+ only)**. Use the [`loaderFile` setting][loader-file] to enable Uploadcare image loader for all images by default.
+
+1. Configure the `loaderFile` in your `next.config.js` like the following:
+
+```js
+module.exports = {
+  images: {
+    loader: 'custom',
+    loaderFile: './node_modules/@uploadcare/nextjs-loader/build/loader.js',
+  },
+}
+```
+
+2. Use `Image` as usual, with Uploadcare loader enabled implicitly:
+
+```tsx
+import Image from 'next/image';
+
+<Image
+  alt="A test image"
+  src="https://your-domain/image.jpg"
+  width="400"
+  height="300"
+  quality="80"
+/>
+```
+
+**Option 4**. Use the [next-image-loader](https://www.npmjs.com/package/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`.
 
@@ -180,19 +207,45 @@ There are two possible use cases:
 
 #### When `src` is a string
 
-This options is available for the `UploadcareImage` component only. It won't work when you're using custom loader directly.
+If you pass `placeholder="blur"` to the `UploadcareImage` component, the `blurDataURL` property will be used as the placeholder. In this case you must provide the `blurDataURL` property using our `getBlurDataURL` server-side helper.
 
-If you pass `placeholder="blur"` to the `UploadcareImage` component, it will generate `blurDataURL` with the URL of the placeholder image (not base64) and use it as a placeholder. You can override `blurDataURL`.
+Here is the ``getBlurDataURL` interface:
+
+```ts
+function getBlurDataURL(
+  src: string,
+  width = 10,
+  quality = 1
+): Promise<string>
+```
+
+Usage example:
 
 ```tsx
-<UploadcareImage
-  alt="A test image"
-  src="https://your-domain/image.jpg"
-  width="400"
-  height="300"
-  quality="80"
-  placeholder="blur"
-/>
+import UploadcareImage, { getBlurDataURL } from '@uploadcare/nextjs-loader';
+
+const BLUR_IMAGE_URL = "https://your-domain/image.jpg"
+
+export const getStaticProps = async () => {
+  const blurDataURL = await getBlurDataURL(BLUR_IMAGE_URL);
+
+  return {
+    props: { blurDataURL }
+  };
+};
+
+export default ({ blurDataURL }) => {
+  return (
+    <UploadcareImage
+      alt="Blurred image"
+      src={BLUR_IMAGE_URL}
+      width="400"
+      height="300"
+      placeholder="blur"
+      blurDataURL={blurDataURL}
+    />
+  )
+}
 ```
 
 #### When `src` is a static import
@@ -246,3 +299,6 @@ Next checks whether the image url which loader generates has the exact value whi
 [npm-link]: https://www.npmjs.com/package/@uploadcare/nextjs-loader
 [demo-link]: https://uploadcare-nextjs-loader.netlify.app/
 [uploadcare-transformation-image-compression-docs]: https://uploadcare.com/docs/transformations/image/compression/?utm_source=github&utm_campaign=nextjs-loader
+[docs-custom-proxy-endpoint]: https://uploadcare.com/docs/delivery/proxy/#usage-endpoint
+[last-next-12-release]: https://github.com/uploadcare/nextjs-loader/tree/v0.4.0
+[loader-file]: https://nextjs.org/docs/api-reference/next/image#loader-configuration

jest-setup.js

@@ -1 +1,2 @@
 import '@testing-library/jest-dom'
+import 'whatwg-fetch';

package.json

@@ -62,7 +62,8 @@
     "shipjs": "0.24.0",
     "ts-add-module-exports": "^1.0.0",
     "ts-node": "^10.2.1",
-    "typescript": "^4.4.3"
+    "typescript": "^4.4.3",
+    "whatwg-fetch": "^3.6.2"
   },
   "peerDependencies": {
     "next": ">=10.0.5",

src/__tests__/get-blur-data-url.spec.ts

@@ -0,0 +1,16 @@
+/**
+ * @jest-environment jsdom
+ */
+import { getBlurDataURL } from '../utils/getBlurDataURL';
+
+describe('getBlurDataURL', () => {
+  it('should return low quality image with the specified width', async () => {
+    const dataURL = await getBlurDataURL(
+      'https://ucarecdn.com/c768f1c2-891a-4f54-8e1e-7242df218b51/pinewatt2Hzmz15wGikunsplash.jpg',
+      10
+    );
+    expect(dataURL).toBe(
+      'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIcSUNDX1BST0ZJTEUAAQEAAAIMbGNtcwIQAABtbnRyUkdCIFhZWiAH3AABABkAAwApADlhY3NwQVBQTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLWxjbXMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAApkZXNjAAAA/AAAAF5jcHJ0AAABXAAAAAt3dHB0AAABaAAAABRia3B0AAABfAAAABRyWFlaAAABkAAAABRnWFlaAAABpAAAABRiWFlaAAABuAAAABRyVFJDAAABzAAAAEBnVFJDAAABzAAAAEBiVFJDAAABzAAAAEBkZXNjAAAAAAAAAANjMgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0ZXh0AAAAAElYAABYWVogAAAAAAAA9tYAAQAAAADTLVhZWiAAAAAAAAADFgAAAzMAAAKkWFlaIAAAAAAAAG+iAAA49QAAA5BYWVogAAAAAAAAYpkAALeFAAAY2lhZWiAAAAAAAAAkoAAAD4QAALbPY3VydgAAAAAAAAAaAAAAywHJA2MFkghrC/YQPxVRGzQh8SmQMhg7kkYFUXdd7WtwegWJsZp8rGm/fdPD6TD////bAEMAChQVGRUSHBkXGSAeHCIrRy4rJycrVz5CNEdnW21rZVtkYnKApItyeZt7YmSOwpCbqa63ubduicnXx7LWpLS3sP/bAEMBEBQVGRUSHBkXGSAeHCIrRy4rJycrVz5CNEdnW21rZVtkYnKApItyeZt7YmSOwpCbqa63ubduicnXx7LWpLS3sP/CABEIAAcACgMBIgACEQEDEQH/xAAWAAEBAQAAAAAAAAAAAAAAAAAABAX/xAAVAQEBAAAAAAAAAAAAAAAAAAAAAf/aAAwDAQACEAMQAAABixyP/8QAFxAAAwEAAAAAAAAAAAAAAAAAAAISE//aAAgBAQABBQLZoP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQMBAT8Bf//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQIBAT8Bf//EABQQAQAAAAAAAAAAAAAAAAAAABD/2gAIAQEABj8CP//EABkQAAIDAQAAAAAAAAAAAAAAAAABEUFRYf/aAAgBAQABPyFWOEvT/9oADAMBAAIAAwAAABCD/8QAFREBAQAAAAAAAAAAAAAAAAAAAQD/2gAIAQMBAT8QC//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQIBAT8Qf//EABgQAAMBAQAAAAAAAAAAAAAAAAABIREx/9oACAEBAAE/EFYvafRteuz/2Q=='
+    );
+  });
+});

src/__tests__/uploadcare-image.spec.tsx

@@ -43,6 +43,7 @@ describe('UploadcareImage', () => {
 
     render(
       <UploadcareImage
+        alt="Test image"
         src={src}
         width={500}
         height={500}
@@ -56,36 +57,4 @@ describe('UploadcareImage', () => {
       'https://ucarecdn.com/a6f8abc8-f92e-460a-b7a1-c5cd70a18cdb/-/format/auto/-/stretch/off/-/progressive/yes/-/resize/1080x/-/quality/normal/'
     );
   });
-
-  it('should generate blurDataURL when placeholder=blur passed', () => {
-    const src =
-      'https://ucarecdn.com/a6f8abc8-f92e-460a-b7a1-c5cd70a18cdb/image.png';
-
-    render(
-      <UploadcareImage src={src} width={500} height={500} placeholder="blur" />
-    );
-
-    expect(screen.getByRole('img')).toHaveStyle(
-      'background-image: url(https://ucarecdn.com/a6f8abc8-f92e-460a-b7a1-c5cd70a18cdb/-/format/auto/-/stretch/off/-/progressive/yes/-/resize/5x/-/quality/lightest/image.png)'
-    );
-  });
-
-  it('should not override passed blurDataURL', () => {
-    const src =
-      'https://ucarecdn.com/a6f8abc8-f92e-460a-b7a1-c5cd70a18cdb/image.png';
-
-    render(
-      <UploadcareImage
-        src={src}
-        width={500}
-        height={500}
-        placeholder="blur"
-        blurDataURL={src}
-      />
-    );
-
-    expect(screen.getByRole('img')).toHaveStyle(
-      `background-image: url(${src})`
-    );
-  });
 });

src/components/UploadcareImage.tsx

@@ -1,41 +1,7 @@
 import Image, { ImageProps } from 'next/image';
 import React from 'react';
-import {
-  PLACEHOLDER_SIZE_FALLBACK,
-  PLACEHOLDER_SIZE_MULTIPLIER
-} from '../utils/constants';
-import { getInt } from '../utils/helpers';
 import { uploadcareLoader } from '../utils/loader';
 
-const shouldOverrideBlurDataUrl = (props: ImageProps): boolean => {
-  return (
-    typeof props.src === 'string' &&
-    props.placeholder === 'blur' &&
-    !props.blurDataURL
-  );
-};
-
-const generateBlurDataUrl = (
-  src: string,
-  width: ImageProps['width']
-): string => {
-  const imageWidth = getInt(width);
-  const blurImageWidth = imageWidth
-    ? Math.ceil(imageWidth * PLACEHOLDER_SIZE_MULTIPLIER)
-    : PLACEHOLDER_SIZE_FALLBACK;
-  return uploadcareLoader({
-    src: src,
-    width: blurImageWidth,
-    quality: 1
-  });
-};
-
 export function UploadcareImage(props: ImageProps): JSX.Element {
-  let blurDataURL = props.blurDataURL;
-  if (shouldOverrideBlurDataUrl(props)) {
-    blurDataURL = generateBlurDataUrl(props.src as string, props.width);
-  }
-  return (
-    <Image loader={uploadcareLoader} blurDataURL={blurDataURL} {...props} />
-  );
+  return <Image loader={uploadcareLoader} {...props} />;
 }

src/index.ts

@@ -1,5 +1,6 @@
 import { UploadcareImage } from './components/UploadcareImage';
 import { uploadcareLoader } from './utils/loader';
+import { getBlurDataURL } from './utils/getBlurDataURL';
 
 export default UploadcareImage;
-export { uploadcareLoader };
+export { uploadcareLoader, getBlurDataURL };

src/utils/constants.ts

@@ -3,5 +3,3 @@ export const MAX_OUTPUT_JPEG_IMAGE_DIMENSION = 5000;
 export const NOT_PROCESSED_EXTENSIONS = ['svg', 'gif'];
 export const DEFAULT_PARAMS = ['format/auto', 'stretch/off', 'progressive/yes'];
 export const DEFAULT_CDN_DOMAIN = 'ucarecdn.com';
-export const PLACEHOLDER_SIZE_MULTIPLIER = 0.01;
-export const PLACEHOLDER_SIZE_FALLBACK = 10;

src/utils/getBlurDataURL.ts

@@ -0,0 +1,21 @@
+import { uploadcareLoader } from './loader';
+
+export async function getBlurDataURL(
+  src: string,
+  width = 10,
+  quality = 1
+): Promise<string> {
+  const cdnUrl = uploadcareLoader({
+    src: src,
+    width,
+    quality
+  });
+
+  const response = await fetch(cdnUrl);
+  const contentType = response.headers.get('content-type');
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  const base64 = buffer.toString('base64');
+  const dataURL = `data:${contentType};base64,${base64}`;
+  return dataURL;
+}

src/utils/helpers.ts

@@ -145,16 +145,6 @@ export function isJpegExtension(extension: string): boolean {
   return ['jpg', 'jpeg'].includes(extension.toLowerCase());
 }
 
-export function getInt(x: unknown): number | undefined {
-  if (typeof x === 'number') {
-    return x;
-  }
-  if (typeof x === 'string') {
-    return parseInt(x, 10);
-  }
-  return undefined;
-}
-
 function _parseUploadcareTransformationParam(param: string): string[] {
   return param.split('/');
 }