Image Placeholder (Strapi v5 plugin)

Create a Base64 image placeholder for any newly created or updated image stored on S3 (or any URL‑accessible storage). The plugin adds a placeholder field to plugin::upload.file and automatically fills it during lifecycle events.

This is useful for blurred image previews while the full image loads on the client.

Features

• Auto‑generates Base64 placeholders on image create/update.
• Extends plugin::upload.file with a placeholder text attribute.
• Uses plaiceholder under the hood.
• Supports remote/public URLs (e.g., S3 public URLs).

Requirements

• Strapi v5.x (tested with @strapi/strapi@^5.23.3).
• Upload plugin enabled (plugin::upload).
• Publicly accessible image URLs from your storage provider (or your server must be able to fetch them).
• Node 18+.

Installation

Install from npm after publishing your package. The current package name is placeholder. If you publish under a different name (e.g. strapi-plugin-image-placeholder), replace accordingly.

• npm: npm install placeholder
• yarn: yarn add placeholder
• pnpm: pnpm add placeholder

Enable The Plugin

Add the plugin to your Strapi project’s config/plugins.ts and provide its configuration. The size option is required and validated (min: 4, max: 64). It is passed to plaiceholder.

Example config/plugins.ts:

import type { Core } from '@strapi/strapi';

export default ({ env }: { env: Core.Env }) => ({
  // ...other plugins
  placeholder: {
    enabled: true,
    config: {
      // Required: integer between 4 and 64
      size: 8,
    },
  },
});

There is also a ready‑to‑copy example at examples/config/plugins.ts in this repo.

How It Works

• On register, the plugin augments plugin::upload.file with a placeholder text attribute.
• On beforeCreate and beforeUpdate lifecycles for plugin::upload.file:
  • If the file is an image and has a resolvable url, the plugin fetches the image bytes.
  • It generates a Base64 placeholder using plaiceholder and stores it in file.placeholder.

Accessing The Placeholder

When you fetch files (REST or GraphQL), the placeholder field will be available on the upload.file entries. Example:

{
  "id": 1,
  "url": "https://your-bucket.s3.amazonaws.com/path/to/image.jpg",
  "mime": "image/jpeg",
  "placeholder": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

You can use this Base64 string in your frontend as a blurred preview.

Configuration

Currently supported options (under config):

• size (number, required): Controls the size fed to plaiceholder (range 4–64). Smaller values are blurrier and faster; larger values are sharper with larger Base64 strings.

Example:

placeholder: {
  enabled: true,
  config: {
    size: 12,
  },
}

Notes and Limitations

• The plugin fetches the image from its url on your Strapi server. Ensure the URL is accessible from the server (public S3 or proper network/VPC access). For private S3, consider generating signed URLs that Strapi can fetch during lifecycles.
• Only files with mime starting with image/ and a truthy url are processed.
• Errors during fetching or placeholder generation are logged and the placeholder is set to null.

Troubleshooting

• Validation error about size:
  • Ensure you provided size in config/plugins.ts and it’s between 4 and 64.
• Upload plugin not installed:
  • Install and enable @strapi/plugin-upload. The placeholder plugin depends on it.
• Placeholders not generated for updates:
  • The plugin merges missing url/mime from the existing file on update, but if the URL is still not reachable from the server, generation will be skipped or fail.
• Large images or slow network:
  • Consider a smaller size to reduce processing time and Base64 length.

Security & Performance

• Your server fetches the image via fetch(url). Avoid exposing private buckets without proper access control.
• Generating placeholders adds processing per upload/update; tune size to balance quality and speed.

License

MIT © Kian Tavakoli