Package a browser plugin

An external plugin is distributed as a standalone classic browser script. Its entry queues the plugin before the Icon Visualizer embed starts.

Install the SDK

Install the reviewed versioned SDK tarball supplied for plugin development:

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

Pin the exact SDK version used for a release. Do not use an unreviewed floating dependency.

Package scripts

{
  "name": "customer-visualizer-plugin",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "type-check": "tsc --noEmit",
    "build": "npm run type-check && vite build"
  },
  "dependencies": {
    "@iconfigurators/plugin-sdk": "file:./iconfigurators-plugin-sdk-VERSION.tgz"
  },
  "devDependencies": {
    "typescript": "YOUR_REVIEWED_VERSION",
    "vite": "YOUR_REVIEWED_VERSION"
  }
}

Use the dependency form appropriate to how the reviewed tarball is supplied. Commit the lockfile used to produce a release.

TypeScript configuration

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

Browser entry

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

queuePlugin(plugin, {
  order: 20,
  required: false,
  options: {
    customerId: 'CUSTOMER_ID',
  },
})

Top-level work should only prepare and queue the plugin. Defer fallible browser work until setup() so failures can be attributed to its registration.

Vite library build

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

export default defineConfig({
  build: {
    sourcemap: true,
    lib: {
      entry: 'src/preboot.ts',
      name: 'CustomerVisualizerPlugin',
      formats: ['iife'],
      fileName: () => 'customer-visualizer.plugin.js',
    },
  },
})

The output must bundle SDK helpers and plugin-owned dependencies. Do not mark them as host-provided externals.

Artifact requirements

The final script must:

• Run as a classic browser script without import maps
• Include its own SDK helpers and optional renderer
• Queue exactly the intended plugin at top level
• Avoid credentials and server-only values
• Avoid importing private Icon Visualizer code
• Clean up plugin-owned resources during disposal

Source maps are useful for reviewed test deployments. Decide separately whether they should be publicly available in production.

Load order

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

Do not use async on a script that must register startup hooks. Serve the artifact over HTTPS and set a cache policy that matches the release and rollback strategy.

Verify the output

npm run build

Then load it on a nonproduction page and confirm its stable ID reaches ready:

const api = await window.iConfigurator.ready()
console.log(api.getPluginStatus('customer.visualizer-plugin'))

Continue with Test a plugin and Release and rollback.