CASOON Open Source

Charts and diagrams, finished at build time.

Describe a chart in a small JSON file, and chartlet compiles it into plain SVG or an HTML figure with caption, source and data table. A chart ships no JavaScript, and the same specification gives the same bytes on every build.

npmcargo

npm install @casoon/chartlet

cargo install chartlet

Try it in the browser Use it with an AI agent Add it to a project →

MITv0.23.00 bytes of chart JavaScript

Rendered by chartlet during this build from examples/energy-flow.json, with its phone variant on small screens.

Three ways to a first result

Status: before 1.0, so a minor release may change the specification; flow, state and class diagrams are experimental. The support matrix says what is verified and what is only designed."No browser JavaScript" means a chart: static SVG and HTML figures carry no script. The interactive module and the playground are optional JavaScript that a chart never loads.

Quiet when it works, exact when it does not

A valid specification renders without a word. Invalid input is refused with a code and the path of the field, and the exit code tells CI. A compromise such as a canvas that is too small still renders, with a warning that says what to change.

--strict turns warnings into failures, and --preview shows every save on a local page.

Warnings and errors CLI reference →

Terminal, real chartlet 0.21.0 runs. chartlet render energy-flow.json -o sankey.svg prints nothing, and ls lists sankey.svg. duplicate.json has the label January twice; chartlet render duplicate.json fails with 'chartlet: duplicate_label at /data/1/label: labels must be unique in a single-series chart', and echo $? prints 1. chartlet render narrow-flow.json renders with 'warning[canvas_too_small] at /width: the diagram needs 499 pixels here and was drawn that large; raise width to 499, shorten labels, or try the other orientation'.

From the showcase

All 150 examples →

Parliament

Time series with bands

Network

bytes of chart JavaScript in the browser: 0
examples, also the golden-file test inputs: 150
minimum contrast of every series colour on white: 4.5:1
types of chart and diagram, from one JSON schema: 37

What it does

Accessible by default
Every chart carries a title and a description generated from the data, and the HTML output always includes the complete data as a table.
Deterministic and honest
The same specification produces the same bytes, so charts can be reviewed, diffed and cached. Problems come with a code and a path instead of happening silently.
Diagrams laid out for you
Sequence, flow, state, architecture, class, tree, network, cycle, layer, plan, Venn, fishbone, kanban, story map, journey and value map diagrams come from what is connected or listed. chartlet places the boxes, routes the edges and keeps the main path straight.

Where it runs

Generated at build time

All examples →

Focus

Show all Commit pushed Code review Build Run tests All green? Fix failures Deploy to staging Approved? Deploy to production Released

From commit to release

Source: Team handbook, release process

Show chart data

Data for From commit to release
Step	Kind	Lane	Group	Leads to
Commit pushed	start	Development		Code review
Code review	step	Development		Build (merged)
Build	step	Continuous integration	Quality gates	Run tests
Run tests	step	Continuous integration	Quality gates	All green?
All green?	decision	Continuous integration	Quality gates	Deploy to staging (yes), Fix failures (no)
Fix failures	step	Development		Build (retry)
Deploy to staging	step	Operations		Approved?
Approved?	decision	Operations		Deploy to production (yes), Code review (changes requested)
Deploy to production	step	Operations		Released
Released	end	Operations

Diagrams too: this flow chart is laid out by chartlet from steps and edges alone. Click a step, or pick one under Focus, to see its neighbourhood.

examples/release-flow.json

Quickstart

From a specification to a finished chart. The CLI, the Astro component and the JavaScript API are covered in the documentation.

Install the CLI, or the npm package for Astro and JavaScript.
Describe the chart in a small JSON specification.
Render it with chartlet render spec.json -o chart.svg or the <Chart> component.

Read the documentation

spec.jsonSpecification

{
  "schemaVersion": 1,
  "type": "bar",
  "title": "Monthly revenue",
  "data": [
    { "label": "January", "value": 120 },
    { "label": "February", "value": 180 },
    { "label": "March", "value": 150 }
  ]
}

New in v0.23.0

Changelog →

