@devx-labs/strapi-preview 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratham Bhatia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @devx-labs/strapi-preview
+
+A Strapi 5 plugin that adds a **preview image URL** field to any component and renders all component previews as a side panel in the edit view.
+
+Component authors set the image URL once in the Content-Type Builder (no Media Library required — any HTTPS URL works), and the panel displays the matching image live for every component on the entry. Dynamic-zone reorders are reflected immediately, and components without a configured preview are simply skipped.
+
+## Install
+
+```bash
+npm install @devx-labs/strapi-preview
+# or
+yarn add @devx-labs/strapi-preview
+# or
+bun add @devx-labs/strapi-preview
+```
+
+Register the plugin in `config/plugins.ts` (Strapi only auto-discovers packages whose names start with `strapi-plugin-` — this one uses a scope, so an explicit entry is needed):
+
+```ts
+export default () => ({
+  'component-preview-image': {
+    enabled: true,
+    resolve: '@devx-labs/strapi-preview',
+  },
+});
+```
+
+The plugin's internal id is `component-preview-image` (that's why the key in the config object is `component-preview-image`, not `strapi-preview`). Don't change that key.
+
+Rebuild the admin:
+
+```bash
+npm run build
+```
+
+## Add the preview field to your components
+
+In Strapi's Content-Type Builder, edit a component → **Add another field** → **Custom** → pick **"Preview Image"**. Name the field exactly `preview` (any name works, but `preview` is the convention).
+
+In the field's **Base settings**, fill in **Preview Image URL** with a direct image URL (Shopify CDN, S3, Cloudinary, picsum, anything reachable by the browser).
+
+## Usage
+
+1. Configure the `preview` field on each component you want to preview (URL is set once per component schema in CTB).
+2. Open any entry that uses your components — for example a Page with a dynamic zone of blocks.
+3. The **Component previews** side panel on the right shows every component on the entry, with its preview image, in the current dynamic-zone order.
+4. The custom field itself renders a small **Preview ↗** button inside each component instance so editors can quickly open the full image in a new tab.
+
+### Behavior
+
+- Dynamic zone: panel items appear in the current order. Reorder components → panel reorders live (no save required).
+- Components without a configured `preview` URL are silently skipped.
+- Regular (non-dynamic-zone) component fields are also rendered, including repeatable components.
+- No Media Library coupling: URLs are plain strings, so previews can live on any CDN — useful when your component thumbnails live separately from your production media (e.g. a private design-system bucket).
+
+## CSP note
+
+If your preview URLs point to external hosts (Shopify CDN, etc.), make sure your CSP `img-src` permits them. The simplest broad allow is `"https:"` in `config/middlewares.ts`:
+
+```ts
+'img-src': ["'self'", 'data:', 'blob:', 'https:', 'market-assets.strapi.io'],
+```
+
+## What the plugin registers
+
+- Custom field type: `plugin::component-preview-image.preview-image` (stored as `string`)
+- Custom field UI: a compact **Preview ↗** link button rendered inside each component instance
+- Content-Manager edit-view side panel: **Component previews**
+- Content-API route: `GET /api/component-preview-image/options` returning a `{ [componentUid]: { name, url } }` map (used internally by the side panel)
+
+## Supported Strapi versions
+
+Strapi 5.x
+
+## License
+
+MIT

package/admin/src/components/ComponentPreviewPanel.tsx

