DOCSEARCHbyAlgolia
Submit Docs

plaiceholder

repository·main·Indexed 25 days ago

https://github.com/joe-bell/plaiceholder

A server-side library for generating lightweight Low Quality Image Placeholders (LQIP) in formats including CSS, SVG, Base64, and solid colors to improve perceived loading performance. Distributed as ESM only and utilizing sharp for image transformations, it includes specialized plugins for Next.js (@plaiceholder/next) and Tailwind CSS (@plaiceholder/tailwindcss). Version 3.0.0 is the feature-complete release and is currently in maintenance mode.

Tokens
5.7K
Snippets
19
Records
36
Agent score
73%

What's inside plaiceholder

  1. Overview of Plaiceholder LQIP strategies

    main

    Plaiceholder is a suite of server-side functions designed to create Low Quality Image Placeholders (LQIP). It provides multiple strategies so you can choose the one that best fits your performance and aesthetic requirements:

    • Color: A simple solid color placeholder.
    • CSS: Generates a CSS-based placeholder (~600B when rendered).
    • SVG: Generates an SVG placeholder (~1.2kB when rendered in HTML).
    • Base64: Generates a Base64 encoded image placeholder (~300B asset size).

    Strategy Tradeoffs

    StrategyProsCons
    ColorExtremely lightweightPlain; not visually engaging
    CSSLightweightWon't maintain aspect ratio for images using object-fit
    SVGVisually smoothDoes not currently leverage SVG filter primitives (like feGaussianBlur)
    Base64Small asset sizeCan appear drab; even with Plaiceholder's internal saturation boost, colors may not look ideal

  2. Overview of plaiceholder

    main
    plaiceholder is a tool for generating beautiful image placeholders. It supports various output formats, ranging from pure CSS to SVG, to provide a seamless loading experience for images without the hassle of manual placeholder creation.

  3. Understand plaiceholder runtime requirements

    main

    Before using Plaiceholder, be aware of the following runtime constraints:

    • Server-side only: Plaiceholder is a server-side library and will not work in the browser.
    • ESM only: All plaiceholder packages are ESM-only.
    • Runtime support: It works on all runtimes supported by sharp. Currently, sharp is primarily limited to Node.js.

  6. Run the Plaiceholder × Astro example project

    main

    To run this example project locally, follow these steps from the project root:

    1. Install dependencies: Run npm install to set up the environment.
    2. Start development server: Run npm run dev to start the local development server at http://localhost:3000.
    3. Build for production: Run npm run build to generate the production site in the ./dist/ directory.
    4. Preview build: Run npm run preview to preview your production build locally before deploying.
    npm install
npm run dev

  7. Use a Buffer with getPlaiceholder in v3.0

    main

    In plaiceholder v3.0, automatic image resolution (passing a string path or URL to getPlaiceholder) has been removed to support non-Node.js runtimes. You must now manually resolve your image into a Buffer and pass that Buffer to getPlaiceholder().

    Node.js: 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");

    Node.js: 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"
);
    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");

  9. Configure Next.js with withPlaiceholder

    main

    Wrap your Next.js configuration object with the withPlaiceholder function.

    Important Requirements:

    • Your Next.js config file must use the .mjs extension (or .ts if supported by your environment).
    • This plugin is essential for ensuring Plaiceholder functions execute correctly within the Next.js lifecycle.
    // @ts-check
import withPlaiceholder from "@plaiceholder/next";

/**
 * @type {import('next').NextConfig}
 */
const config = {
 // your Next.js config
};

export default withPlaiceholder(config);

  12. Upgrade @plaiceholder/next and @plaiceholder/tailwindcss to v3.0

    main

    @plaiceholder/next

    1. Migrate your next.config.js to next.config.mjs (or .ts if supported).
    2. Ensure your configuration matches the plugin's 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.