---
url: https://chartbuddy.io/embed/docs/getting-started/installation.md
---
# Installation

## npm

```bash
npm install @chartbuddy.io/embed
```

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

## CDN (recommended for HTML pages and single-file embeds)

Import the latest embed from unpkg or jsDelivr:

```js
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`) | Single HTML page, strict CSP, one script tag |
| **Multi-file** (`chartbuddy-embed.mjs` + siblings) | Sites you control that can load engine assets |

For single-script or strict-CSP hosts: 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/angular).

Guides: [React](/guides/react) · [Vue](/guides/vue) ·
[Angular & web components](/guides/angular).