CommandBar JavaScript SDK

Common errors

• ReferenceError: CommandBar is not defined

  cause The CommandBar SDK script has not been loaded or the `init` function has not been called before attempting to access `window.CommandBar`.
  fix Ensure `import { init } from 'commandbar'; init('YOUR_ORG_ID');` has been executed successfully before any calls to `window.CommandBar` methods. For non-module usage, verify the `<script>` tag for CommandBar's snippet is correctly placed and loaded in your HTML.

• TypeError: window.CommandBar.boot is not a function

  cause The `init` function was either not called or failed, meaning the `window.CommandBar` object was not properly populated with its API methods.
  fix Check that `init('YOUR_ORG_ID')` is called exactly once and completes without errors before any subsequent calls to `window.CommandBar.boot` or other `window.CommandBar` methods.

• Error: init requires an orgId

  cause The `init` function was called without providing the required organization ID string.
  fix Provide your unique CommandBar organization ID as the first argument to `init`, e.g., `init('YOUR_ORGANIZATION_ID');`.

• Error: boot requires a userId

  cause The `window.CommandBar.boot` function was called without providing the required user ID string.
  fix Pass a valid authenticated user ID string as the first argument to `window.CommandBar.boot`, e.g., `window.CommandBar.boot(authenticatedUserID);`. For anonymous users, pass `null` or an empty string as explicitly documented.

Warnings

• gotcha The `commandbar` npm package has a last publish date of 2 years ago (version 1.14.0). While the core library is stable, the CommandBar service itself is actively developed with newer features like AI Copilot and mobile support, which may involve server-side updates or separate mobile SDKs rather than new npm package versions. Ensure your expectations align with this release cadence for the JavaScript SDK.
  Fix: Monitor CommandBar's official documentation for announcements regarding new versions or updates to their web SDK, and consider the implications of a less frequently updated npm package for new feature adoption.
• gotcha Initialization order is critical. The `init` function must be called first with your `orgId` before `window.CommandBar.boot` or any other SDK methods are invoked. Calling other methods before `init` will result in errors.
  Fix: Ensure `init(ORG_ID)` is executed once at the earliest possible stage in your application's lifecycle, typically before any UI components that might interact with CommandBar are mounted or rendered.
• gotcha After initialization, the CommandBar SDK exposes its API primarily through a global `window.CommandBar` object. Directly importing methods like `boot` or `addCommands` from the package will not work as they are not exported for direct module consumption in this manner; they are designed to be accessed from the global instance.
  Fix: Always interact with the SDK methods via `window.CommandBar.methodName(...)` after `init` has successfully run. If `window.CommandBar` is undefined, ensure `init` was called correctly and the script had time to load.
• gotcha Both `init` and `boot` functions require mandatory arguments (`orgId` for `init` and `userId` for `boot`). Failing to provide these will lead to runtime errors and CommandBar will not function.
  Fix: Always pass your valid CommandBar organization ID to `init` and an authenticated user ID (or `null` for anonymous users) to `boot`. Validate these values before calling the functions.

Install

• npm install commandbar npm
• yarn add commandbar yarn
• pnpm add commandbar pnpm

Imports

• init
  wrong:

  const init = require('commandbar').init;

  correct:

  import { init } from 'commandbar';

  The `init` function must be called once with your organization ID before `window.CommandBar.boot` or any other SDK methods are used.
• boot
  wrong:

  import { boot } from 'commandbar';
  boot(userId);

  correct:

  window.CommandBar.boot(userId);

  After `init` is called, the core CommandBar instance is exposed globally on `window.CommandBar`. The `boot` method is accessed via this global object and is crucial for identifying the user and making CommandBar available.
• addCommands
  wrong:

  import { addCommands } from 'commandbar';

  correct:

  window.CommandBar.addCommands([/* commands */]);

  Like `boot`, `addCommands` is a method on the global `window.CommandBar` object, used to programmatically add custom commands to the bar.
• Types

  import type { CommandBarOptions, Command } from 'commandbar';

  The library ships with built-in TypeScript types, which are beneficial for development in TypeScript projects.

Quickstart

This quickstart demonstrates how to initialize the CommandBar SDK with an organization ID and then 'boot' it for a specific user, including how to add a custom command. This sequence is essential for the CommandBar UI to appear and function correctly in your application.

import { init } from 'commandbar';

// Initialize CommandBar with your organization ID.
// This should typically run once when your application starts.
const MY_ORG_ID = process.env.COMMANDBAR_ORG_ID ?? 'YOUR_ORGANIZATION_ID'; // Replace with your actual ID
init(MY_ORG_ID);

// Simulate a user authentication flow and boot CommandBar for the identified user.
function initializeUserCommandBar(userID: string) {
  if (typeof window.CommandBar !== 'undefined' && window.CommandBar.boot) {
    window.CommandBar.boot(userID, { 
      // Optional user properties for analytics and targeting
      plan: 'pro', 
      signedUpDate: new Date().toISOString() 
    });
    console.log(`CommandBar booted for user: ${userID}`);

    // Example of adding a custom command
    window.CommandBar.addCommands([
      {
        id: 'navigate-dashboard',
        name: 'Go to Dashboard',
        description: 'Navigates to the main user dashboard.',
        handler: () => {
          alert('Navigating to dashboard...');
          // In a real app, you'd use your router here: e.g., router.push('/dashboard');
        },
        // You can add additional metadata for filtering, etc.
        category: 'Navigation'
      }
    ]);
    console.log('Custom command added: Go to Dashboard');
  } else {
    console.error('CommandBar is not initialized or available globally.');
  }
}

// Example usage: Call this function after a user logs in or is identified.
const authenticatedUserID = 'user_12345'; // Replace with actual authenticated user ID
initializeUserCommandBar(authenticatedUserID);

// You can also boot for anonymous users if needed (pass null or an empty string for userID)
// initializeUserCommandBar(null);