Quickstart (React)

This quickstart walks through configuring registry access, installing the SDK, and rendering the Copilot component in a React 18+ application.

Prerequisites

Requirement	Details
Node.js	Version 16.x or higher
Package manager	npm or yarn
NPM registry access	Configured authentication token for @gocommotion packages
Organization app key	Obtained from the Commotion team

Caution

The SDK is hosted on a private GitLab npm registry. Contact the Commotion team to request an authentication token and organization app key. Treat the token like a password - never commit it to version control.

1. Configure npm registry access.

   Create a .npmrc file in your project root pointing the @gocommotion scope at the private registry and supplying your token:

   @gocommotion:registry=https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/
   //gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/:_authToken=<YOUR_AUTH_TOKEN>

   Replace <PROJECT_ID> and <YOUR_AUTH_TOKEN> with the values supplied by the Commotion team.

2. Install the package.

   npm

   npm install @gocommotion/copilot-sdk@prod

   yarn

   yarn add @gocommotion/copilot-sdk@prod

3. Verify peer dependencies.

   React 18.2.0 or higher is required as a peer dependency. Ensure both react and react-dom are installed in your application:

   npm install react@18 react-dom@18

   Dependency	Supported versions	Required
   react	18.2.0 through 19.x	Yes
   react-dom	18.2.0 through 19.x	Yes

4. Initialize the SDK once.

   For most React applications, create a dedicated configuration file to initialize the SDK once. This pattern prevents multiple initializations and centralizes configuration.

   import { initializeCopilotSDK } from '@gocommotion/copilot-sdk';
   
   // Initialize once with your organization's app key
   export const { Copilot } = initializeCopilotSDK('YOUR_APP_KEY');

5. Render the Copilot component.

   Import the initialized component and render it where you need the chat interface:

   import { Copilot } from '@/lib/copilot';
   
   export function DashboardPage() {
     return <Copilot userId="user-123" mode="embed" />;
   }

Tip

See the full props reference for every prop the Copilot component accepts, including workerId, agentId, systemContext, and panel-visibility controls.

Why peer dependencies?

Peer dependencies ensure your application uses the same React instance as the SDK. This prevents duplicate React bundles and version conflicts.

Why centralized initialization?

Initializing the SDK once in a central location ensures consistent behavior across your application and avoids redundant initialization overhead. Export the Copilot component from a single module and import it throughout your app.

Next steps

• Pick the right mode for your use case (embed, preview, link_preview, or widget).
• Review the full props reference.
• Integrating outside of React? See the Browser ESM guide (recommended) or the UMD guide for legacy environments.