@netbirdio/explain

AI-powered "Explain" assistant for React apps. Users click on UI elements and get contextual AI explanations via a chat panel.

The package has two entry points:

@netbirdio/explain/client — React components (provider, chat panel, floating button)
@netbirdio/explain/server — Node.js handler that proxies requests to Anthropic or OpenAI

No CSS framework required — the package is fully self-contained with inline styles and CSS custom properties.

Installation

npm install @netbirdio/explain

Peer dependencies: react >=18, react-dom >=18.

For local development as a workspace package, add it to your package.json:

{
  "dependencies": {
    "@netbirdio/explain": "file:./packages/@netbirdio/explain"
  }
}

If you're using Next.js, add to next.config.js:

module.exports = {
  transpilePackages: ["@netbirdio/explain"],
};

Client

Setup

Wrap your app with AIAssistantProvider:

import { AIAssistantProvider } from "@netbirdio/explain/client";

export default function App({ children }) {
  return (
    <AIAssistantProvider
      endpoint="http://localhost:3080/api/ai/chat"
      apiKey="your-api-key"
    >
      {children}
    </AIAssistantProvider>
  );
}

This renders the floating action button and chat panel automatically. No CSS imports are needed — the provider injects all required styles via CSS custom properties.

Props

Prop	Type	Required	Description
`endpoint`	`string`	Yes	URL of the AI chat API
`apiKey`	`string`	No	Bearer token sent with each request
`children`	`ReactNode`	Yes	Your application

Marking elements as explainable

Add the data-nb-explain attribute to any element you want users to be able to click on in explain mode:

<div data-nb-explain>
  <Label>Name</Label>
  <Input value={name} onChange={setName} />
</div>

When clicked, the library extracts a label from the element (first <label>, heading, or text content) and sends it as the query.

You can also pass a custom label directly:

<div data-nb-explain="Database connection string">...</div>

Documentation URLs

Attach docs to an element or its parent so the AI can reference them:

<div data-nb-explain-docs='["https://docs.example.com/resources"]'>
  <div data-nb-explain>...</div>
</div>

Excluding elements

Use data-nb-explain-ignore to prevent an element from being selectable in explain mode:

<button data-nb-explain-ignore onClick={enterExplainMode}>
  Explain
</button>

Setting page/modal context

Use the useAIAssistant hook to provide context that gets included in every query:

import { useAIAssistant } from "@netbirdio/explain/client";

function MyModal() {
  const { setExplainContext, clearExplainContext } = useAIAssistant();

  useEffect(() => {
    setExplainContext({
      modalName: "Add Resource",
      pageName: "Networks",
      docsUrls: ["https://docs.example.com/networks"],
    });
    return () => clearExplainContext();
  }, []);

  return <div data-nb-explain>...</div>;
}

This produces queries like: Explain "Name" on Add Resource modal in Networks.

Hook API

useAIAssistant() returns:

Method / Property	Description
`openChat(query?)`	Open the chat panel, optionally with a query
`closeChat()`	Close the chat panel
`isChatOpen`	Whether the chat panel is open
`explainMode`	Whether explain mode is active
`enterExplainMode()`	Activate explain mode (click-to-explain)
`exitExplainMode()`	Deactivate explain mode
`setExplainContext(ctx)`	Set page/modal context for queries
`clearExplainContext()`	Clear the context

Theming

The package ships with a dark theme out of the box. All visual properties are controlled via CSS custom properties (--nb-explain-*) injected into :root by the provider. Override any of them in your own CSS to match your app's look and feel.

How it works

AIAssistantProvider injects a <style> tag with default values for all --nb-explain-* variables.
Components use inline styles that reference these variables (e.g., background: var(--nb-explain-bg)).
Your CSS can override any variable — later declarations on :root or more specific selectors win.

Overriding in CSS

Add a stylesheet or <style> block after the provider mounts (or use higher specificity):

