website·Indexed 33 days ago
https://plaiceholder.co/docsDocumentation for Plaiceholder, including getting started guides, usage parameters, and plugins for Next.js and Tailwind. Version 3.0 is the final release and is ESM only.
sharp library, which is currently limited primarily to Node.js.sharp library to transform images. While some frameworks include sharp by default, you may need to install it manually before installing the main package.npm install sharp
npm install plaiceholder@plaiceholder/tailwindcss package is ESM only and requires a Node.js environment. To use it, install the package and add it to your Tailwind configuration. Note that your Tailwind config file must use the .mjs or .ts extension.npm install @plaiceholder/tailwindcss// tailwind.config.mjs
// @ts-check
import plaiceholder from "@plaiceholder/tailwindcss";
/** @type {import('tailwindcss').Config} */
export default {
content: [],
theme: {
extend: {},
},
variants: {},
plugins: [plaiceholder()],
};Upgrading to plaiceholder 3.0 requires several breaking changes to ensure future-proofing and wider runtime support. Key requirements include:
plaiceholder packages are now ESM only. CommonJS projects must migrate to ESM.plaiceholder and @plaiceholder/* packages are updated to at least version 3.0.0.sharp (currently limited to Node.js).plaiceholder plugin requires a resolver function to determine how to convert an image path (provided in the Tailwind class square brackets) into a Buffer. This is configured within the plugin options in your Tailwind config.// tailwind.config.mjs
// @ts-check
import fs from "node:fs";
import path from "node:path";
import plaiceholder from "@plaiceholder/tailwindcss";
/** @type {import('tailwindcss').Config} */
export default {
content: [],
theme: {
extend: {},
},
variants: {},
plugins: [
plaiceholder({
resolver: (src) =>
fs.readFileSync(path.join("./public", `${src}.jpg`)),
}),
],
};plaiceholder packages are ESM (ECMAScript Module) only. They cannot be used in CommonJS environments without a build step or specific compatibility layers.@plaiceholder/next plugin is required for Next.js projects to ensure that all Plaiceholder functions start in the main thread. Note that plaiceholder packages are ESM only. To set up the plugin, install the package and wrap your Next.js configuration with withPlaiceholder. Your configuration file must use the .mjs extension (or .ts where supported).npm install @plaiceholder/next// next.config.mjs
// @ts-check
import withPlaiceholder from "@plaiceholder/next";
/**
* @type {import('next').NextConfig}
*/
const config = {
// your Next.js config
};
export default withPlaiceholder(config);getPlaiceholder() no longer automatically resolves images via file paths or URLs. You must now pass a Buffer directly to the function. This change allows the library to support non-Node.js runtimes.import path from "node:path";
import fs from "node:fs/promises";
import { getPlaiceholder } from "plaiceholder";
// For local images in /public (Node.js)
const getImageLocal = 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 } };
};
// For remote images (Node.js)
const getImageRemote = 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 } };
};plaiceholder packages are ESM only. The primary function getPlaiceholder(input, options) takes a raw Buffer image source and an optional configuration object to generate low-resolution placeholders and metadata.import { getPlaiceholder } from "plaiceholder";
// input must be a raw Buffer
const result = await getPlaiceholder(input, options);Guidelines: https://github.com/joe-bell/plaiceholder/blob/main/CONTRIBUTING.md#implementationsDue to the shift to ESM, configuration files for associated plugins must be migrated to ESM formats:
next.config.js to next.config.mjs (or .ts if supported).tailwind.config.js to tailwind.config.mjs or tailwind.config.ts.