Copilot Widget SDK

Cimulate's Copilot Widget SDK is a React component library which allows you to embed our Copilot Widget into your app.

Installation

Requires Node >= 22.15.0 and npm >= 10.9.2

npm install @cimulate/copilot-widget

Playgrounds

React App Playground

npm start

Simulates a React environment. Faster for local development because Vite serves source via hot-module replacement — no full build is required, and changes reflect instantly in the browser. This is the most appropriate testing playground for customers who will integrate the widget in a React-based storefront.

Settings are in src/App.tsx. Example configurations you can modify:

// Theme definitions
const THEMES: Record<string, ThemeConfig> = {
  sfra: {
    primaryColor: "#0070D2",
    fontFamily: '"Helvetica Neue", Arial, sans-serif',
    backgroundColor: "#F7F7F7",
    // ...
  },
  "storefront-next": {
    primaryColor: "#000000",
    fontFamily: '"Inter", sans-serif',
    backgroundColor: "#FFFFFF",
    // ...
  },
};

// Copilot mode props
<CopilotWidget
  apiKey={apiKey}
  theme={currentTheme}
  logoUrl="https://example.com/logo.png"
  headerText="Cimulate Copilot"
  isDevelopment={true}
/>

// Agentforce/Messaging mode props
<AgentForceWidget
  headerText="Commerce Client"
  disclaimerMarkdown="This is AI, *be careful*."
  isDevelopment={true}
  theme={currentTheme}
  searchConfig={{
    placeholder: "Find me cutting-edge outdoor gear",
    buttonLabel: "Go",
    buttonType: "icon-text",
    buttonIconUrl: "https://example.com/icon.png",
  }}
  messagingConfig={{
    scrt2Url: "",
    orgId: "",
    esDeveloperName: "AgentForce",
  }}
/>

HTML / CDN Integration Playground

npm run preview

The most common integration method because it is framework-agnostic. Any changes to the widget should be tested on this playground. It is slower for local development because it must produce a full build of all three artifacts (main bundle, copilot sub-bundle, messaging sub-bundle) and requires a rebuild on every change.

Settings are in public/index.html. Example configurations you can modify:

<script>
  // Widget injection with configuration
  injectCopilotWidget({
    elementId: "root",
    apiKey: "INSERT_YOUR_API_KEY_HERE",
    componentConfig: { isOpen: true, options: { dialogPosition: "bottom-right" } },
    isDevelopment: true,
    mode: "copilot",
    theme: {
      primaryColor: "#000000",
      fontFamily: '"Inter", sans-serif',
      backgroundColor: "#FFFFFF",
    },
    headerText: "Commerce Client",
    searchConfig: {
      placeholder: "Find me cutting-edge outdoor gear",
      buttonLabel: "Go",
      buttonType: "icon-text",
    },
  });

  // Event handlers for programmatic control
  const { eventHandlers } = window["cimulate-copilot-widget"];

  eventHandlers.search.updateSearchQuery("running shoes");
  eventHandlers.components.setWidgetType("modal"); // "chat" | "dialog" | "modal"
  eventHandlers.components.toggleWidgetOpen(true);
  eventHandlers.pdp.setPdpContext({ productId: "product-123" });
  eventHandlers.browse.setBrowseContext({ categoryId: "outdoor-gear" });
</script>

Publish Flow

This project follows trunk-based development — all changes merge directly to master. The package uses semantic versioning; bump the version in package.json before merging. Be mindful of backwards-compatibility since customers have existing implementations relying on the public API.

Publishing is handled automatically by the Build and Publish Javascript Packages GitHub Actions workflow (.github/workflows/build-and-publish-js.yaml).

Trigger: Push to master with changes under javascript/ (only runs for copilot-widget).

Steps:

1. Install dependencies
2. Run tests (npm run test)
3. Build (npm run build)
4. Publish to npm (npm publish --access public)
5. Upload UMD bundles and CSS to a Google Cloud Storage bucket for CDN delivery, versioned by the package version:

   <bucket>/copilot-widget/<version>/*.umd.js
   <bucket>/copilot-widget/<version>/*.css

Creating Symlinks

To develop against local versions of the SDK dependencies, use npm link:

copilot-sdk

# In javascript/copilot-sdk
npm install
npm run build
npm link

# In javascript/copilot-widget
npm link @cimulate/copilot-sdk

agentforce-sdk

# In javascript/agentforce-sdk
npm install
npm run build
npm link

# In javascript/copilot-widget
npm link @cimulate/agentforce-sdk

To unlink and restore the registry version:

npm unlink @cimulate/copilot-sdk
npm unlink @cimulate/agentforce-sdk
npm install