Upgrading to 3.0

3.0 marks the end of the plaiceholder project, with this major release focussing on making the project feature complete and as future-proof as possible.

plaiceholder continues to work on all runtimes supported by sharp (opens in a new tab).
sharp (opens in a new tab) is currently limited to Node.js, but there is a pull request (opens in a new tab) to expand support.

Preparing for wider support meant dropping some of the "magic" features that plaiceholder previously offered. There is no obligation to upgrade to 3.0 if you would prefer to keep using the previous API!

If this project has been useful to you, please consider sponsoring my work (opens in a new tab).

Migrate to ESM

If you're using any of the plaiceholder packages in a CommonJS project, you'll need to migrate to ESM before continuing.

Update Your Dependencies

Ensure all plaiceholder and @plaiceholder/* packages are set to at least 3.0.0.

Update Your Code

plaiceholder

1. Implement your own image resolver

   Previously, plaiceholder would automatically resolve your image based on a specified file path or URL, e.g. getPlaiceholder('./path-to-image').

   To enable future adoption within other non-Node.js runtimes, this feature has been removed.

   Instead, you will need to pass a Buffer to getPlaiceholder(), based on your own use-case.

   In the case of Node.js, for local images in /public:

   import path from "node:path";
   import fs from "node:fs/promises";
    
   const getImage = async (src: string) => {
     const buffer = await fs.readFile(path.join("./public", src));
    
     const {
       metadata: { height, width },
       ...plaiceholder
     } = await getPlaiceholder(buffer, { size: 10 });
    
     return {
       ...plaiceholder,
       img: { src, height, width },
     };
   };
    
   // Usage
   const { base64, img } = await getImage("/assets/image/example.jpg");

   In the case of Node.js, for remote images:

   const getImage = async (src: string) => {
     const buffer = await fetch(src).then(async (res) =>
       Buffer.from(await res.arrayBuffer())
     );
    
     const {
       metadata: { height, width },
       ...plaiceholder
     } = await getPlaiceholder(buffer, { size: 10 });
    
     return {
       ...plaiceholder,
       img: { src, height, width },
     };
   };
    
   // Usage
   const { base64, img } = await getImage(
     "https://images.unsplash.com/photo-1621961458348-f013d219b50c?auto=format&fit=crop&w=2850&q=80"
   );

2. blurhash is no longer returned

   Switch any blurhash consumers to an alternative LQIP strategy, or use the blurhash package directly.

3. img → metadata

   Update any img consumers to make use of the new metadata object.

   Instead, use metadata to create your own <img /> attributes.

   Note: img.type has moved to metadata.format.

4. No longer removeAlpha by default

   To preserve previous behaviour, you can specify removeAlpha: true within getPlaiceholder()'s options.

5. Update Your Types

   • TGetPlaiceholderSrc → GetPlaiceholderSrc
   • IGetPlaiceholderOptions → GetPlaiceholderOptions
   • IGetPlaiceholderReturn → GetPlaiceholderReturn
   • IGetPlaiceholder → typeof getPlaiceholder

@plaiceholder/next

1. Migrate your next.config.js to next.config.mjs
   (or .ts when supported)
2. Ensure your config matches the configuration steps.

@plaiceholder/tailwindcss

1. Migrate your tailwind.config.js to tailwind.config.mjs or tailwind.config.ts
2. Follow the configuration steps to add a resolver.