icons-only

A minimal Atomic Payload template that exercises the @pro-laico/icons plugin on its own, with no design sets or forms wired in. It is the Icon and IconSet collections plus a small Next.js page that renders them, and it also demonstrates the requested-icons usage panel and runtime miss tracking.

What it shows

This example demonstrates @pro-laico/icons in isolation:

• iconsPlugin({ iconSetOptions: { livePreviewUrl, usagePanel: true }, trackRequests: true }) registered in payload.config.ts adds the icon and iconSet collections to the admin UI. usagePanel: true puts a "Requested icons" panel on the IconSet edit view, and trackRequests: true registers the hidden iconRequest collection and makes <Icon> record names that fail to resolve at runtime.
• The seed creates two icon sets: a "Demo Icon Set" (active) and a "Second Demo Set", each holding the same six SVG icons (arrow-right, check, cog, heart, star, x). It is auth-gated to logged-in admins. Re-running the seed replaces the sample data: it clears every iconSet, deletes each sample icon (and its file), and re-uploads, so it always lands on a clean, current state.
• / renders every Icon doc inline by inlining its svgString field, and renders each IconSet as a labelled grid.
• The Seed and Reset buttons are server actions that call seedIcons / resetIcons directly (gated by payload.auth), not a fetch to /api/seed. The POST /api/seed and POST /api/reset REST routes still exist.
• The "Requested icons" panel: open an IconSet in the admin and it diffs the names the app requests against the set's icons. The demo page renders an IconChildTile with name="y", which the seeded set does not define, so "y" shows as missing. With trackRequests on, visiting the page also records "y" as a live runtime miss, which appears in the panel with a count, and a Clear runtime requests button wipes those records. The iconRequest collection that backs this is hidden from the admin nav.
• Live preview is wired for iconSet edits: open any iconSet in the admin, click the Live Preview tab, and edits propagate to the home page in real time via <LivePreviewListener> and the /next/preview route handler.

Scaffold it

npx @pro-laico/create-atomic-payload my-icons --template icons-only

pnpm dlx @pro-laico/create-atomic-payload my-icons --template icons-only

Then set up and run it:

cp .env.example .env       # set long PAYLOAD_SECRET + PREVIEW_SECRET (DATABASE_URI is optional)
cp gitignore.template .gitignore
pnpm install
pnpm generate:types        # generates src/payload-types.ts + augment
pnpm generate:importmap    # populates src/app/(payload)/admin/importMap.js
pnpm generate:icons        # scans src for icon names, writes icon-usage-manifest.json
pnpm dev

How it works

1. Open http://localhost:3000/admin and create your first user.
2. Go back to http://localhost:3000. The seed button is now visible: click it to create the sample icons and sets.
3. The page now renders the icons. Refresh after editing in the admin to see updates.

A few details worth knowing:

• The seed endpoint reads each set's SVG files from src/seed/icons/ and src/seed/icons-two/ at request time, then uses Payload's local API (payload.create) to feed the SVG bytes directly via the file argument, so the upload pipeline (including the icons plugin's formatSVGHook) runs end-to-end.
• The page uses dangerouslySetInnerHTML to inline each icon's svgString field. Because the icons are uploaded SVGs that pass through formatSVGHook, the strings are already optimized and stripped of script tags by SVGO.
• Workspace dependency direction: this template depends on @pro-laico/icons, which in turn pulls in @pro-laico/core and @pro-laico/atomic.

What to look at

src/
  payload.config.ts                     # buildConfig: the only place iconsPlugin runs
  instrumentation.ts                    # registerPayloadConfig for the cache getters
  collections/users.ts                  # auth collection (required by Payload)
  seed/
    sampleIcons.ts                      # reads the SVG folders into icon-set manifests
    icons/                              # SVGs for the active "Demo Icon Set"
    icons-two/                          # SVGs for the "Second Demo Set"
  app/
    (frontend)/
      layout.tsx                        # plain HTML layout, no design system
      page.tsx                          # demo page: lists icons + sets, seed button
      CodeBlock.tsx                     # Shiki-highlighted snippets on the page
      next/preview/route.ts             # live-preview entry route handler
      next/exit-preview/route.ts        # exits live-preview / draft mode
    (payload)/
      layout.tsx                        # Payload admin RootLayout
      custom.scss                       # admin overrides (empty)
      admin/
        importMap.js                    # `pnpm generate:importmap` populates this
        [[...segments]]/
          page.tsx                      # Payload admin entry
          not-found.tsx
      api/
        [...slug]/route.ts              # Payload REST endpoint
        seed/route.ts                   # POST /api/seed → seeds the sample sets
        reset/route.ts                  # POST /api/reset → clears the seeded data

The icon-usage manifest is written to icon-usage-manifest.json at the project root (generated by pnpm generate:icons, gitignored).

Related