@@ -0,0 +1,206 @@
+import { useEffect, useState } from 'react';
+import { Box, Button, Flex, Typography } from '@strapi/design-system';
+import type { PanelComponent } from '@strapi/content-manager/strapi-admin';
+import { unstable_useContentManagerContext } from '@strapi/content-manager/strapi-admin';
+import { useForm, useFetchClient } from '@strapi/strapi/admin';
+import { ExternalLink } from '@strapi/icons';
+
+type SchemaAttribute = {
+  type?: string;
+  component?: string;
+  repeatable?: boolean;
+};
+
+type SchemaDefinition = {
+  attributes?: Record<string, SchemaAttribute>;
+  info?: { displayName?: string };
+};
+
+type PreviewOption = { name: string; url: string };
+
+type PreviewItem = {
+  uid: string;
+  displayName: string;
+  previewUrl: string;
+  previewName: string;
+  count: number;
+  tempKey?: string;
+};
+
+const collectPreviewItems = (
+  value: unknown,
+  attributes: Record<string, SchemaAttribute> | undefined,
+  componentSchemas: Record<string, SchemaDefinition>,
+  optionsMap: Record<string, PreviewOption>
+): PreviewItem[] => {
+  const items: PreviewItem[] = [];
+
+  if (!value || !attributes || typeof value !== 'object') return items;
+
+  const pushItem = (componentUid: string, tempKey?: string) => {
+    const opts = optionsMap[componentUid];
+    if (!opts) return;
+    const schema = componentSchemas[componentUid];
+    items.push({
+      uid: componentUid,
+      displayName: schema?.info?.displayName ?? componentUid,
+      previewUrl: opts.url,
+      previewName: opts.name,
+      count: 1,
+      tempKey,
+    });
+  };
+
+  for (const [attributeName, attribute] of Object.entries(attributes)) {
+    const attributeValue = (value as Record<string, unknown>)[attributeName];
+    if (!attributeValue) continue;
+
+    if (attribute.type === 'dynamiczone' && Array.isArray(attributeValue)) {
+      for (const item of attributeValue) {
+        if (!item || typeof item !== 'object') continue;
+        const componentUid = (item as { __component?: string }).__component;
+        const tempKey = (item as { __temp_key__?: string }).__temp_key__;
+        if (componentUid) pushItem(componentUid, tempKey);
+      }
+      continue;
+    }
+
+    if (attribute.type === 'component' && attribute.component) {
+      const componentUid = attribute.component;
+      if (attribute.repeatable && Array.isArray(attributeValue)) {
+        for (let i = 0; i < attributeValue.length; i++) {
+          const item = attributeValue[i] as { __temp_key__?: string } | undefined;
+          pushItem(componentUid, item?.__temp_key__);
+        }
+      } else {
+        pushItem(componentUid);
+      }
+    }
+  }
+
+  return items;
+};
+
+export const ComponentPreviewPanel: PanelComponent = () => {
+  const { components, contentType, isCreatingEntry } = unstable_useContentManagerContext();
+  const values = useForm('ComponentPreviewPanel', (state) => state.values);
+  const { get } = useFetchClient();
+  const [optionsMap, setOptionsMap] = useState<Record<string, PreviewOption>>({});
+
+  useEffect(() => {
+    let cancelled = false;
+
+    get('/api/component-preview-image/options')
+      .then(({ data }: { data: Record<string, PreviewOption> }) => {
+        if (!cancelled) setOptionsMap(data ?? {});
+      })
+      .catch(() => {
+        if (!cancelled) setOptionsMap({});
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const previewItems = collectPreviewItems(
+    values,
+    contentType?.attributes,
+    components as Record<string, SchemaDefinition>,
+    optionsMap
+  );
+
+  if (isCreatingEntry) {
+    return {
+      title: 'Component previews',
+      content: (
+        <Typography variant="omega" textColor="neutral600">
+          Save this entry once to load component previews.
+        </Typography>
+      ),
+    };
+  }
+
+  if (previewItems.length === 0) {
+    return {
+      title: 'Component previews',
+      content: (
+        <Typography variant="omega" textColor="neutral600">
+          No component previews are available for this entry yet.
+        </Typography>
+      ),
+    };
+  }
+
+  return {
+    title: 'Component previews',
+    content: (
+      <Flex direction="column" gap={4} alignItems="stretch">
+        {previewItems.map((item, index) => (
+          <Box
+            key={item.tempKey ?? `${index}-${item.uid}`}
+            borderColor="neutral200"
+            background="neutral0"
+            hasRadius
+            padding={3}
+            shadow="tableShadow"
+            width="100%"
+            overflow="hidden"
+            style={{ boxSizing: 'border-box' }}
+          >
+            <Flex direction="column" gap={3} alignItems="stretch">
+              <img
+                src={item.previewUrl}
+                alt={item.previewName || item.displayName}
+                style={{
+                  width: '100%',
+                  maxWidth: '100%',
+                  display: 'block',
+                  borderRadius: '8px',
+                  border: '1px solid #dcdce4',
+                  objectFit: 'cover',
+                  boxSizing: 'border-box',
+                }}
+              />
+              <Flex
+                justifyContent="space-between"
+                alignItems="flex-start"
+                gap={2}
+                width="100%"
+              >
+                <Box style={{ minWidth: 0, flex: 1 }}>
+                  <Typography variant="sigma" textColor="neutral800">
+                    {item.previewName || item.displayName}
+                  </Typography>
+                  <Typography
+                    variant="pi"
+                    textColor="neutral600"
+                    style={{
+                      display: 'block',
+                      overflowWrap: 'anywhere',
+                      wordBreak: 'break-word',
+                    }}
+                  >
+                    {item.uid}
+                  </Typography>
+                </Box>
+                <Button
+                  variant="tertiary"
+                  size="S"
+                  tag="a"
+                  href={item.previewUrl}
+                  target="_blank"
+                  rel="noreferrer"
+                  endIcon={<ExternalLink />}
+                  style={{ flexShrink: 0 }}
+                >
+                  Open
+                </Button>
+              </Flex>
+            </Flex>
+          </Box>
+        ))}
+      </Flex>
+    ),
+  };
+};

package/admin/src/components/PreviewImageInput.tsx

@@ -0,0 +1,31 @@
+import { Flex, LinkButton } from '@strapi/design-system';
+import { ExternalLink } from '@strapi/icons';
+
+type PreviewImageInputProps = {
+  attribute?: {
+    options?: {
+      url?: string;
+    };
+  };
+};
+
+export const PreviewImageInput = ({ attribute }: PreviewImageInputProps) => {
+  const url = attribute?.options?.url;
+
+  if (!url) return null;
+
+  return (
+    <Flex justifyContent="flex-end">
+      <LinkButton
+        href={url}
+        target="_blank"
+        rel="noreferrer"
+        variant="tertiary"
+        size="S"
+        endIcon={<ExternalLink />}
+      >
+        Preview
+      </LinkButton>
+    </Flex>
+  );
+};

package/admin/src/index.tsx

@@ -0,0 +1,47 @@
+import { ComponentPreviewPanel } from './components/ComponentPreviewPanel';
+
+export default {
+  register(app: any) {
+    app.customFields.register({
+      name: 'preview-image',
+      pluginId: 'component-preview-image',
+      type: 'string',
+      inputSize: { default: 12, isResizable: false },
+      intlLabel: {
+        id: 'component-preview-image.preview-image.label',
+        defaultMessage: 'Preview Image',
+      },
+      intlDescription: {
+        id: 'component-preview-image.preview-image.description',
+        defaultMessage:
+          'Schema-level preview image — set the image URL once in the Content-Type Builder, shown in the edit-view side panel',
+      },
+      components: {
+        Input: async () =>
+          import('./components/PreviewImageInput').then((mod) => ({
+            default: mod.PreviewImageInput,
+          })),
+      },
+      options: {
+        base: [
+          {
+            name: 'options.url',
+            type: 'text',
+            intlLabel: {
+              id: 'component-preview-image.options.url.label',
+              defaultMessage: 'Preview Image URL',
+            },
+            description: {
+              id: 'component-preview-image.options.url.description',
+              defaultMessage: 'Direct URL of the image to display in the preview panel',
+            },
+          },
+        ],
+      },
+    });
+  },
+
+  bootstrap(app: any) {
+    app.getPlugin('content-manager').apis.addEditViewSidePanel([ComponentPreviewPanel]);
+  },
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@devx-labs/strapi-preview",
+  "version": "1.0.3",
+  "description": "Strapi 5 plugin that adds a preview-image custom field (configured per component in the Content-Type Builder with a direct image URL) and renders a side panel in the edit view showing each component's preview image in dynamic-zone order.",
+  "keywords": [
+    "strapi",
+    "plugin",
+    "strapi-plugin",
+    "component-preview",
+    "preview-image",
+    "custom-field",
+    "side-panel"
+  ],
+  "author": {
+    "name": "Pratham Bhatia"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prathambdevx/strapi-component-preview.git"
+  },
+  "homepage": "https://github.com/prathambdevx/strapi-component-preview#readme",
+  "bugs": {
+    "url": "https://github.com/prathambdevx/strapi-component-preview/issues"
+  },
+  "main": "./strapi-server.js",
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-admin": {
+      "import": "./strapi-admin.js",
+      "default": "./strapi-admin.js"
+    },
+    "./strapi-server": {
+      "require": "./strapi-server.js",
+      "default": "./strapi-server.js"
+    },
+    ".": "./strapi-server.js"
+  },
+  "files": [
+    "admin",
+    "server",
+    "strapi-admin.js",
+    "strapi-server.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "strapi": {
+    "name": "component-preview-image",
+    "displayName": "Strapi Preview",
+    "description": "Adds a preview-image custom field (URL configured in CTB) and an edit-view side panel that displays those images.",
+    "kind": "plugin"
+  },
+  "peerDependencies": {
+    "@strapi/content-manager": ">=5.0.0",
+    "@strapi/design-system": ">=2.0.0-0",
+    "@strapi/icons": ">=2.0.0-0",
+    "@strapi/strapi": ">=5.0.0",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0"
+  }
+}

package/server/src/controllers/options.ts

@@ -0,0 +1,27 @@
+import type { Core } from '@strapi/strapi';
+
+const CUSTOM_FIELD_KEY = 'plugin::component-preview-image.preview-image';
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  async getOptions(ctx: any) {
+    const result: Record<string, { name: string; url: string }> = {};
+
+    for (const [uid, schema] of Object.entries(strapi.components as Record<string, any>)) {
+      for (const attr of Object.values(schema.attributes as Record<string, any>)) {
+        if (
+          attr.type === 'customField' &&
+          attr.customField === CUSTOM_FIELD_KEY &&
+          attr.options?.url
+        ) {
+          result[uid] = {
+            name: schema.info?.displayName || uid,
+            url: attr.options.url,
+          };
+          break;
+        }
+      }
+    }
+
+    ctx.body = result;
+  },
+});