:root {
  /* Change to a light theme */
  --nb-explain-bg: #ffffff;
  --nb-explain-bg-subtle: rgba(0, 0, 0, 0.04);
  --nb-explain-bg-hover: rgba(0, 0, 0, 0.06);
  --nb-explain-border: rgba(0, 0, 0, 0.12);
  --nb-explain-text: #1a1a1a;
  --nb-explain-text-muted: #6b7280;
  --nb-explain-text-dim: #9ca3af;
  --nb-explain-accent: #2563eb;
  --nb-explain-accent-hover: #3b82f6;
  --nb-explain-user-bg: #2563eb;
  --nb-explain-user-text: #ffffff;
}

Full variable reference

Variable	Default	Description
`--nb-explain-bg`	`#0a0a0f`	Chat panel background
`--nb-explain-bg-subtle`	`rgba(255,255,255,0.06)`	Input field & assistant message bg
`--nb-explain-bg-hover`	`rgba(255,255,255,0.08)`	Hover state background
`--nb-explain-border`	`rgba(255,255,255,0.1)`	Border color
`--nb-explain-text`	`#f0f0f5`	Primary text color
`--nb-explain-text-muted`	`#9ca3af`	Secondary text color
`--nb-explain-text-dim`	`#6b7280`	Placeholder / tertiary text
`--nb-explain-accent`	`#eab308`	Accent color (buttons, icons)
`--nb-explain-accent-hover`	`#facc15`	Accent hover state
`--nb-explain-accent-glow`	`rgba(234,179,8,0.15)`	Accent glow (avatar backgrounds)
`--nb-explain-user-bg`	`#4f46e5`	User message bubble background
`--nb-explain-user-text`	`#ffffff`	User message text color
`--nb-explain-user-glow`	`rgba(79,70,229,0.25)`	User avatar glow
`--nb-explain-radius`	`12px`	Panel border radius
`--nb-explain-radius-sm`	`8px`	Message bubble border radius
`--nb-explain-radius-xs`	`6px`	Button border radius
`--nb-explain-font`	system font stack	Font family for all components
`--nb-explain-shadow`	large drop shadow	Chat panel box shadow
`--nb-explain-banner-bg`	`rgba(234,179,8,0.92)`	Explain mode banner background
`--nb-explain-banner-text`	`#000000`	Explain mode banner text
`--nb-explain-error-text`	`#f87171`	Error message text

Data attributes

Attribute	Description
`data-nb-explain`	Marks element as explainable. Value can be a custom label or boolean.
`data-nb-explain-docs`	JSON array of documentation URLs for context.
`data-nb-explain-ignore`	Element is non-interactive during explain mode.

Server

The server module provides a framework-agnostic handler that proxies chat requests to Anthropic or OpenAI.

With Express

import express from "express";
import { createAssistant } from "@netbirdio/explain/server";

const assistant = createAssistant({
  provider: "anthropic",
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-sonnet-4-20250514",
  systemPrompt: "You are a helpful assistant for MyApp.",
});

const app = express();
app.use(express.json());

app.post("/api/ai/chat", assistant.handler({ apiKey: "your-api-key" }));

app.listen(3080);

With plain Node.js HTTP

import http from "http";
import { createAssistant } from "@netbirdio/explain/server";

const assistant = createAssistant({
  provider: "openai",
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o",
});

const handle = assistant.handler({ apiKey: "your-api-key" });

http.createServer(handle).listen(3080);

Programmatic usage (no HTTP)

