Development guide

June 27, 2026 · View on GitHub

Use this page to set up flint-chart locally, run the common checks, and find the right extension path when you need to add a new capability.

Prerequisites

Node 18+ (see packages/flint-js/.nvmrc; run nvm use if you use nvm)
npm 9+ (workspaces)

First-time setup

git clone https://github.com/microsoft/flint-chart
cd flint-chart
npm install    # root workspace: packages/flint-js, packages/flint-mcp, site

Daily commands

Run these from the repository root:

Command	What it does
`npm run typecheck`	Build/typecheck `packages/flint-js` and typecheck `packages/flint-mcp`
`npm run test`	Vitest in `packages/flint-js` and `packages/flint-mcp`
`npm run build`	Build `packages/flint-js` and `packages/flint-mcp`
`npm run site`	Demo site at http://localhost:5274/
`npm run site:build`	Production build → `site/dist/`
`npm run build:mcp`	Build MCP server workspace

The demo site aliases flint-chart to packages/flint-js/src through Vite, so library edits hot-reload in the gallery and editor without rebuilding dist/.

Repo layout

flint-chart/
├── packages/
│   ├── flint-js/          npm package `flint-chart`
│   │   ├── src/core/      semantics, layout, types
│   │   ├── src/vegalite/  Vega-Lite backend
│   │   ├── src/echarts/   ECharts backend
│   │   ├── src/chartjs/   Chart.js backend
│   │   └── src/test-data/ gallery fixtures
│   ├── flint-py/          Python port preview (PyPI package planned later)
│   └── flint-mcp/         npm package `flint-chart-mcp`
├── site/                  landing, gallery, editor, docs browser
├── docs/                  architecture + site documentation sources
├── agent-skills/          AI agent skill (SKILL.md)
└── shared/test-data/      JSON fixtures (JS + Python)

How chart assembly works

Phase 0 — semantic resolution (packages/flint-js/src/core/resolve-semantics.ts)
Phase 1 — layout (packages/flint-js/src/core/compute-layout.ts)
Phase 2 — instantiation (per-backend assemble.ts + templates)

For the full flow, see Architecture.

Extension guides

Start with the guide that matches the surface you want to extend:

Extending chart templates - add a new chart type to an existing backend.
Extending semantic types - teach Flint a new field meaning that changes formatting, aggregation, scale, or color behavior.
Extending backends - add a new rendering target that consumes the shared compiler output.

Test coverage

Smoke tests: packages/flint-js/tests/smoke.test.ts
Visual coverage: Gallery, driven by TEST_GENERATORS in test-data
Shared fixtures: shared/test-data/, consumed by JS and Python tests