Installation

Skip installation entirely: open Start Studio (pnpm dev:studio, port 3003) to pick a template, tools, handoff target, and analytics sink, then download a runnable repo with the SDK bundled inside. First conversation in under three minutes — no manual install required.

The rest of this guide is for adding the SDK to an existing project, not for first-time exploration.

Prerequisites

• Node.js 20 or newer (download)
• pnpm 9.15+ — run corepack enable if pnpm is not already available
• Git — required to clone the repo or work on the SDK locally

Verify your setup

Run these before continuing. If any command errors or returns the wrong version, fix it first — most "weird install failures" trace back to here.

node --version     # v20.0.0 or newer
corepack enable    # makes pnpm available; safe to re-run
pnpm --version     # 9.15.0 or newer
git --version

Install the SDK

The SDK is not yet published to a public npm registry. Pick whichever local-install option fits your setup:

Option 1 — workspace install (recommended for experimenting in the monorepo):

pnpm add gecx-chat --workspace

Option 2 — local tarball (install into any sibling project):

# From inside this repo:
pnpm --filter gecx-chat build
pnpm --filter gecx-chat pack            # produces gecx-chat-0.1.0-prototype.tgz

# From your other project:
npm install /path/to/gecx-chat-0.1.0-prototype.tgz

Once published, installation will be the one-liner you expect:

npm install gecx-chat
# or
pnpm add gecx-chat

Package exports

The SDK ships multiple entry points. Import only what you need:

import { createChatClient, defineClientTool } from 'gecx-chat';          // Core runtime
import { useChatSession, MessagePart } from 'gecx-chat/react';           // React adapter
import { createChatTokenHandler } from 'gecx-chat/server';               // Server helpers
import { createMockChatClient } from 'gecx-chat/testing';                // Test utilities
import { createRichContentRegistry } from 'gecx-chat/rich-content';      // Rich content
import { createA2UISurfaceManager } from 'gecx-chat/a2ui';               // Generative UI (core)
import { createA2UIRenderer } from 'gecx-chat/a2ui/react';               // Generative UI (React)
import { createWidgetEventBridge } from 'gecx-chat/compat';              // Legacy widget bridge

See Package Exports Reference for a complete listing of every export.

Run the demos locally

Clone the repo and start the showcase:

git clone https://github.com/andrewhuot/headless-chat-sdk.git
cd headless-chat-sdk
pnpm install --frozen-lockfile
pnpm build:packages     # required — apps import the SDK from dist/
pnpm dev                 # Showcase on http://localhost:3000

No credentials are needed. The demos use mock auth and mock transport by default.

TypeScript configuration

The SDK ships as ESM with bundled .d.ts type declarations. Plain JavaScript projects can use it too — just import from gecx-chat directly. For TypeScript projects, your tsconfig.json should include:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true
  }
}

What's next

• Quickstart — send your first message in 5 minutes
• React Quickstart — build a chat UI with React
• Project Structure — understand the repo layout