---
url: https://chartbuddy.io/embed/docs/guides/versioning.md
---
# Versioning

## chartData documents

Every `chartData` object can carry a top-level **`version`** field (the ChartBuddy release that wrote the JSON, for example `"1.8.3"`).

**Always version JSON you store or ship.** When an older chart loads in a newer `@chartbuddy.io/embed` release, ChartBuddy runs its migration pipeline automatically and converts the document to the current schema. You do not need to rewrite saved charts by hand when you upgrade the package.

That forward compatibility is why versioning matters:

* A chart saved months ago with a `version` stamp still mounts in today's embed.
* Missing `version` makes it harder to pick the right migration path; stamped JSON is unambiguous.

Stamp on save from the running embed:

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

const insight = new Insight('#chart', { chartData: myChart });
await insight.ready;

const toStore = {
  ...insight.getChartData(),
  version, // or the version field already on getChartData()
};
```

Or export from the editor (`exportConfig()` / full `getChartData()` round-trip). Both include the resolved tree; keep `version` when you persist it.

Migration runs on mount (and when chart data enters the engine). If transformers apply, the in-memory document is updated to the current format for that release. See also the [`version` field](/api/chart-data#top-level-map) in the chartData reference.

## Embed package

Examples and live previews load the **latest** `@chartbuddy.io/embed` from unpkg. Check the running version at runtime:

```js
import { version } from '@chartbuddy.io/embed';
console.log(version);
```

## Docs site

This docs site is **single-version**. It documents the current embed package.