Dashboard Icons

To automate the icon synchronization process, create a new workflow file at .github/workflows/sync-<yoursource>.yml. This workflow runs on a schedule or can be triggered manually. It installs dependencies, fetches your source's manifest, and executes the importer script.

Required Repository Secrets

To allow the workflow to communicate with the backend, you must configure the following secrets in your GitHub repository:

• PB_URL: The PocketBase instance URL (e.g., https://pb.dashboardicons.com).
• PB_ADMIN: The PocketBase superuser email.
• PB_ADMIN_PASS: The PocketBase superuser password.

name: Sync yoursource icons

on:
  schedule:
    - cron: "0 5 * * *"        # Daily at 05:00 UTC (adjust as needed)
  workflow_dispatch:            # Manual trigger

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          cache-dependency-path: web/pnpm-lock.yaml

      - run: cd web && pnpm install --frozen-lockfile

      - name: Fetch yoursource manifests
        run: |
          cd web
          mkdir -p data/sources/yoursource
          curl -fsSL https://example.com/manifest.json -o data/sources/yoursource/index.json

      - name: Import external icons
        env:
          NEXT_PUBLIC_POCKETBASE_URL: ${{ secrets.PB_URL }}
          PB_ADMIN: ${{ secrets.PB_ADMIN }}
          PB_ADMIN_PASS: ${{ secrets.PB_ADMIN_PASS }}
        run: cd web && pnpm exec tsx scripts/import-yoursource.ts

When adding a new external icon source, ensure you have completed the following tasks:

Required Tasks

• Added source ID to ExternalSourceId union in constants.ts
• Added full config entry to EXTERNAL_SOURCES in constants.ts
• Created PocketBase migration adding source to the source select field
• Written importer script at scripts/import-<source>.ts
• Added .gitignore exception for the importer
• Created GitHub Actions workflow at .github/workflows/sync-<source>.yml
• Added remotePatterns entry in next.config.ts
• Added Playwright tests in tests/external-icons.spec.ts
• Updated README.md with source documentation

Verification Steps

• Verified: url_templates has explicit keys for every format+theme combination
• Verified: variants are merged if applicable (e.g. -color as primary)
• Verified locally: importer runs with --dry-run, icons appear in browse, detail page renders
• Verified: source filter dropdown shows new source with its icon
• Verified: themed previews work in both light and dark modes
• Verified: CMD+K search returns new source icons with badge
• Verified: hero hover popover shows new source count
• Verified: pnpm build generates static pages for all new slugs

The application can display external icon metadata from selfh.st/icons using the external_icons PocketBase collection. This allows using icons hosted on jsDelivr without local storage.

Prerequisites

If the collection does not exist, import data/sources/selfhst/external_icons.collection.json in the PocketBase admin UI under Collections before running the importer. This JSON defines the fields, public rules (listRule: "", viewRule: ""), and the (source, slug) unique index.

Import Process

1. Download the required metadata files:

   mkdir -p data/sources/selfhst
   curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index.json -o data/sources/selfhst/index.json
   curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index-consolidated.json -o data/sources/selfhst/index-consolidated.json
   curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/tags.json -o data/sources/selfhst/tags.json

2. Run the import script:

   PB_ADMIN=admin@example.com PB_ADMIN_PASS=your-password \
   NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090 \
   bun run scripts/import-selfhst.ts

Icon URL Pattern

External icons are served via jsDelivr using the following pattern: https://cdn.jsdelivr.net/gh/selfhst/icons/<format>/<slug>.<format>

Note: Every external icon card and detail page must display Icons by selfh.st/icons (CC BY 4.0).

When building UI components to display icons, use getVariantDefinition() to retrieve metadata (labels, descriptions, and icons) for any variant. This allows the UI to support both preset variants (like light or dark) and custom user-defined variants dynamically.

Rendering Logic Pattern:

1. Retrieve all variant names from iconData.variants and iconData.wordmark.
2. Sort variants so that presets appear first, followed by custom variants in alphabetical order.
3. Map through the sorted list and use getVariantDefinition(variantName) to render the appropriate section.

import { getVariantDefinition, groupVariantsByCategory } from "@/lib/variant-definitions"

// Sort: preset variants first, then custom variants alphabetically
const sortedVariants = allVariants.sort((a, b) => {
  const aDef = getVariantDefinition(a)
  const bDef = getVariantDefinition(b)
  if (aDef.preset && !bDef.preset) return -1
  if (!aDef.preset && bDef.preset) return 1
  return a.localeCompare(b)
})