const assistant = createAssistant({
  provider: "anthropic",
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const { reply } = await assistant.chat({
  messages: [{ role: "user", content: "What is a network resource?" }],
});

`createAssistant(config)`

Option	Type	Required	Default
`provider`	`"anthropic"` \| `"openai"`	Yes	—
`apiKey`	`string`	Yes	—
`model`	`string`	No	Provider default
`systemPrompt`	`string`	No	Generic assistant prompt

`assistant.handler(opts?)`

Returns a (req, res) => Promise<void> handler compatible with Express, plain http, and similar frameworks.

Option	Type	Description
`apiKey`	`string`	If set, requires `Authorization: Bearer <key>` on requests

API contract

Request POST /api/ai/chat

{
  "messages": [
    { "role": "context", "content": "Docs: https://..." },
    { "role": "user", "content": "Explain network routes" }
  ]
}

Response

{
  "reply": "Network routes allow you to..."
}

Error codes: 400 (bad request), 401 (unauthorized), 502 (LLM error).

Standalone dev server

The server/ directory in the dashboard repo contains a ready-to-run Express server for local development.

cd server
cp .env .env.local   # edit with your LLM API key
npm install
node index.js

Environment variables:

Variable	Default	Description
`PORT`	`3080`	Server port
`API_KEY`	`nb-ai-dev-key-change-me`	Bearer token for auth
`LLM_PROVIDER`	`anthropic`	`anthropic` or `openai`
`ANTHROPIC_API_KEY`	—	Anthropic API key
`ANTHROPIC_MODEL`	`claude-sonnet-4-20250514`	Model ID
`OPENAI_API_KEY`	—	OpenAI API key
`OPENAI_MODEL`	`gpt-4o`	Model ID
`SYSTEM_PROMPT`	Generic NetBird prompt	System prompt for the LLM

Full integration example

// layout.tsx — wrap app with provider
import { AIAssistantProvider } from "@netbirdio/explain/client";

export default function Layout({ children }) {
  return (
    <AIAssistantProvider
      endpoint={process.env.NEXT_PUBLIC_AI_SERVER_URL || "http://localhost:3080/api/ai/chat"}
      apiKey={process.env.NEXT_PUBLIC_AI_API_KEY || "nb-ai-dev-key-change-me"}
    >
      {children}
    </AIAssistantProvider>
  );
}

// MyModal.tsx — add explain support to a modal
import { useAIAssistant } from "@netbirdio/explain/client";
import { Sparkles } from "lucide-react";

function MyModal() {
  const { setExplainContext, clearExplainContext, explainMode, enterExplainMode, exitExplainMode } =
    useAIAssistant();

  useEffect(() => {
    setExplainContext({
      modalName: "Add Resource",
      pageName: "Networks",
      docsUrls: ["https://docs.netbird.io/manage/networks"],
    });
    return () => clearExplainContext();
  }, []);

  return (
    <div data-nb-explain>
      <button
        data-nb-explain-ignore
        onClick={() => (explainMode ? exitExplainMode() : enterExplainMode())}
      >
        <Sparkles size={13} />
        {explainMode ? "Click an element..." : "Explain"}
      </button>

      <div data-nb-explain>
        <label>Name</label>
        <input placeholder="e.g., Postgres Database" />
      </div>

      <div data-nb-explain>
        <label>Address</label>
        <input placeholder="e.g., 10.0.0.1" />
      </div>
    </div>
  );
}

License

BSD-3-Clause

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
example		example
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

@netbirdio/explain

Installation

Client

Setup

Props

Marking elements as explainable

Documentation URLs

Excluding elements

Setting page/modal context

Hook API

Theming

How it works

Overriding in CSS

Full variable reference

Data attributes

Server

With Express

With plain Node.js HTTP

Programmatic usage (no HTTP)

`createAssistant(config)`

`assistant.handler(opts?)`

API contract

Standalone dev server

Full integration example

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

@netbirdio/explain

Installation

Client

Setup

Props

Marking elements as explainable

Documentation URLs

Excluding elements

Setting page/modal context

Hook API

Theming

How it works

Overriding in CSS

Full variable reference

Data attributes

Server

With Express

With plain Node.js HTTP

Programmatic usage (no HTTP)

createAssistant(config)

assistant.handler(opts?)

API contract

Standalone dev server

Full integration example

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`createAssistant(config)`

`assistant.handler(opts?)`

Packages