Installation

npm

npm install @chartbuddy.io/embed

import { Insight, version } from '@chartbuddy.io/embed';

CDN (recommended for HTML / LLM artifacts)

Import the latest embed from unpkg or jsDelivr:

import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';

Equivalents:

• https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.single.mjs — single-file build
• https://cdn.jsdelivr.net/npm/@chartbuddy.io/embed

Single-file vs multi-file

Build	When
Single-file (package root / .single.mjs)	AI artifacts, strict CSP, one script tag
Multi-file (chartbuddy-embed.mjs + siblings)	Sites you control that can load engine assets

For LLM / artifact hosts: always use the single-file path. Do not pass assetBase. Do not import engine internals (d3, wasm, workers) yourself.

Bundle size and many charts

ChartBuddy ships a chart editor, not a draw-only chart library, so it is considerably heavier than Chart.js or Recharts. Plan for it.

Asset	Raw	Gzipped
chartbuddy-embed.single.mjs (engine, all-in-one)	2.24 MB	~560 KB
chartbuddy-embed.mjs (multi-file loader only)	40 KB	~13 KB
webapp-entry.js (engine, fetched by the loader)	1.92 MB	~449 KB
labelPlacementAccel.wasm (label placement)	1.43 MB	~314 KB
react.mjs / vue.mjs / element.mjs (framework bindings)	6–8 KB each	~2 KB each

What that means in practice:

• The engine loads once per page, not once per chart. The loader is idempotent, so ten Insights on a dashboard share one engine download. Chart number ten costs you draw time and DOM, not another 560 KB.
• The wasm is a separate file, not part of the bundle. It accelerates label placement and is fetched by a worker when that path runs, so it does not block first paint.
• The multi-file build defers the weight. Your bundle grows by ~13 KB gzipped; the engine arrives as a separate cacheable request on first mount. Prefer it for sites you control. The single-file build trades that for one request and no assetBase, which is what artifact and strict-CSP hosts need.
• View-only and editable load the same engine. editable: false is a lighter mount, not a lighter download.

For a dashboard of many small tiles, the honest advice is to measure before you commit: mount your real chart count and watch draw time, because that — not the download — is what you will feel. If tiles are below the fold, defer mounting until they scroll into view.

There is no headless or server-side render path today, so charts cannot be pre-rendered on a server.

TypeScript

Types ship as chartbuddy-embed.d.ts from the package (types field).

Framework bindings

Framework	Import	Peer dependency
React 18/19	@chartbuddy.io/embed/react	react (optional)
Vue 3	@chartbuddy.io/embed/vue	vue (optional)
Angular, Svelte, Solid, Lit, plain HTML	@chartbuddy.io/embed/element	none

Each ships its own types. Angular uses the <chartbuddy-insight> custom element rather than a compiled Angular library, so ChartBuddy upgrades are not tied to your Angular major — see the Angular guide.

Guides: React · Vue · Angular & web components.