@jnet/chatbot-sdk

Floating, voice-enabled chat assistant for React apps. Supports Google Gemini and Anthropic Claude, local route matching without an API key, and generative UI (OpenUI) for non-navigation questions.

For maintainers (this repo)

Full guide: docs/CHATBOT_SDK_RELEASE_AND_CONSUME.md

Release workflow (version → build → publish → use elsewhere)

npm login   # once on your machine

# Bugfix release (0.1.0 → 0.1.1), build, pack, publish to npm
npm run release:chatbot-sdk -- patch --publish

# Or explicit version
bash scripts/release-chatbot-sdk.sh 0.2.0 --publish

# Pack only (tarball, no npm)
bash scripts/release-chatbot-sdk.sh patch

Other products then:

npm install @jnet/[email protected]
# or tarball: npm install /path/to/hrms-max/releases/jnet-chatbot-sdk-0.1.1.tgz

Individual commands

| Command | Purpose | |---------|---------| | npm run build:chatbot-sdk | Build dist/ | | npm run pack:chatbot-sdk | Build + releases/*.tgz (current version) | | npm run release:chatbot-sdk -- patch --publish | Bump patch + pack + npm publish | | npm run publish:chatbot-sdk | Publish current version (no bump) |

GitHub Packages — add to packages/chatbot-sdk/.npmrc:

@jnet:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then set publishConfig.registry in package.json and run npm publish.

4. Try the demo app

cd packages/chatbot-sdk/examples/demo
cp .env.example .env
# edit .env with VITE_GEMINI_API_KEY
npm install
npm run dev

Open http://localhost:5175

For other products (consumers)

Option A — Install from tarball (recommended for internal apps)

After someone runs npm run pack:chatbot-sdk in this monorepo:

npm install /path/to/hrms-max/releases/jnet-chatbot-sdk-0.1.0.tgz

Or copy the .tgz into your product repo:

npm install ./vendor/jnet-chatbot-sdk-0.1.0.tgz

Option B — Install from npm (after publish)

npm install @jnet/chatbot-sdk

Peer dependencies

npm install react react-dom framer-motion lucide-react react-router-dom
npm install @lottiefiles/dotlottie-react   # optional

Quick start

import { BrowserRouter, useNavigate } from "react-router-dom";
import { ChatBot, buildRoutesFromCatalog } from "@jnet/chatbot-sdk";
import "@jnet/chatbot-sdk/styles.css";

const routes = buildRoutesFromCatalog([
  {
    id: "home",
    path: "/",
    label: "Home",
    description: "Landing page",
    moduleLabel: "Main",
    aliases: ["dashboard", "start"],
  },
  {
    id: "settings",
    path: "/settings",
    label: "Settings",
    moduleLabel: "Main",
  },
]);

function AppShell() {
  const navigate = useNavigate();

  return (
    <ChatBot
      routes={routes}
      apiKey={import.meta.env.VITE_GEMINI_API_KEY}
      provider="gemini"
      appName="My Product"
      onNavigate={(path) => navigate(path)}
    />
  );
}

export default function App() {
  return (
    <BrowserRouter>
      <AppShell />
    </BrowserRouter>
  );
}

Add to .env:

VITE_GEMINI_API_KEY=your_key

If you use React Router everywhere, you can omit onNavigate (the SDK uses useNavigate() inside <BrowserRouter>).

Route catalog

| Field | Required | Description | |-------|----------|-------------| | path | yes | Exact path for navigation | | label | yes | Display / voice name | | description | no | Helps matching and LLM | | moduleLabel | no | Groups pages for list/explain | | aliases | no | Synonyms | | id | no | Stable id |

Security

Browser-exposed API keys are visible to users. For production, proxy Gemini/Claude through your backend.

Troubleshooting: Invalid hook call / duplicate React

This happens when the host app and @jnet/chatbot-sdk load two different copies of react (common in monorepos).

Fix in your Vite app (vite.config.ts):

import path from "node:path";
import { fileURLToPath } from "node:url";

const root = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  resolve: {
    dedupe: ["react", "react-dom", "react/jsx-runtime", "framer-motion"],
    alias: {
      react: path.resolve(root, "node_modules/react"),
      "react-dom": path.resolve(root, "node_modules/react-dom"),
      "react/jsx-runtime": path.resolve(root, "node_modules/react/jsx-runtime.js"),
    },
  },
});

Then delete node_modules/.vite and restart the dev server.

Install the SDK from the .tgz tarball, not file:../source, when testing outside this repo.

HRMS Max

Host app uses src/adapters/hrms-chatbot.ts for routes and imports @jnet/chatbot-sdk in Layout.tsx.