Diagrams: "look": "editorial" (or --theme editorial, or a theme file with look) draws flow, sequence, state, architecture and class diagrams in neutral paper and ink with hairline strokes, one accent for the main path, type tags on nodes (DB, QUEUE, EXT, SVC, …, tag per node, "tags": false to switch off), monospace sublabels and edge labels, and edge and message labels on an unbordered mask 8 px from their line, calls · HTTPS/JSON on one line where it fits (name in sans, technology in monospace). Trees and class diagrams tag their kinds; network and cycle diagrams take the neutral boxes and masks; other charts take the paper and ink palette. low_contrast measures tokens against the editorial palette under that look. The classic look stays the default and is available as classic; no existing output changes. PNG output bundles JetBrains Mono (SIL Open Font License) for the monospace text. Details: Diagram design. Examples editorial-flow, -sequence, -architecture, -states, -classes (each with a -dark twin), editorial-dense-architecture, editorial-dense-flow, editorial-bars, editorial-trend.
Emphasis: emphasis on a flow chart, state diagram, class diagram, architecture diagram, tree, network or sequence diagram marks what to look at first: nodes (one or two) get a heavy accent outline and tint, path draws the edges (messages) between consecutive ids in the accent, and everything else stays neutral. Weight carries the cue as well as color, in light, dark and print. A mainPath without an emphasis path stays drawn in the accent. More than two emphasized nodes warn with too_much_emphasis; an unknown id is unknown_node, a path no edge joins emphasis_path_gap. The description names the emphasized elements and the table adds an Emphasis column. Details: Emphasis and legend. Examples release-focus, sign-in-focus, shop-focus, ownership-focus, dependencies-focus.
Legend: "legend": "auto" on the same diagrams draws one strip below the drawing that lists the node kinds, line patterns and emphasis that occur, when there is more than one to tell apart. It wraps into rows on a narrow canvas, grows the canvas, is left out in compact spacing (the description says so) and is off by default, so existing diagrams are drawn as before.
Flow: diagrams (flow charts, architecture, state and class diagrams) lay steps, lanes, frames and their gaps out on a 4 px grid: every step's box, its position, the gaps between steps and layers and the padding of frames and lanes are multiples of 4 px, and steps are a multiple of 8 px wide and high so that their middle lies on the grid too. Text sizes are exempt. Steps grow by up to 7 px to reach the grid, so a diagram may need a slightly larger canvas than before; tests/routing.rs asserts the grid for every diagram example.
Flow: edges that change course beside each other keep 12 px apart (the tracks were 10 px), and a way back to an earlier step keeps to the lane of the step it returns to instead of the outside of the lane it starts in, which shortens it and spares it the crossings with the lanes in between. Example release-flow loses its 3 crossings and about 8 % of its edge length.
Flow: a step that several edges meet on one side is wide enough to keep their ports 12 px apart, and runs of different edges that would still lie closer than 12 px side by side are moved apart where that leads through no step and across no further edge. Examples claim-handling, service-perspectives, release-flow and order-flow change; no diagram example has runs closer than 12 px any more.

Frequently asked questions

What does chartlet take as input?

A small, declarative JSON specification — the type of chart or diagram, the data, and optional styling. chartlet validates it against a public schema and compiles it to SVG or an HTML figure; it never runs in the browser.

How is this different from a JavaScript charting library?

There is no chart script to ship or hydrate. chartlet renders at build time to plain SVG or an HTML figure with a caption, a generated description and a data table, and the same specification always produces the same bytes.

What chart and diagram types does it support?

Dozens of chart types — bar, line, time series, scatter, box plot, Sankey, treemap, heatmap and more — plus diagrams (sequence, flow, state, architecture, class, tree, network, cycle, layers, floor plan, Venn, fishbone, kanban, story map, journey, value map) that chartlet lays out itself from what is connected.

Can an AI agent generate charts with chartlet?

Yes. The MCP server @casoon/chartlet-mcp lets an assistant inspect data or a request, draft a specification, and have chartlet validate and compile it — no model runs inside the server and your data is never altered.

Is chartlet stable enough to build on?

chartlet is before 1.0: a minor release may still change the specification, and flow, state and class diagrams are marked experimental. The support matrix in the documentation lists what is verified and what is only designed.