package/server/src/index.ts

@@ -0,0 +1,43 @@
+import type { Core } from '@strapi/strapi';
+import optionsController from './controllers/options';
+
+const PLUGIN_NAME = 'component-preview-image';
+
+export default {
+  register({ strapi }: { strapi: Core.Strapi }) {
+    strapi.customFields.register({
+      name: 'preview-image',
+      plugin: PLUGIN_NAME,
+      type: 'string',
+    });
+  },
+
+  bootstrap() {},
+  destroy() {},
+
+  config: {},
+
+  routes: {
+    'content-api': {
+      type: 'content-api',
+      routes: [
+        {
+          method: 'GET',
+          path: '/options',
+          handler: 'options.getOptions',
+          config: {
+            auth: false,
+          },
+        },
+      ],
+    },
+  },
+
+  controllers: {
+    options: optionsController,
+  },
+
+  services: {},
+  policies: {},
+  middlewares: {},
+};

package/server/src/routes/index.ts

@@ -0,0 +1,10 @@
+export default [
+  {
+    method: 'GET',
+    path: '/options',
+    handler: 'options.getOptions',
+    config: {
+      auth: false,
+    },
+  },
+];

package/strapi-admin.js

@@ -0,0 +1 @@
+export { default } from './admin/src/index';

package/strapi-server.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const CUSTOM_FIELD_KEY = 'plugin::component-preview-image.preview-image';
+
+module.exports = {
+  register({ strapi }) {
+    strapi.customFields.register({
+      name: 'preview-image',
+      plugin: 'component-preview-image',
+      type: 'string',
+      inputSize: { default: 12, isResizable: false },
+    });
+  },
+
+  bootstrap() {},
+  destroy() {},
+  config: {},
+
+  routes: {
+    'content-api': {
+      type: 'content-api',
+      routes: [
+        {
+          method: 'GET',
+          path: '/options',
+          handler: 'options.getOptions',
+          config: { auth: false },
+        },
+      ],
+    },
+  },
+
+  controllers: {
+    options: ({ strapi }) => ({
+      async getOptions(ctx) {
+        const result = {};
+
+        for (const [uid, schema] of Object.entries(strapi.components || {})) {
+          for (const attr of Object.values(schema.attributes || {})) {
+            if (
+              attr.customField === CUSTOM_FIELD_KEY &&
+              attr.options?.url
+            ) {
+              result[uid] = {
+                name: schema.info?.displayName || uid,
+                url: attr.options.url,
+              };
+              break;
+            }
+          }
+        }
+
+        ctx.body = result;
+      },
+    }),
+  },
+
+  services: {},
+  policies: {},
+  middlewares: {},
+};