Build your first plugin

This guide builds a standalone browser plugin that marks one brand as a dealer recommendation.

1. Create the project

dealer-plugin/
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── plugin.ts
    └── preboot.ts

Install the approved SDK package and build tools. Until the SDK is published to a registry, the package is distributed as a reviewed tarball:

npm install ./iconfigurators-plugin-sdk-VERSION.tgz
npm install --save-dev typescript vite

2. Define the plugin

// src/plugin.ts
import { PLUGIN_API_VERSION, definePlugin } from '@iconfigurators/plugin-sdk'

export type DealerPluginOptions = {
  featuredBrandSlug?: string
  badgeLabel?: string
}

export default definePlugin<DealerPluginOptions>({
  id: 'customer.dealer-recommendation',
  version: '1.0.0',
  apiVersion: PLUGIN_API_VERSION,

  setup(api, options) {
    const featuredBrandSlug = options?.featuredBrandSlug ?? 'FEATURED_BRAND_SLUG'

    api.hooks.filter('brands:filter', (brands) =>
      brands.map((brand) => ({
        ...brand,
        dealerFeatured: brand.slug === featuredBrandSlug,
      })),
    )

    api.ui.mount('brands:card:badges', (container, context) => {
      if (context.brand.dealerFeatured !== true) return

      const badge = document.createElement('span')
      badge.textContent = options?.badgeLabel ?? 'Dealer pick'
      container.appendChild(badge)

      return () => badge.remove()
    })
  },
})

Known event, hook, and outlet names infer their public data types. Import plugin contracts only from @iconfigurators/plugin-sdk; do not depend on private visualizer modules.

3. Queue it before the embed

// src/preboot.ts
import { queuePlugin } from '@iconfigurators/plugin-sdk'
import plugin from './plugin'

queuePlugin(plugin, {
  order: 20,
  required: false,
  options: {
    featuredBrandSlug: 'FEATURED_BRAND_SLUG',
    badgeLabel: 'Dealer pick',
  },
})

4. Bundle a browser script

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      entry: 'src/preboot.ts',
      name: 'DealerVisualizerPlugin',
      formats: ['iife'],
      fileName: () => 'dealer-experience.plugin.js',
    },
  },
})

The artifact must bundle its SDK helpers and plugin-owned dependencies. It must not bundle the Icon Visualizer application.

5. Load it on the customer page

<script src="https://YOUR_DOMAIN/assets/dealer-experience.plugin.js"></script>
<div id="icf_page"></div>
<script src="https://iconfigurators.app/src/embed.cfm?ky=CONFIGURATOR_KEY"></script>

6. Verify registration

document.addEventListener('iconfigurator.ready', () => {
  const status = window.iConfigurator.getPluginStatus('customer.dealer-recommendation')
  console.log(status)
})

The expected status is ready. Continue with Test a plugin before deploying it to a production page.