# chartjs2img — full documentation (v0.3.0)

> Concatenated English docs plus the aggregated `chartjs2img llm` reference (Chart.js core + 12 bundled plugins). Auto-generated; do not edit by hand.

<!-- source: docs/en/index.md -->
<!-- route: /en -->

<Landing />

---

<!-- source: docs/en/ai/index.md -->
<!-- route: /en/ai -->

# AI Guide

chartjs2img is built to be **driven by an LLM agent**. You describe
what you want in natural language; an agent produces a valid
Chart.js configuration JSON, renders it with chartjs2img, reads back
any Chart.js errors, and iterates — no manual reference-pasting
required.

This guide is **task-oriented**. Pick one of the three usage paths
below and follow it end-to-end. Each tutorial starts from a clean
machine and ends with a rendered PNG plus the command to update
later.

## Three ways to use chartjs2img from an agent

| Tutorial                                  | Best for                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| [Claude Code plugin](./claude-plugin)     | You use Claude Code. Slash commands (`/chartjs2img-install`, `/chartjs2img-author`, `/chartjs2img-render`) drive the whole workflow. |
| [`gh skill`](./gh-skill)                  | You want the same skill bundle installed into Copilot, Cursor, Gemini CLI, or Codex alongside (or instead of) Claude Code. |
| [context7 (MCP)](./context7)              | You want an agent to retrieve chartjs2img's docs via MCP without installing anything plugin-side. Read-only. |

You can mix and match. The Claude plugin includes a `/chartjs2img-install`
skill that fetches the CLI binary; `gh skill` gives you the same
skills in other hosts; context7 is a parallel retrieval channel that
works even without any plugin.

## What you'll need

None of this is installed by chartjs2img itself. Install whatever the
tutorial of your choice calls for before starting.

| Software                                                         | For which tutorial                    | Why                                    |
| ---------------------------------------------------------------- | ------------------------------------- | -------------------------------------- |
| [git](https://git-scm.com/)                                      | All                                   | Plugin marketplaces clone over git.    |
| [Claude Code](https://code.claude.com/)                          | Claude plugin, context7               | Host that runs the skills / MCP.       |
| [GitHub CLI `gh`](https://cli.github.com/) (v2.90+)              | `gh skill`                            | Provides the `gh skill` subcommand.    |
| [Cursor](https://cursor.com/) / [Gemini CLI](https://github.com/google-gemini/gemini-cli) / [Codex](https://openai.com/index/introducing-codex/) | `gh skill` (optional target)          | Alternative skill hosts.               |
| `curl`, `tar`, `unzip` (windows)                                 | `/chartjs2img-install` runtime        | Downloading the chartjs2img binary.   |
| `bun` ([install](https://bun.sh/))                               | Only if building chartjs2img from source | You can use the release binary instead.|

You do **not** need to install the `chartjs2img` CLI manually — the
Claude plugin ships a `/chartjs2img-install` skill that handles it,
and `gh skill` users can run the same skill after installing it. If
you'd rather install chartjs2img outside your agent, follow the
standard [Quick start](/en/guide/) or [Install](/en/guide/install)
page; any install that puts `chartjs2img` on `$PATH` is picked up by
the skills automatically.

Chromium is handled separately by chartjs2img at render time — see
the main install guide if you're on linux-arm64.

## At a glance: what chartjs2img exposes

If you want the full tour before picking a tutorial:

- **[`chartjs2img llm`](./cli#chartjs2img-llm)** — one-shot Markdown
  reference teaching an agent the Chart.js config JSON shape, every
  bundled plugin's options, and the canonical examples. The
  `/chartjs2img-author` skill already inlines the JSON shape and a
  plugin catalog; reach for `chartjs2img llm` when an agent needs the
  full option tables for a specific plugin.
- **[`/llms.txt`](https://chartjs2img.ideamans.com/llms.txt) + [`/llms-full.txt`](https://chartjs2img.ideamans.com/llms-full.txt)** — public discovery files on the docs site.
- **[`context7.json`](https://github.com/ideamans/chartjs2img/blob/main/context7.json)** — registers chartjs2img for [context7](./context7) MCP retrieval.
- **[`plugins/chartjs2img`](https://github.com/ideamans/chartjs2img/tree/main/plugins/chartjs2img)** — three skills (`chartjs2img-install`, `chartjs2img-render`, `chartjs2img-author`) distributed via Claude Code and `gh skill`.

The [CLI reference page](./cli) documents `chartjs2img llm` in full —
useful whether an agent is driving it through a skill or you're
running it manually in a terminal.

## Tutorials

Start here:

- **[Claude Code plugin](./claude-plugin)** — 10-minute path if you
  already use Claude Code.
- **[`gh skill`](./gh-skill)** — if you want the skills in Copilot /
  Cursor / Gemini / Codex.
- **[context7](./context7)** — if you want an agent to *retrieve*
  chartjs2img docs over MCP without installing anything chartjs2img-
  specific.

---

<!-- source: docs/en/ai/claude-plugin.md -->
<!-- route: /en/ai/claude-plugin -->

# Claude Code plugin

The `chartjs2img` plugin bundles three skills that let Claude Code
install the CLI, author configs from a description, and render to
PNG / JPEG / WebP. The Chart.js JSON shape and a plugin catalog are
inlined into the author skill itself — no separate "load the
reference" step required.

## Prerequisites

- [Claude Code](https://code.claude.com/) installed and working.
- `git` on `PATH` (the marketplace is a git clone).

That's it. The plugin's `/chartjs2img-install` skill handles the CLI
binary + auto-downloads Chromium.

## 1. Add the marketplace

The chartjs2img plugin is distributed via **ideamans/claude-public-plugins**
(an aggregate marketplace for Ideamans' open-source plugins).

In Claude Code:

```
/plugin marketplace add ideamans/claude-public-plugins
```

The first add clones the marketplace; subsequent sessions reuse the
cache. Claude Code will confirm with something like:

```
Added marketplace ideamans-plugins from github.com/ideamans/claude-public-plugins
```

## 2. Install the plugin

```
/plugin install chartjs2img@ideamans-plugins
```

This registers three slash commands:

- `/chartjs2img-install` — install / update the CLI
- `/chartjs2img-author` — compose a config from a description (JSON
  constraints and plugin catalog inlined)
- `/chartjs2img-render` — render a config to PNG / JPEG / WebP

## 3. Install the CLI binary

```
/chartjs2img-install
```

The skill:

1. Detects your OS + arch (linux / darwin / windows × amd64 / arm64).
2. Fetches the matching release asset from github.com/ideamans/chartjs2img/releases.
3. Verifies the SHA-256 checksum.
4. Drops the binary in `~/.local/bin` (or another writable PATH directory).
5. Runs `chartjs2img --version` to confirm.

If no writable PATH directory exists, the skill stages the binary in
`/tmp` and prints the exact `sudo mv` command to complete the install.

Verify:

```
chartjs2img --version
```

Should print `chartjs2img v0.2.2` (or whatever tag is latest).

## 4. Author a chart

```
/chartjs2img-author monthly sales bar chart for Jan-Jun, data 12 19 3 5 2 15
```

The skill picks the chart type (`bar`), fills in a realistic skeleton,
validates with `chartjs2img render`, and iterates on any Chart.js
error messages until the render is clean.

It hands back the PNG path plus the JSON config so you can save, edit,
or feed into your own pipeline.

If the agent needs deeper plugin-option detail than the skill inlines,
it can pipe `chartjs2img llm` (or a single section of it) into the
conversation — see the [CLI reference](./cli#chartjs2img-llm).

## 5. Render an existing config

If you already have a `.json` file:

```
/chartjs2img-render sales.json
```

The skill redirects `chartjs2img render`'s stderr and inspects it for
`[chart ERROR]` / `[chart WARN]` messages. A clean render ends with a
one-line summary (path + size); a messaged render ends with concrete
fix suggestions (misspelled chart type, missing dataset shape, etc.).

## Updating

When a new chartjs2img version ships:

```
/plugin marketplace update
/plugin update chartjs2img@ideamans-plugins
/chartjs2img-install      # upgrades the CLI binary in place
```

The plugin manifest's `version` is pinned to chartjs2img's own version,
so a CLI bump implies a plugin bump.

## Troubleshooting

**`/chartjs2img-* : unknown command`** — the plugin isn't installed.
Run `/plugin list` to confirm; if missing, repeat step 2.

**`chartjs2img: command not found`** — binary not on PATH. Run
`/chartjs2img-install` again, or check whether your shell picked up
`~/.local/bin` (start a new shell or `exec $SHELL`).

**Rendering fails with a Chromium error** — on first render,
chartjs2img downloads Chrome for Testing. If that fails (firewall,
corporate proxy, linux-arm64), fall back to manual install + set
`CHROMIUM_PATH`. See [Install](/en/guide/install).

**Rendered image is blank** — check the skill's output for
`X-Chart-Messages`. A typo in `chart.type` or missing `datasets` is
the usual culprit. The render still succeeded technically (exit 0),
but Chart.js gave up on drawing.

## See also

- [CLI reference](./cli) — the `chartjs2img llm` output format.
- [`gh skill` tutorial](./gh-skill) — the same skills in Copilot / Cursor / Gemini / Codex.
- [Plugin publishing checklist](https://github.com/ideamans/chartjs2img/blob/main/plugins/chartjs2img/PUBLISH.md) — how we keep the plugin in sync with releases.

---

<!-- source: docs/en/ai/cli.md -->
<!-- route: /en/ai/cli -->

# CLI reference — `chartjs2img llm`

This is a **reference page**, not a tutorial. Start with one of the
tutorials ([Claude plugin](./claude-plugin) / [`gh skill`](./gh-skill)
/ [context7](./context7)) if you haven't installed anything yet.

One `chartjs2img` subcommand exists specifically for LLM consumption:
`chartjs2img llm`. It prints a self-contained Markdown reference of
Chart.js core plus every bundled plugin. Pipe it into your agent's
context on session start and configs come out right first try.

## Usage

```sh
chartjs2img llm
```

- No network access.
- No arguments.
- Stdout only.

The output covers:

- **Usage guide** — how to invoke chartjs2img (CLI vs HTTP), input JSON shape, constraints (JSON only, no functions), and caveats.
- **Chart.js core** — all 8 built-in chart types (`bar`, `line`, `pie`, `doughnut`, `radar`, `polarArea`, `scatter`, `bubble`), dataset properties, scales, and the `title` / `legend` / `tooltip` plugin option trees.
- **Bundled plugin options** — 12 sections:
  - `chartjs-plugin-datalabels`
  - `chartjs-plugin-annotation`
  - `chartjs-plugin-zoom`
  - `chartjs-plugin-gradient`
  - `chartjs-chart-treemap`
  - `chartjs-chart-matrix`
  - `chartjs-chart-sankey`
  - `chartjs-chart-wordcloud`
  - `chartjs-chart-geo`
  - `chartjs-chart-graph`
  - `chartjs-chart-venn`
  - `chartjs-adapter-dayjs-4`

Each section includes option tables (property path, type, default,
description) and a JSON example.

The Markdown is regenerated from source (`src/llm-docs/*.ts`) on
every build, so it can never drift from the implementation.

## Output shape at a glance

Approximate structure:

```
# Usage

<input JSON shape, HTTP vs CLI, JSON constraint, error feedback, exit codes>

## Chart.js core (chart.js@4.4.9)

<type, data, datasets, options, scales, title, legend, tooltip>

## Datalabels (chartjs-plugin-datalabels)

<display, anchor, align, color, font — including the chartjs2img-specific
 "off by default" policy>

## Annotation (chartjs-plugin-annotation)

<line, box, label, point, polygon, ellipse>

## Zoom (chartjs-plugin-zoom)

...

## Gradient (chartjs-plugin-gradient)

...

<plus the 7 additional chart-type plugins and the date adapter>
```

Total output: ~1400 lines, ~135 KB. Fits comfortably in modern
context windows.

## Agent prompt templates

### Minimal — opening turn

```text
You are going to author Chart.js configurations that chartjs2img will
render to images. The complete reference follows. When you produce a
JSON config:
1. Validate with `chartjs2img render -i <file> -o /tmp/check.png 2> /tmp/check.err`.
2. If /tmp/check.err is non-empty, fix and retry.
3. Report the final JSON plus the rendered image path.

---
<paste output of `chartjs2img llm`>
---
```

### Richer — with explicit gotchas

```text
<above>

Gotchas to remember:
- JSON has no functions — do not use `options.scales.y.ticks.callback` or `datalabels.formatter`.
- Animation is forced OFF internally — don't propose animated configs.
- Datalabels is disabled by default — set `options.plugins.datalabels.display: true` to show labels.
- Time-series axes need `"type": "time"` — the dayjs adapter is bundled.
```

## Piping into standard LLM CLIs

### OpenAI / generic `llm` CLI

```sh
chartjs2img llm \
  | llm -s "Generate a Chart.js config for monthly sales, Jan-Jun, values 12 19 3 5 2 15"
```

### Clipboard (macOS)

```sh
chartjs2img llm | pbcopy
```

Then paste into your agent's system-prompt box.

### File

```sh
chartjs2img llm > /tmp/chartjs2img-reference.md
```

Re-use across sessions.

## Relationship to other AI channels

- **`llms-full.txt`** on the docs site has a superset — it appends
  every docs/en/ Markdown page to the same reference. Use it if your
  agent wants both the reference and the guide pages in one payload.
- **context7** retrieves the same content via MCP when a full-bundle
  is too big for your context window.
- **`chartjs2img-author` SKILL.md** inlines the JSON shape, the error
  feedback contract, and a plugin catalog so the skill is
  self-contained. Agents fall back to `chartjs2img llm` only when
  they need the full option tables for a specific plugin.

Whichever channel an agent uses, the actual content is derived from
the same `src/llm-docs/*.ts` files, so consistency is guaranteed.

## Extending

To add / change what `chartjs2img llm` outputs, edit the relevant file
under `src/llm-docs/`. See the [Developer Guide → Adding LLM docs](/en/developer/adding-llm-doc)
for the full format.

## Troubleshooting

**`chartjs2img: command not found`** — install the binary first. See
[Install](/en/guide/install) or run `/chartjs2img-install` if you have
the Claude plugin.

**Output is empty** — that would be a bug; file an issue. The
aggregator always has at least the `usage` section.

**Output looks outdated** — check `chartjs2img --version`. Each
release rebuilds `src/llm-docs/` from the pinned plugin versions in
`src/template.ts`; old binaries reflect old plugin versions.

## See also

- [AI Guide overview](./) — pick a tutorial.
- [llms.txt](./llms-txt) — the same reference served as a static file.
- [Developer Guide → Adding LLM docs](/en/developer/adding-llm-doc) — how to extend the output.

---

<!-- source: docs/en/ai/context7.md -->
<!-- route: /en/ai/context7 -->

# context7 (MCP retrieval)

[context7](https://context7.com/) is an Upstash MCP service that
crawls a repo's documentation and serves it to any agent that speaks
[MCP](https://modelcontextprotocol.io/). Register chartjs2img once;
every MCP-capable agent (Claude Code, Cursor, Gemini CLI, Codex,
anything using the spec) can resolve + query the docs without
installing anything else.

This is a **read-only** path — context7 doesn't give agents the
ability to render charts. For that, combine it with the
[Claude plugin](./claude-plugin) or [`gh skill`](./gh-skill) tutorial.

## What context7 does for chartjs2img

When an agent asks "how do I show data labels on a bar chart in
chartjs2img?", context7:

1. Resolves `chartjs2img` to our registered library ID.
2. Searches our docs for the relevant passage (datalabels section +
   the bar example + `plugins/datalabels.display: true` requirement).
3. Returns it to the agent as MCP tool output.

No CLI install, no skill install, no binary download. Pure docs
retrieval.

## How it's set up

A `context7.json` file at the repo root tells context7 what to index:

```json
{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "chartjs2img",
  "description": "Server-side Chart.js rendering service...",
  "folders": ["docs/en", "examples", "src/llm-docs"],
  "excludeFolders": ["docs/.vitepress", "docs/public", "docs/ja", "node_modules", "dist", "tests"],
  "rules": ["Input is always Chart.js configuration JSON. ...", "..."]
}
```

The `rules` array contains 9 chartjs2img-specific pitfalls — JSON
input shape, no-functions constraint, animation forced off, datalabels
off-by-default, X-Chart-Messages feedback, exit codes, Chromium
availability. Agents always see these, regardless of which specific
doc passage they retrieve.

The live file: [github.com/ideamans/chartjs2img/blob/main/context7.json](https://github.com/ideamans/chartjs2img/blob/main/context7.json).

## How to use it from an MCP-capable agent

### Claude Code

In a session, two MCP tools become relevant:

- `mcp__context7__resolve-library-id` — input: `"chartjs2img"` or a
  vague phrase; output: the canonical library id.
- `mcp__context7__query-docs` — input: library id + a natural-language
  question; output: the retrieved passages.

Example flow the agent runs automatically:

```
user: "Draw a pie chart with data labels."
assistant calls mcp__context7__resolve-library-id("chartjs2img")
      → returns "/ideamans/chartjs2img"
assistant calls mcp__context7__query-docs(
      libraryId="/ideamans/chartjs2img",
      query="pie chart with data labels")
      → returns the pie example + the datalabels section
assistant drafts a JSON config and (if the plugin is installed)
          calls /chartjs2img-render to produce the PNG.
```

### Other MCP hosts

Any agent host that speaks MCP can add context7 as a server:

```bash
# In your MCP host's config
servers:
  context7:
    url: https://mcp.context7.com/
```

Check the host's docs for the exact configuration path (each host
stores MCP server configs differently).

## When context7 is helpful vs not

- **Helpful** when you need answers to "what does option X do" / "what
  plugin handles feature Y" / "what's the shape of data for chart
  type Z". One-shot retrieval, no install.
- **Not helpful** for actually rendering — that requires the CLI
  binary. Use [Claude plugin](./claude-plugin) or
  [`gh skill`](./gh-skill) for the render-loop.
- **Complementary**: context7 + the author/render skills is the best
  combo. context7 surfaces the right option shape; the render skill
  validates it produces a clean PNG.

## Checking that the registration succeeds

After we push `context7.json`, context7 crawls on its own schedule
(typically a few hours). From the context7 web UI
([context7.com/add-package](https://context7.com/add-package)) you
can request an expedited crawl.

Once indexed, test from Claude Code:

```
mcp__context7__resolve-library-id  → ask for "chartjs2img"
```

Should return something like `/ideamans/chartjs2img`. If it returns
empty, the crawl hasn't completed yet; check back in an hour or two.

## What we exclude from the index

- `docs/ja/**` — Japanese is a mirror of English, and duplicated
  content hurts retrieval quality. English is treated as canonical.
- `docs/.vitepress/**` — build config, not content.
- `docs/public/**` — generated artifacts (llms.txt, example PNGs).
- `node_modules/`, `dist/`, `tests/` — not docs.

If you need Japanese retrieval, file an issue — we can add a second
context7 registration for the JA docs.

## See also

- [llms.txt](./llms-txt) — a parallel, simpler discovery file at the site root.
- [CLI reference](./cli) — `chartjs2img llm` produces the same reference offline.
- [context7 docs](https://context7.com/docs/adding-libraries) — how to register your own projects.

---

<!-- source: docs/en/ai/gh-skill.md -->
<!-- route: /en/ai/gh-skill -->

# `gh skill` (multi-host)

The same `SKILL.md` files that the Claude Code plugin ships are
Agent Skills standard. `gh skill` (GitHub CLI v2.90+) can install
them into any host that honors the spec.

## Who should read this

Pick `gh skill` over the Claude plugin tutorial if:

- You use **GitHub Copilot**, **Cursor**, **Gemini CLI**, or **OpenAI Codex** (with or without Claude Code alongside).
- You want to pin to a specific git tree SHA so updates are explicit.
- You prefer the `gh` workflow to the Claude marketplace flow.

## Prerequisites

- GitHub CLI **v2.90.0 or later** (`gh --version`).
- The host you're targeting installed and working (Copilot / Cursor / Gemini / Codex / Claude Code).

Verify:

```bash
gh --version         # must be ≥ 2.90.0
gh skill --help      # the skill subcommand should list install / update / preview / search / publish
```

## Install the three skills

Each skill is installed independently so you can choose which ones
you want. Typical full set:

```bash
gh skill install ideamans/chartjs2img plugins/chartjs2img/skills/chartjs2img-render   --agent claude-code
gh skill install ideamans/chartjs2img plugins/chartjs2img/skills/chartjs2img-author   --agent claude-code
gh skill install ideamans/chartjs2img plugins/chartjs2img/skills/chartjs2img-install  --agent claude-code
```

`--agent` can be any of `claude-code`, `copilot`, `cursor`, `gemini`,
`codex`. Run the same command multiple times with different `--agent`
values to install the skill into multiple hosts.

Check what's installed:

```bash
gh skill list
```

## Skill bundle overview

Same three skills as the Claude Code plugin, so content doesn't drift:

| Skill                     | Use when…                                                          |
| ------------------------- | ------------------------------------------------------------------ |
| `chartjs2img-install`     | You need to install / update the `chartjs2img` CLI binary.         |
| `chartjs2img-author`      | You have a description but no JSON config yet. The Chart.js JSON shape and a 14-entry plugin catalog are inlined. |
| `chartjs2img-render`      | You have a JSON config and want a PNG / JPEG / WebP back.          |

Need deeper option tables for a specific plugin? `chartjs2img llm`
(the CLI subcommand) prints the full ~1400-line reference — pipe all
of it or one `## <plugin>` section into the agent as needed.

Each has standards-compliant frontmatter (`name`, `description`,
`license`, `compatibility`, `allowed-tools`) only — see the
[Agent Skills spec](https://agentskills.io/specification). No
Claude-only fields are used, so a skill installed to Copilot behaves
the same as one installed to Claude Code.

## Provenance via frontmatter

`gh skill install` writes three fields into the SKILL.md copy it places
in your host's skill directory:

- `repository: ideamans/chartjs2img`
- `ref: main` (or the specific ref you pinned)
- a tree SHA of `plugins/chartjs2img/skills/<name>` at install time

That tree SHA is how `gh skill update` detects changes — you don't need
a version bump on our side. Any change to the skill body flows through
on `gh skill update`.

## Updating

```bash
gh skill update            # updates all installed skills
gh skill update chartjs2img-render    # one by name
```

## Pinning to a specific version

By default `gh skill install` pins to the current `main` tree SHA. If
you want a specific release:

```bash
gh skill install ideamans/chartjs2img plugins/chartjs2img/skills/chartjs2img-render \
  --ref v0.2.2 \
  --agent claude-code
```

Replace `v0.2.2` with the chartjs2img tag you want. `gh skill update`
won't move you off a pinned ref unless you explicitly unpin.

## What you can't do with `gh skill`

- `gh skill` doesn't install the `chartjs2img` CLI binary itself. Run
  `/chartjs2img-install` from your host after installation, or use one
  of the install paths in the main [Install guide](/en/guide/install).
- `gh skill` doesn't orchestrate skills across hosts. If you want the
  same skill in multiple agents, run `gh skill install` once per
  `--agent`.

## Verifying the install

In your agent host, invoke any of the three skills — e.g.
`/chartjs2img-render`. It should return the skill body without a
"skill not found" error.

If a skill isn't found, check `gh skill list` then look at the host-
specific skill directory (Claude Code: `~/.claude/skills/`; others
documented by the host).

## See also

- [Claude Code plugin](./claude-plugin) — alternative install path.
- [CLI reference](./cli) — what `chartjs2img llm` returns.
- [Agent Skills spec](https://agentskills.io/specification) — the open standard the skills implement.

---

<!-- source: docs/en/ai/llms-txt.md -->
<!-- route: /en/ai/llms-txt -->

# llms.txt

chartjs2img publishes two public discovery files at the docs site
root, following the [llmstxt.org](https://llmstxt.org/) convention.
They are designed for LLM agents that land on the site without any
prior chartjs2img knowledge.

| URL                                                                             | Size       | What it is                                                  |
| ------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------- |
| [`/llms.txt`](https://chartjs2img.ideamans.com/llms.txt)                        | ~3 KB      | Index: grouped links to every English docs page             |
| [`/llms-full.txt`](https://chartjs2img.ideamans.com/llms-full.txt)              | ~135 KB    | Full bundle: concatenated Markdown of every page + `chartjs2img llm` reference |

## When to use which

### `llms.txt` — index

Use when the agent wants to **browse**. It's a short Markdown
document with:

- An H1 project title
- A blockquote summary
- `## User Guide`, `## Developer Guide`, `## AI Guide`, `## Gallery`
  sections, each listing pages as bullet links
- A final `## LLM reference (single bundle)` pointer to `llms-full.txt`

Example usage from a shell:

```bash
curl -s https://chartjs2img.ideamans.com/llms.txt | head -20
```

### `llms-full.txt` — full bundle

Use when the agent wants **everything in one payload**. It contains
the Markdown body of every English page, preceded by
`<!-- source: ... -->` comments that name the origin file, separated
by `---` horizontal rules. At the end, `chartjs2img llm`'s full
~1400-line Chart.js + plugin reference is appended.

This is "give my agent the whole manual and let it search in-context."
Appropriate for:

- One-shot agents without retrieval tools (copy the whole thing into
  the system prompt)
- Extended context windows (Claude, Gemini, GPT-4o with their long
  context modes)
- Offline inspection / audit

```bash
curl -s https://chartjs2img.ideamans.com/llms-full.txt | wc -l
```

## How the files are generated

`docs/public/llms.txt` and `docs/public/llms-full.txt` are **not
checked in**. They are regenerated at site-build time by
`scripts/build-llms-txt.ts`:

1. Walk `docs/en/**/*.md`, extract title + body.
2. Sort pages by route.
3. `llms.txt` → group pages by top-level section, emit link list.
4. `llms-full.txt` → concatenate every body, append `getLlmDocs()`
   (the aggregated Chart.js + plugin reference).
5. Write both under `docs/public/` — VitePress serves them from the
   site root.

Trigger manually:

```bash
bun run build-llms-txt
# output:
#   wrote <N> chars → docs/public/llms.txt
#   wrote <N> chars → docs/public/llms-full.txt (<N> docs concatenated)
```

The same script runs inside `docs:dev` / `docs:build` / `ai:regen`.

## Relationship to other AI channels

| Channel                | Audience                                 | Distribution                               |
| ---------------------- | ---------------------------------------- | ------------------------------------------ |
| **llms.txt**           | Any agent that can `curl`                | Static file on the docs site               |
| **llms-full.txt**      | Same, when full-text is cheaper than search | Static file on the docs site            |
| [**context7**](./context7)   | MCP-capable hosts                        | MCP server                                 |
| [**Claude plugin**](./claude-plugin) | Claude Code                    | Marketplace                                |
| [**gh skill**](./gh-skill)   | Copilot / Cursor / Gemini / Codex        | GitHub CLI                                 |
| [**`chartjs2img llm`**](./cli)| An agent running chartjs2img itself      | CLI output (`chartjs2img llm`)             |

llms.txt is the simplest, no-install channel. Even a zero-config
shell script can fetch and use it.

## What agents should do with `llms-full.txt`

A useful opening turn for an agent session:

```
SYSTEM: You are going to author Chart.js configuration JSON for
        chartjs2img. The complete reference follows. It covers the
        input format, every supported chart type, every bundled
        plugin's options, error feedback, and canonical examples.

        ---
        <paste full contents of https://chartjs2img.ideamans.com/llms-full.txt>
        ---

        When you produce a Chart.js configuration:
        1. Validate it via a subsequent `chartjs2img render` call.
        2. If X-Chart-Messages (HTTP) or stderr (CLI) is non-empty,
           fix the config and retry.
        3. Report the final JSON plus the rendered image path.
```

## URL convention

Both files are served at fixed paths, guaranteed stable:

- `https://chartjs2img.ideamans.com/llms.txt`
- `https://chartjs2img.ideamans.com/llms-full.txt`

No redirects, no auth, no user-agent sniffing. They are intended to be
`curl`-able from any environment.

## See also

- [llmstxt.org](https://llmstxt.org/) — the public standard.
- [Anthropic's llms.txt](https://code.claude.com/docs/llms.txt), [Vercel's](https://vercel.com/llms.txt), [Next.js's](https://nextjs.org/docs/llms-full.txt) — real-world reference implementations.
- [context7](./context7) — parallel MCP retrieval for agents that prefer search over full-bundle.
- [CLI reference](./cli) — how `chartjs2img llm` produces the reference that `llms-full.txt` appends.

---

<!-- source: docs/en/developer/index.md -->
<!-- route: /en/developer -->

# Developer Guide

You've cloned the repo and want to understand or extend chartjs2img.
This page points you to the right spot for each kind of change.

## What this project is

A thin service around **Chart.js rendered inside headless Chromium**:

<img src="/diagrams/architecture-overview.svg" alt="chartjs2img architecture overview: CLI and HTTP server both invoke renderer.ts, which uses puppeteer to drive headless Chromium with Chart.js and its plugins." />

<!-- Source: docs/diagrams/architecture-overview.gg (regenerated by `bun run docs:diagrams`) -->


Everything on the Node side is written so it can run unchanged under
`bun --compile` — there's no build step required for development.

## Repo layout

```
chartjs2img/
├── src/
│   ├── index.ts         # CLI entry point: argv parser, subcommand dispatch
│   ├── cli.ts           # `render` + `examples` CLI implementations
│   ├── server.ts        # `serve` HTTP server (Bun.serve)
│   ├── renderer.ts      # Puppeteer + Chromium lifecycle, screenshot pipeline
│   ├── template.ts      # Static HTML template loaded in the browser
│   ├── cache.ts         # In-memory LRU + TTL cache
│   ├── semaphore.ts     # Tiny async semaphore for concurrency control
│   ├── examples.ts      # Built-in chart examples (used by CLI + gallery)
│   ├── version.ts       # Single source of truth for VERSION
│   └── llm-docs/        # Per-module LLM-oriented Markdown snippets
│       ├── index.ts     # Aggregates + exports getLlmDocs()
│       ├── usage.ts
│       ├── chartjs-core.ts
│       ├── plugin-*.ts
│       ├── chart-*.ts
│       └── adapter-*.ts
├── examples/            # JSON inputs + PNG outputs (regenerable)
├── docs/                # VitePress bilingual documentation site
├── .github/workflows/   # CI
├── Dockerfile
├── package.json
└── README.md
```

The code base is intentionally small (~2000 LOC excluding llm-docs) —
all the heavy lifting happens inside Chromium. When you're reading, the
interesting file is usually `renderer.ts`.

## Common contribution flows

### "I want to add another Chart.js plugin"

See [Adding a Chart.js plugin](./adding-plugin).

### "I want to document a plugin for LLMs"

See [Adding LLM docs](./adding-llm-doc).

### "I want to tune concurrency / cache / browser behavior"

See [Architecture](./architecture) for the moving parts, then check
[Modules](./modules) for which file to edit. Most knobs are env vars —
no rebuild needed.

### "I hit a bug in rendering"

Check the browser console first. In `renderer.ts`, `page.on('console',
…)` and `window.__chartMessages` capture both Chromium-side and
Chart.js-side errors. They surface to the caller via `X-Chart-Messages`
(HTTP) or stderr (CLI) — see [Error handling](./error-handling).

## Running from source

```bash
bun install
bun run dev              # HTTP server on :3000
bun run cli -- help      # CLI help
bun run cli -- llm       # LLM reference output
```

`bun run` prepends the project's local binaries and doesn't need a
compiled binary. Type check with `bun run typecheck`.

## Running the full site locally

```bash
bun run docs:dev         # VitePress dev server on :5173
```

The docs site has no backend. It reads `docs/en/**` and `docs/ja/**`,
plus the sidebar/nav defined in `docs/.vitepress/config.ts`.

## Where to go next

- **[Library API (TypeScript)](./library-api)** — import `renderChart` and friends from any Bun / Node program.
- **[Architecture](./architecture)** — request flow from HTTP to PNG.
- **[Modules](./modules)** — one-line summary of each `src/*.ts` file.
- **[Types & HTTP schema](./types)** — every interface and every HTTP body.
- **[Adding a Chart.js plugin](./adding-plugin)** — 3-file change, <10 lines.
- **[Adding LLM docs](./adding-llm-doc)** — add a plugin's option table to `chartjs2img llm`.
- **[Error handling](./error-handling)** — how renderer errors / Chart.js errors / server errors differ.

---

<!-- source: docs/en/developer/adding-llm-doc.md -->
<!-- route: /en/developer/adding-llm-doc -->

# Adding LLM docs

`chartjs2img llm` prints a ~1400-line Markdown reference that teaches
an LLM how to write Chart.js configs for chartjs2img. Each section
lives in one `src/llm-docs/*.ts` file.

## When to add one

- You added a Chart.js plugin in [Adding a Chart.js plugin](./adding-plugin). Each plugin gets its own doc file.
- You noticed the existing reference misses a common foot-gun that agents keep tripping on.
- You upgraded a plugin version and its option shape changed.

## File shape

A `llm-docs/*.ts` file is a single-purpose ESM module that exports a
string called `doc`:

```ts
// src/llm-docs/plugin-example.ts
export const doc = `
## Example plugin (chartjs-plugin-example)

<one-paragraph summary of what the plugin does>

### Options

| Option                                | Type     | Default | Description              |
| ------------------------------------- | -------- | ------- | ------------------------ |
| \`options.plugins.example.enabled\`   | boolean  | \`false\` | Master toggle         |
| \`options.plugins.example.color\`     | string   | -       | CSS color              |

### JSON example

\`\`\`json
{
  "type": "bar",
  "data": { "labels": ["A"], "datasets": [{ "data": [1] }] },
  "options": {
    "plugins": {
      "example": { "enabled": true, "color": "#f39c55" }
    }
  }
}
\`\`\`

### Caveats

- \`enabled: true\` is required; the plugin is off by default.
- Does not support \`type: "treemap"\`.
`
```

Escaping rules:

- The file is a template literal, so you escape backticks (`` \` ``).
- Inside code-fence JSON, the template literal's `\n` becomes a real newline — you're just writing Markdown inside a JS string.
- TypeScript is not type-checking the Markdown; keep it consistent by hand.

## Register it

`src/llm-docs/index.ts` is the aggregator:

```ts
import { doc as pluginExample } from './plugin-example'

const docs = [
  // ...existing entries...
  pluginExample,
]
```

Order matters — `getLlmDocs()` joins entries with `\n\n` in array
order. Current convention:

1. `usage` (always first — sets context)
2. `chartjsCore`
3. Visual plugins (datalabels, annotation, zoom, gradient)
4. Chart-type plugins (treemap, matrix, sankey, wordcloud, geo, graph, venn)
5. Date adapter (`adapterDayjs`) last

Slot your new entry into the matching group.

## Conventions

**Headings.** Start each file with `## <plugin display name>` (H2, not H1 — the
bundle has no top-level H1). Sub-sections use H3.

**Option tables.** One big table per plugin. Put the full path in backticks
(`options.plugins.foo.bar`). Type column is free-form (prose is fine:
"function or string"). Mark required fields by writing `*required*` in
the Default column.

**Examples.** Always include at least one working JSON example. Keep
data tiny — 2-3 points is enough to show the shape. The example should
be copy-pasteable into `chartjs2img render`.

**Caveats.** A bullet list of things LLMs keep getting wrong. Lead with
the most common. "This plugin must be explicitly enabled" is a common
first bullet.

**No callbacks / functions.** Chart.js options accept functions
(`ticks.callback`, etc.) in the runtime API, but the HTTP/CLI input is
JSON. Mention when a plugin can't be fully expressed in JSON.

**Avoid unnecessary mentions of chartjs2img.** The doc is meant to
teach Chart.js config, not chartjs2img internals. Keep plugin docs
transferable.

## Verify

```bash
# 1. Type check
bun run typecheck

# 2. Print and eyeball
bun run cli -- llm | less

# 3. Grep for your new section
bun run cli -- llm | grep -A 20 "Example plugin"

# 4. Check total length (a reasonable doc is ~30-200 lines per plugin)
bun run cli -- llm | wc -l
```

## What NOT to put here

- **Release notes / changelog.** This is evergreen reference, not a history.
- **Server operations.** Env vars, Docker config, etc. belong in the [User Guide](../guide/).
- **Claude-specific instructions.** Agent Skills files (SKILL.md in `plugins/chartjs2img/skills/*`) are the right home for those — a context7 / Claude-only audience. `chartjs2img llm` is host-agnostic.

See the **Phase 2-B** section of PLAN.md for the upcoming
auto-generation of `docs/public/llms-full.txt` that will concatenate
the LLM docs with the guide pages.

---

<!-- source: docs/en/developer/adding-plugin.md -->
<!-- route: /en/developer/adding-plugin -->

# Adding a Chart.js plugin

You want to bundle another Chart.js ecosystem plugin (a new chart type,
a new decorator) so users can reference it in their config without
extra setup.

## The three-file change

### 1. Add it to `template.ts`

In `src/template.ts`, extend the `LIBS` object:

```ts
export const LIBS = {
  // ...existing entries...
  myNewPlugin: {
    pkg: 'chartjs-chart-mynew',      // npm package name
    version: '1.2.3',                 // pin the exact version
    file: 'dist/chartjs-chart-mynew.min.js', // UMD build path
  },
} as const
```

`Object.values(LIBS).map(cdnUrl)` in the template automatically emits a
`<script src="…">` tag. Nothing else needs editing here.

If the plugin **does not auto-register** with Chart.js, also add a line
inside the template's IIFE:

```ts
// In the template IIFE (same file)
if (window.ChartMyNew) {
  Chart.register(ChartMyNew);
}
```

Most community plugins auto-register. Only add this line if your plugin
docs explicitly say `Chart.register(…)` is required.

### 2. Add an LLM doc snippet

Create `src/llm-docs/plugin-mynew.ts` (or `chart-mynew.ts` for a chart
type):

```ts
export const doc = `
## My New Plugin (chartjs-chart-mynew)

Enables \`chart.type: "mynew"\`. Use for <what it visualizes>.

### Options

| Option                  | Type   | Default | Description                |
| ----------------------- | ------ | ------- | -------------------------- |
| \`options.plugins.mynew.foo\` | string | \`"bar"\` | ...                   |

### Example

\`\`\`json
{
  "type": "mynew",
  "data": { ... }
}
\`\`\`
`
```

Then register it in `src/llm-docs/index.ts`:

```ts
import { doc as chartMyNew } from './chart-mynew'

const docs = [
  // ...existing...
  chartMyNew,
]
```

See [Adding LLM docs](./adding-llm-doc) for the full template and
formatting conventions.

### 3. Add an example

In `src/examples.ts`, append a new entry to `EXAMPLES`:

```ts
{
  title: 'My New Chart',
  config: {
    type: 'mynew',
    data: {
      // ...realistic sample data...
    },
    options: {
      plugins: {
        title: { display: true, text: 'My New Chart example' }
      }
    }
  },
  width: 800,
  height: 600,
},
```

The new entry shows up automatically in:

- `chartjs2img examples -o ./out` output directory
- `GET /examples` gallery page

## Verify

```bash
# 1. Type check
bun run typecheck

# 2. Render the new example alone
bun run cli -- render < <(jq '.[-1].config' <(cat src/examples.ts | ...)) -o /tmp/new.png
# Or simpler: run the examples CLI and look at the last file
bun run cli -- examples -o /tmp/out
ls /tmp/out | tail

# 3. Make sure chartjs2img llm shows your new section
bun run cli -- llm | grep -A 5 "My New Plugin"

# 4. Run the HTTP server and render via curl
bun run dev &
curl -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{"chart":{"type":"mynew","data":{...}}}' \
  -o /tmp/mynew.png
open /tmp/mynew.png
```

If the render comes back blank or with `X-Chart-Messages: [{"level":"error",…}]`,
the plugin probably isn't registering. Check:

1. Is `Chart.register(…)` needed for this plugin?
2. Is the UMD global name right (the `window.ChartMyNew` in step 1)?
3. Does the plugin expect peer deps that aren't in `LIBS`?

## Bump the version

If this is a new feature (new chart type, new plugin), bump the minor
version in `package.json`. Keep the patch version for bug-only changes
and maintenance.

The `version.ts` re-export propagates automatically to
`chartjs2img --version`, the `X-Powered-By` header, and the `/health`
payload.

## Don't forget docs

- [Bundled plugins](../guide/plugins) user-facing table — add the new row.
- `README.md` plugin tables.

These are currently hand-maintained. See PLAN.md Phase 2-B for the
future plan to generate the llms-full bundle automatically from
`src/llm-docs/`.

---

<!-- source: docs/en/developer/architecture.md -->
<!-- route: /en/developer/architecture -->

# Architecture

The single request path — HTTP intake → cached or fresh render → image
back — is where most of the interesting logic lives.

## Full flow

<img src="/diagrams/request-flow.svg" alt="Request pipeline: auth check → compute hash → cache lookup → semaphore acquire → cache re-check → ensure browser → new page → render chart → screenshot → store in cache → close page → release semaphore → response." />

<!-- Source: docs/diagrams/request-flow.gg (regenerated by `bun run docs:diagrams`) -->

Step-by-step, each box corresponds to the following module:

| Step                 | Module                              | Notes                                                   |
| -------------------- | ----------------------------------- | ------------------------------------------------------- |
| Auth check           | `server.ts::checkAuth`              | 401 if `API_KEY` set and missing/wrong                  |
| Compute hash         | `cache.ts::computeHash`             | SHA-256(canonical(request))[0:16]                       |
| Cache lookup         | `cache.ts::getCache`                | Hit returns image with `X-Cache-Hit: true`              |
| Semaphore acquire    | `semaphore.ts::acquire`             | Waits if `active == CONCURRENCY` (default 8)            |
| Cache re-check       | `cache.ts::getCache` (again)        | A racing request may have finished while we waited      |
| Ensure browser       | `renderer.ts::ensureBrowser`        | Launches puppeteer if not already running               |
| New page             | `b.newPage()` + `schedulePageCleanup` | Safety-net timer force-closes the tab if we leak it    |
| Render chart         | `template.ts::buildHtml` + `page.goto(dataUrl)` | Waits for `window.__chartRendered === true`; collects `window.__chartMessages` |
| Screenshot           | `container.screenshot({ type, quality })`      | Buffer with PNG/JPEG bytes                              |
| Store in cache       | `cache.ts::setCache`                | Evicts oldest if at `CACHE_MAX_ENTRIES`                 |
| Close page           | `clearPageCleanup` + `page.close()` | Releases the browser tab                                |
| Release semaphore    | `semaphore.ts::release`             | Wakes next queued render, if any                        |

The response carries the image plus `X-Cache-*` headers and
`X-Chart-Messages` if Chart.js emitted any warnings.

## Key design choices

### The cache is deliberately coarse

`computeHash` canonicalizes by JSON-stringifying a stable object shape
— `{chart, width, height, devicePixelRatio, backgroundColor, format, quality}`.
That means:

- Different key ordering in `chart` **does not** affect the hash
  (JSON.stringify doesn't sort keys, but the caller submitting the
  same logical JSON object will almost always serialize it the same
  way; in practice this is good enough).
- Any change in dataset values, however small, produces a different
  hash.

For pathological hash churn, disable the cache (`CACHE_MAX_ENTRIES=0`).

### The semaphore is independent of the cache

A cache hit **does not** acquire the semaphore — we return the cached
buffer immediately. This keeps repeated identical requests from
consuming browser tabs.

### One browser, many pages

`browser` is a module-level singleton. Each render gets its own tab
(`b.newPage()`). On `browser.on('disconnected')` we null the reference
so the next request re-launches. Tabs are time-bound: if a render
exceeds `PAGE_TIMEOUT_SECONDS`, the cleanup timer force-closes the tab
— no orphaned-page leak on hung renders.

### Chromium runs with `--no-sandbox`

Required for running as root inside Docker (without it, Chromium
refuses to start). If you're running chartjs2img outside a container
as root, you already have bigger problems.

### The HTML template is static

`template.ts::buildHtml` produces a single HTML document containing
every plugin's CDN `<script>` tag, inline CSS, and an IIFE that:

1. Registers plugins that don't auto-register (datalabels, chartjs-chart-geo).
2. Forces animations OFF (so `page.screenshot` captures a stable frame).
3. Wraps `console.warn` / `console.error` to push into `window.__chartMessages`.
4. Creates the `Chart` instance inside try/catch; stores errors on `window.__chartError`.
5. Sets `window.__chartRendered = true` so the renderer knows to screenshot.

This template is what makes "render any Chart.js config" tractable — a
single page init covers every chart type and every plugin we bundle.

### Plugins are CDN-loaded at page init

We do **not** bundle Chart.js plugins into the Node-side JavaScript.
They're fetched from jsdelivr inside Chromium on every page load. That
has two implications:

- First render after a browser cold-start is slower (network round-trips).
- Offline operation requires a local mirror (nginx serving the same
  paths, or Puppeteer's request interception pointing at a cache dir).

Upside: upgrading a plugin is a one-line change in
[template.ts](./modules#template-ts) with no rebuild.

## What isn't in the flow

- **No database.** The cache is in-memory; restarts lose it.
- **No authentication state.** Every request carries the key or doesn't.
- **No WebSocket / SSE.** Just HTTP 1.1 request/response.
- **No multi-process rendering.** Scale horizontally by running multiple instances behind a load balancer. The cache isn't shared between instances (by design — a CDN is the right layer for that).

## Concurrency tuning knobs

| Env var                  | Default | What changes                                                     |
| ------------------------ | ------- | ---------------------------------------------------------------- |
| `CONCURRENCY`            | `8`     | Max semaphore slots — i.e., simultaneous browser tabs             |
| `PAGE_TIMEOUT_SECONDS`   | `60`    | How long a single render can run before the tab is force-killed  |
| `CACHE_MAX_ENTRIES`      | `1000`  | LRU capacity                                                      |
| `CACHE_TTL_SECONDS`      | `3600`  | Per-entry TTL                                                     |

See [Env vars (HTTP server)](../guide/http/env-vars) and
[Env vars (CLI)](../guide/cli/env-vars) for the user-facing docs.

---

<!-- source: docs/en/developer/error-handling.md -->
<!-- route: /en/developer/error-handling -->

# Error handling

chartjs2img deals with three kinds of failure. Knowing which is which
— and how each surfaces — saves a lot of debugging time.

## 1. Server errors (4xx / 5xx HTTP, non-zero CLI exit)

These are **the request itself is broken**. Examples:

| Scenario                             | HTTP status | CLI exit |
| ------------------------------------ | ----------- | -------- |
| Missing API key when one is required | `401`       | *(not applicable — CLI has no auth)* |
| `POST /render` without `chart`       | `500`       | 1        |
| GET `/render` without `chart=` param | `400`       | *(not applicable)* |
| Chromium can't launch (missing binary)| `500`      | 1        |
| Chromium crashed mid-render          | `500`       | 1        |

Handled in `server.ts::handleRequest` (try/catch around the render) and
`cli.ts::cliRender` (exits on `JSON.parse` failure; lets renderer throw
propagate).

## 2. Chart.js rendering errors (image still returned)

These are **the config itself is weird** but the browser didn't crash.
Examples: typo in `chart.type`, missing dataset field, scale config
that Chart.js can't parse.

chartjs2img's contract here:

- **The render still completes.** The image is returned — it may be blank or partial.
- **Exit code is `0`** (CLI) / HTTP status is `200`.
- **Messages surface** via:
  - HTTP → `X-Chart-Messages: [{"level":"error","message":"…"}, …]` header
  - CLI → `[chart ERROR] <message>` / `[chart WARN] <message>` on stderr

This is on purpose: LLM agents can introspect messages, fix the config,
and retry without having to guess why an image is empty. See the user-
facing [Error feedback (HTTP)](../guide/http/error-feedback) or
[Error feedback (CLI)](../guide/cli/error-feedback) page for the caller
experience.

### How messages are captured

`renderer.ts` wires two channels:

```ts
page.on('console', msg => { /* capture error/warning console calls */ })
page.on('pageerror', err => { /* capture uncaught exceptions */ })
```

Inside the browser (`template.ts`), an IIFE wraps `console.warn` /
`console.error` to also push into `window.__chartMessages`, and the
`try { new Chart(…) }` catches a thrown construction error into
`window.__chartError`. After `waitForFunction('window.__chartRendered === true')`
the Node side reads both and merges (deduping).

Why the belt + suspenders? Some Chart.js errors fire before the Node-
side `console` listener attaches; the in-browser interception catches
those. Conversely, some Chromium-level messages (resource load
failures, CORS) only show up in the Node-side listener.

## 3. System errors (Chromium won't launch, disk full, OOM)

Bubble out as exceptions. HTTP server returns `500` with the message in
the JSON body; CLI exits non-zero with the message on stderr. There's
no attempt to retry — systemd or your orchestrator should restart the
service if Chromium dies repeatedly.

## Related Chart.js behavior

Chart.js has a policy we deliberately mirror: **a bad option value is
usually a warning, not an exception.** It will do its best to render
and log to the console. Our pipeline preserves that — if you want
"error the request on any warning," handle it in your client:

```ts
const resp = await fetch('/render', { method: 'POST', body: ... })
const xChartMessages = resp.headers.get('X-Chart-Messages')
if (xChartMessages) {
  const messages = JSON.parse(xChartMessages)
  if (messages.some(m => m.level === 'error')) {
    throw new Error('Chart errored: ' + messages[0].message)
  }
}
```

## DataError vs System error — borrowing from lightfile6-jpeg

The `lightfile6-jpeg` package (sibling project) makes a distinction
between **DataError** (the input data is bad — not a system fault) and
system errors (disk, memory). chartjs2img effectively does the same,
but implicitly: Chart.js reporting a console error is the data error;
an exception in our own code is the system error.

If chartjs2img ever grows a TypeScript SDK of its own, the boundary
will likely be:

- Throw `SystemError` when the renderer can't start / crashed / timed out.
- Return `RenderResult { messages: [...] }` when the render completed but
  Chart.js reported something.

Today, "messages" on the result IS the data-error channel. Don't throw
for a bad chart config.

## Logging policy

- `console.log` — only for startup banner and informational progress (one-time events).
- `console.warn` — unusual but expected (forced page close after timeout).
- `console.error` — unexpected failures (browser disconnect, render exception).

We do not log per-request success — that's the caller's job. Runtime
logging of tens of thousands of renders would be noise.

## Timeouts

| Timer                         | Value                         | What happens                                         |
| ----------------------------- | ----------------------------- | ---------------------------------------------------- |
| `page.goto` + `waitForFunction` | 30 seconds (hardcoded)       | Throws; request returns `500` / CLI exits non-zero.  |
| `PAGE_TIMEOUT_SECONDS`        | default `60`, env-configurable | Force-closes the tab. If the render was mid-flight, the caller sees a 500/exception too. |
| Browser launch                | puppeteer default ~30 seconds | Same as above.                                       |

There's **no overall request timeout** on the HTTP server — clients
can (and should) set their own client-side timeout.

---

<!-- source: docs/en/developer/library-api.md -->
<!-- route: /en/developer/library-api -->

# Library API (TypeScript)

chartjs2img ships a small **TypeScript / Node library** surface
alongside the CLI and HTTP server. The CLI and server are thin
wrappers around this library — rendering behavior is identical
regardless of which entry point you use.

## When to use the library directly

- You're already inside a Bun / Node service and want to render
  Chart.js without the IPC overhead of spawning a CLI or making an
  HTTP call to a sidecar.
- You need to customize request validation, caching, or error
  handling in ways the HTTP server doesn't expose as config.
- You want to render at build time in a script (e.g., generate
  dashboard snapshots for an email campaign).

If you don't need any of the above, the HTTP or CLI entry points are
simpler to operate. See [HTTP server](/en/guide/http/) and
[CLI rendering](/en/guide/cli/).

## Install

```bash
# from npm (once published)
bun add chartjs2img
# or
npm install chartjs2img

# from source (dev)
git clone https://github.com/ideamans/chartjs2img
cd chartjs2img
bun install
bun run build:lib   # produces ./dist/*.js + *.d.ts
```

Chromium is **not** a dependency of the npm package. The renderer
downloads Chrome for Testing to the user cache on first run
(macOS/Windows/Linux-x64) or reads `CHROMIUM_PATH` on linux-arm64.

## Quick start

```ts
import { renderChart, closeBrowser } from 'chartjs2img'

const { buffer, hash, cached, messages } = await renderChart({
  chart: {
    type: 'bar',
    data: {
      labels: ['Jan', 'Feb', 'Mar'],
      datasets: [{ data: [12, 19, 3] }],
    },
  },
  width: 800,
  height: 600,
  format: 'png',
})

await Bun.write('chart.png', buffer)         // or fs.writeFileSync for Node
console.log('rendered', buffer.length, 'bytes — cached?', cached)
if (messages.length) console.warn(messages)   // Chart.js warnings/errors

// When your process is about to exit:
await closeBrowser()
```

`renderChart` is async and browser-backed. The first call launches a
Chromium instance (lazy, shared across subsequent calls). Concurrency
is bounded by `CONCURRENCY` (default 8); additional calls queue.

## Exports

All exports are available via the package root:

```ts
import {
  renderChart,
  closeBrowser,
  rendererStats,
  computeHash,
  VERSION,
  NAME,
  BUNDLED_LIBS,
  type RenderOptions,
  type RenderResult,
  type ConsoleMessage,
} from 'chartjs2img'
```

### `renderChart(options: RenderOptions): Promise<RenderResult>`

The single render entry point. Internally:

1. computes a SHA-256 hash over the canonicalized options;
2. returns the cached PNG if one exists (`cached: true`);
3. otherwise acquires a semaphore slot, launches (or reuses) Chromium,
   opens a fresh page, injects the HTML template + Chart.js + 12 plugins,
   screenshots the canvas, caches the result, and returns.

### `closeBrowser(): Promise<void>`

Close the shared Chromium instance and any orphaned pages. Call on
process shutdown. Idempotent.

### `rendererStats()`

```ts
{
  browserConnected: boolean
  concurrency: { max: number; active: number; pending: number }
  activePages: number
  pageTimeoutSeconds: number
}
```

Use it to wire your own `/health` endpoint or a Prometheus exporter.

### `computeHash(options: RenderOptions): string`

Deterministic 16-char hex SHA-256 prefix over the canonical option
shape. Useful when you want to deduplicate or pre-check a cache
**before** hitting `renderChart`.

```ts
const hash = computeHash(options)
if (await redis.exists(`cj:${hash}`)) return redis.get(`cj:${hash}`)
const { buffer } = await renderChart(options)
await redis.set(`cj:${hash}`, buffer, 'EX', 3600)
```

### `VERSION` / `NAME`

Runtime constants matching `package.json`. Surface them in health
probes / log headers.

### `BUNDLED_LIBS`

Read-only table of the Chart.js + plugin versions baked into the
rendering page:

```ts
console.log(BUNDLED_LIBS.chartjs.version)       // "4.4.9"
console.log(BUNDLED_LIBS.datalabels.version)    // "2.2.0"
```

Useful when surfacing "what version of Chart.js is bundled?" to your
own users without parsing `chartjs2img llm`.

## Types

### `RenderOptions`

```ts
interface RenderOptions {
  /** Chart.js configuration object (type, data, options, plugins) */
  chart: Record<string, unknown>
  /** Canvas width in pixels (default: 800) */
  width?: number
  /** Canvas height in pixels (default: 600) */
  height?: number
  /** Device pixel ratio (default: 2). Multiplies output pixels, not chart detail. */
  devicePixelRatio?: number
  /** CSS background color, or "transparent" (default: "white") */
  backgroundColor?: string
  /** Output format (default: "png") */
  format?: 'png' | 'jpeg' | 'webp'
  /** JPEG/WebP quality 0-100 (default: 90) */
  quality?: number
}
```

### `RenderResult`

```ts
interface RenderResult {
  /** Image bytes in the requested format */
  buffer: Buffer
  /** SHA-256 prefix (16 hex chars) that keys the built-in cache */
  hash: string
  /** MIME type matching `format` */
  contentType: string
  /** true if served from the in-process cache */
  cached: boolean
  /** Chart.js console messages captured during the render */
  messages: ConsoleMessage[]
}
```

### `ConsoleMessage`

```ts
interface ConsoleMessage {
  level: 'error' | 'warn' | 'info' | 'log'
  message: string
}
```

In practice only `error` and `warn` occur. Empty array means a clean
render.

## Environment variables

The library reads the same env vars as the CLI / server:

| Variable                 | Default | Effect                                                             |
| ------------------------ | ------- | ------------------------------------------------------------------ |
| `CONCURRENCY`            | `8`     | Max concurrent renders (semaphore capacity)                        |
| `CACHE_MAX_ENTRIES`      | `1000`  | In-memory LRU cache size                                           |
| `CACHE_TTL_SECONDS`      | `3600`  | Cache entry lifetime                                               |
| `PAGE_TIMEOUT_SECONDS`   | `60`    | Force-close orphaned tabs after this many seconds                  |
| `CHROMIUM_PATH`          | *(none)*| Explicit path to a Chromium binary (skips the detection chain)     |

Set them before `renderChart` is first called. Runtime reconfiguration
is not supported — restart the process to change concurrency.

## Error handling

The library does **not** throw on Chart.js errors. A config with a
typo renders a blank/partial image and returns it with
`messages: [{ level: 'error', message: '...' }]`. Always inspect
`messages` before declaring success:

```ts
const result = await renderChart(options)
if (result.messages.some((m) => m.level === 'error')) {
  throw new ChartConfigError(result.messages)
}
```

`renderChart` **does** throw for:

- Chromium launch failures (missing binary on linux-arm64, OOM, etc.)
- Page timeout (page exceeded `PAGE_TIMEOUT_SECONDS`)
- Invalid `chart` field (missing entirely — the server wrapper also
  catches this)

See [Error handling](./error-handling) for the full taxonomy.

## Example: build-time dashboard snapshots

```ts
// scripts/snapshot-dashboards.ts
import { readdirSync, readFileSync } from 'fs'
import { join } from 'path'
import { renderChart, closeBrowser } from 'chartjs2img'

const CONFIGS = readdirSync('./dashboards').filter((f) => f.endsWith('.json'))

for (const file of CONFIGS) {
  const chart = JSON.parse(readFileSync(join('./dashboards', file), 'utf8'))
  const result = await renderChart({ chart, width: 1200, height: 600 })
  const out = file.replace(/\.json$/, '.png')
  await Bun.write(join('./snapshots', out), result.buffer)
  if (result.messages.length) {
    console.warn(file, result.messages)
  }
}

await closeBrowser()
```

Run with `bun run scripts/snapshot-dashboards.ts`. The shared
Chromium instance stays up for the whole loop, so 100 dashboards
render in roughly one browser launch + 100 × per-chart time.

## Example: Express handler

```ts
import express from 'express'
import { renderChart, closeBrowser } from 'chartjs2img'

const app = express()
app.use(express.json({ limit: '1mb' }))

app.post('/chart.png', async (req, res) => {
  try {
    const result = await renderChart({
      chart: req.body.chart,
      width: req.body.width,
      height: req.body.height,
      format: 'png',
    })
    if (result.messages.length) {
      res.setHeader('X-Chart-Messages', JSON.stringify(result.messages))
    }
    res.setHeader('Content-Type', 'image/png')
    res.setHeader('X-Cache-Hit', String(result.cached))
    res.send(result.buffer)
  } catch (err) {
    res.status(500).json({ error: String(err) })
  }
})

process.on('SIGTERM', async () => {
  await closeBrowser()
  process.exit(0)
})

app.listen(3000)
```

## Relationship to the CLI and HTTP server

Both the built-in CLI (`src/index.ts` / `src/cli.ts`) and the built-in
HTTP server (`src/server.ts`) are **thin wrappers** around this same
library:

<img src="/diagrams/library-surface.svg" alt="CLI binary and HTTP server both import from lib.ts; lib.ts re-exports the renderer plus cache and semaphore, which are internal." />

<!-- Source: docs/diagrams/library-surface.gg (regenerated by `bun run docs:diagrams`) -->

- **`lib.ts`** is the public surface — exports `renderChart`,
  `closeBrowser`, `rendererStats`, `computeHash`, etc. Semver-stable.
- **`renderer.ts`**, **`template.ts`**, **`cache.ts`**, **`semaphore.ts`**
  are implementation details. Not covered by semver — may change between
  minor versions.

If you import from `chartjs2img/*` (anything other than the package
root) you're reaching into implementation — those paths are not
covered by semver. Stick to the symbols listed in [Exports](#exports).

---

<!-- source: docs/en/developer/modules.md -->
<!-- route: /en/developer/modules -->

# Modules

Short table of every source module, what it exports, and who imports
it. Use this to figure out where to open the editor.

## `src/index.ts` — CLI entry point

The binary's `main()`. Parses `argv`, prints the usage banner, and
dispatches to one of `serve`, `render`, `examples`, `llm`, `help`, or
`version`. No business logic — just argv → function call.

**Exports**: none (script entry).
**Imports**: `server.ts`, `cli.ts`, `version.ts`, `llm-docs/index.ts`.

## `src/server.ts` — HTTP server

`startServer()` spins up `Bun.serve()` on the configured host + port,
routes requests to `/render`, `/cache/:hash`, `/health`, `/examples`,
or `404`. Handles auth with `checkAuth()`.

**Exports**: `startServer(config)`, `ServerConfig` interface.
**Imports**: `renderer.ts`, `cache.ts`, `examples.ts`, `version.ts`, `template.ts` (type only).

## `src/cli.ts` — CLI `render` + `examples`

- `cliRender()` reads JSON from stdin or a file, calls `renderChart()`,
  writes the image to stdout or a file, and echoes Chart.js messages to
  stderr.
- `cliExamples()` iterates `EXAMPLES`, calls `renderChart()` for each,
  writes `NN-<slug>.{png,jpg}` + `NN-<slug>.json` to `--outdir`.

**Exports**: `cliRender`, `cliExamples`, and their arg interfaces.
**Imports**: `renderer.ts`, `examples.ts`, `template.ts` (type only).

## `src/renderer.ts` — Chromium pipeline

The rendering core. Manages:

- **Chromium discovery & auto-install** — `findChromiumExecutable()`,
  `downloadChromeForTesting()`, `ensureChromiumInstalled()`.
- **Browser lifecycle** — `ensureBrowser()`, `launchBrowser()`,
  `closeBrowser()`. Single module-level `browser` ref; launches
  lazily, auto-clears on `disconnected`.
- **Page lifecycle** — `schedulePageCleanup()` arms a `setTimeout`
  that force-closes the tab after `PAGE_TIMEOUT_SECONDS`.
- **Render entry** — `renderChart()` is the single export the rest of
  the codebase calls. It handles hash compute, cache get/set, semaphore
  acquire/release, HTML build, `page.goto(data:…)`, console capture,
  screenshot.
- **Stats** — `rendererStats()` for `/health`.

**Exports**: `renderChart`, `closeBrowser`, `rendererStats`,
`ConsoleMessage`, `RenderResult`.
**Imports**: `puppeteer-core`, `template.ts`, `semaphore.ts`, `cache.ts`.

## `src/template.ts` — Browser-side HTML

Static HTML string containing every CDN `<script>` for Chart.js + 12
plugins, and an IIFE that:

- registers non-auto-registering plugins (datalabels, chartjs-chart-geo);
- forces animations OFF;
- wraps `console.warn` / `console.error` into `window.__chartMessages`;
- instantiates `Chart` inside try/catch;
- sets `window.__chartRendered = true` when done.

Edit this file if you add/remove/upgrade a plugin. See
[Adding a Chart.js plugin](./adding-plugin).

**Exports**: `buildHtml(options)`, `RenderOptions` interface, `LIBS` const.
**Imports**: none.

## `src/cache.ts` — In-memory cache

`Map<string, CacheEntry>` with LRU-ish eviction (oldest key evicted
when `size >= MAX_ENTRIES`) and TTL (lazy expiry on `getCache`).
`computeHash()` hashes `{chart, width, height, devicePixelRatio,
backgroundColor, format, quality}` via SHA-256 and takes the first 16
hex chars.

**Exports**: `computeHash`, `getCache`, `setCache`, `cacheStats`.
**Imports**: `crypto` (Node built-in), `template.ts` (type only).

## `src/semaphore.ts` — Concurrency control

30-line async semaphore. `acquire()` returns immediately if under
capacity, otherwise pushes a resolver into a FIFO queue. `release()`
pops the head of the queue and resolves.

**Exports**: `Semaphore` class.
**Imports**: none.

## `src/examples.ts` — Built-in examples

`EXAMPLES` is an array of `{ title, config, width?, height? }` used
by:

- The CLI's `examples` subcommand (writes PNG + JSON files)
- The HTTP `/examples` gallery (embeds `<img src="/render?chart=…">` tags)

Add new examples here; they show up in both the CLI output directory
and the gallery page automatically.

**Exports**: `EXAMPLES`, `buildExamplesHtml()`.
**Imports**: none.

## `src/version.ts` — Version constant

Single-line module re-exporting `VERSION` from `package.json` (via
Bun's `await import(..., { type: 'json' })`, so compile-time inlined
by `bun build`).

**Exports**: `VERSION`.
**Imports**: `package.json`.

## `src/llm-docs/` — LLM reference bundle

One TS file per Chart.js module. Each file exports `doc: string` — a
multi-line Markdown snippet. `llm-docs/index.ts` aggregates them into
`getLlmDocs()` which `chartjs2img llm` prints.

See [Adding LLM docs](./adding-llm-doc).

### The files

| Module file                  | Covers                                                       |
| ---------------------------- | ------------------------------------------------------------ |
| `usage.ts`                   | How to invoke chartjs2img; JSON vs HTTP distinction          |
| `chartjs-core.ts`            | Chart.js core: types, datasets, scales, title/legend/tooltip |
| `plugin-datalabels.ts`       | chartjs-plugin-datalabels options                            |
| `plugin-annotation.ts`       | chartjs-plugin-annotation options                            |
| `plugin-zoom.ts`             | chartjs-plugin-zoom options                                  |
| `plugin-gradient.ts`         | chartjs-plugin-gradient options                              |
| `chart-matrix.ts`            | matrix / heatmap chart type                                  |
| `chart-sankey.ts`            | sankey chart type                                            |
| `chart-treemap.ts`           | treemap chart type                                           |
| `chart-wordcloud.ts`         | wordcloud chart type                                         |
| `chart-geo.ts`               | choropleth + bubbleMap chart types                           |
| `chart-graph.ts`             | graph / forceDirectedGraph / dendrogram / tree chart types   |
| `chart-venn.ts`              | venn + euler chart types                                     |
| `adapter-dayjs.ts`           | dayjs date adapter for time-series axes                      |

## Dependency graph (roughly)

<img src="/diagrams/module-deps.svg" alt="Module dependency graph: index.ts dispatches to server.ts and cli.ts; both end in renderer.ts which depends on template.ts, cache.ts, and semaphore.ts. cli.ts also imports examples.ts. index.ts separately wires llm-docs/index.ts to many llm-docs/*.ts modules for the `llm` subcommand." />

<!-- Source: docs/diagrams/module-deps.gg (regenerated by `bun run docs:diagrams`) -->

No cyclic deps. Nothing imports `server.ts` or `cli.ts` except
`index.ts` — keeping entry points thin.

---

<!-- source: docs/en/developer/types.md -->
<!-- route: /en/developer/types -->

# Types & HTTP schema

If you're integrating chartjs2img from code, these are the exact types
and payloads you'll deal with.

## `RenderOptions` (template.ts)

The canonical "render a chart" input. Used by both the CLI (directly)
and the HTTP server (as the inner shape after unwrapping).

```ts
interface RenderOptions {
  /** Chart.js configuration object */
  chart: Record<string, unknown>
  /** Canvas width in pixels (default: 800) */
  width?: number
  /** Canvas height in pixels (default: 600) */
  height?: number
  /** Device pixel ratio (default: 2) */
  devicePixelRatio?: number
  /** Background color, CSS syntax (default: 'white') */
  backgroundColor?: string
  /** Output format: png, jpeg, webp (default: 'png') */
  format?: 'png' | 'jpeg' | 'webp'
  /** JPEG/WebP quality 0-100 (default: 90) */
  quality?: number
}
```

## `RenderResult` (renderer.ts)

What `renderChart()` returns.

```ts
interface RenderResult {
  /** Image bytes in the requested format */
  buffer: Buffer
  /** SHA-256 prefix (16 hex chars) that keys the cache */
  hash: string
  /** MIME type matching `format` (image/png, image/jpeg, image/webp) */
  contentType: string
  /** true if served from cache, false if freshly rendered */
  cached: boolean
  /** Chart.js console messages captured during render */
  messages: ConsoleMessage[]
}

interface ConsoleMessage {
  level: 'error' | 'warn' | 'info' | 'log'
  message: string
}
```

Only `error` and `warn` actually appear in practice; `info` / `log` are
reserved for future use.

## `ServerConfig` (server.ts)

```ts
interface ServerConfig {
  port: number
  host: string
  apiKey?: string
}
```

## HTTP body — `POST /render`

**Outer** wrapper (server-side) — different from CLI which expects the
chart config directly:

```jsonc
{
  "chart": { /* RenderOptions.chart */ },
  "width": 800,
  "height": 600,
  "devicePixelRatio": 2,
  "backgroundColor": "white",
  "format": "png",
  "quality": 90
}
```

`chart` is the only required field. The server validates only its
presence — Chart.js itself validates the rest and reports errors via
`X-Chart-Messages`.

## HTTP query — `GET /render`

Same semantic content, encoded as query params:

```
GET /render?chart=<URL-encoded JSON>
          &width=800
          &height=600
          &devicePixelRatio=2
          &backgroundColor=white
          &format=png
          &quality=90
```

Only `chart` is required; other params are optional. Query params
coerce to `number` where applicable (`width`, `height`, `quality`).

## HTTP response — successful render

```
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: <N>
X-Cache-Hash: <16 hex chars>
X-Cache-Url: http://host:port/cache/<hash>
X-Cache-Hit: true|false
X-Chart-Messages: [{"level":"error","message":"…"}, …]   ← only when non-empty
X-Powered-By: chartjs2img/<version>

<image bytes>
```

## HTTP response — `/health`

```ts
type HealthResponse = {
  status: 'ok'
  version: string
  renderer: {
    browserConnected: boolean
    concurrency: { max: number; active: number; pending: number }
    activePages: number
    pageTimeoutSeconds: number
  }
  cache: {
    size: number
    maxEntries: number
    ttlSeconds: number
  }
}
```

## HTTP response — `/cache/:hash`

On hit:

```
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: <N>
Cache-Control: public, max-age=3600

<image bytes>
```

On miss (expired or never rendered):

```
HTTP/1.1 404 Not Found
Content-Type: application/json

{ "error": "Cache miss - image not found or expired" }
```

## HTTP error responses

| Status                  | Body JSON                                      | When                                                     |
| ----------------------- | ---------------------------------------------- | -------------------------------------------------------- |
| `400 Bad Request`       | `{ "error": "Missing chart parameter" }`       | GET `/render` without `chart=` query                     |
| `401 Unauthorized`      | `{ "error": "Unauthorized" }`                  | `API_KEY` set and request missing/wrong key              |
| `404 Not Found`         | `{ "error": "Not found" }` / cache miss msg    | Unknown path, or cache hash with no entry                |
| `405 Method Not Allowed`| `{ "error": "Method not allowed" }`            | `/render` with method other than GET/POST                |
| `500 Internal Server Error`| `{ "error": "<exception message>" }`        | Unhandled exception inside `handleRequest()`             |

## CLI argument shapes (cli.ts)

```ts
interface CliRenderArgs {
  input?: string           // path, or "-" for stdin, or undefined → stdin
  output?: string          // path, or "-" for stdout, or undefined → stdout
  width?: number
  height?: number
  devicePixelRatio?: number
  backgroundColor?: string
  format?: 'png' | 'jpeg' | 'webp'
  quality?: number
}

interface CliExamplesArgs {
  outdir: string           // required
  format?: 'png' | 'jpeg'
  quality?: number
}
```

The CLI's JSON input (stdin or file) is the **Chart.js config directly** —
no outer `chart` wrapper. That's the one asymmetry between CLI and
HTTP: HTTP wraps, CLI doesn't. See [Adding a Chart.js plugin](./adding-plugin)
for why.

---

<!-- source: docs/en/gallery/index.md -->
<!-- route: /en/gallery -->

# Gallery

Example charts, rendered by chartjs2img itself. Every image below is
regenerated from `src/examples.ts` via `bun run docs:examples`, so the
images you see here are exactly what the live service produces.

Each example shows the rendered PNG, the Chart.js configuration JSON,
and a ready-to-paste CLI / HTTP command — flip tabs to switch. Copy,
tweak, send to `/render`.

## Categories

| Category                                   | Charts                                                                 |
| ------------------------------------------ | ---------------------------------------------------------------------- |
| [Basic chart types](./basic)               | bar, line, pie, doughnut, radar, polarArea, scatter, bubble, horizontal bar |
| [Composite charts](./composite)            | filled area, stacked bar, mixed bar + line                             |
| [Axes & chart options](./axes-options)     | dual axis, log scale, negative values, rotated ticks, custom grid styling |
| [Labels & annotation](./decorations)       | data labels, annotation (line / box / point), gradient fills, zoom framing, time-series axis |
| [Exotic plugins](./exotic)                 | treemap, matrix / heatmap, sankey, wordcloud, venn / euler, force-directed graph, tidy tree, choropleth skeleton |
| [Sizing](./sizing)                         | small 400×300 and wide 1200×400 canvases                               |
| [Internationalization](./i18n)             | Japanese labels with Noto Sans CJK                                     |

## How these are produced

```bash
# One-shot renders everything into docs/public/examples/
bun run docs:examples

# Same renders show up in the built-in live gallery
bun run dev     # then open http://localhost:3000/examples
```

The `/examples` endpoint on a running server produces the same images
from the same source. If you want them embedded in your own site, the
HTTP API (`GET /render?chart=...`) or the cache URL pattern
(`/cache/:hash`) is usually easier than scraping the docs site.

## Adding your own

See [Developer Guide → Adding a Chart.js plugin](/en/developer/adding-plugin)
for the full recipe. In short: append an entry to `EXAMPLES` in
`src/examples.ts`, then `bun run docs:examples`. The new chart shows up
in both the CLI output directory and the gallery.

---

<!-- source: docs/en/gallery/axes-options.md -->
<!-- route: /en/gallery/axes-options -->

# Axes & chart options

A `type` alone rarely gets you a production-ready chart. These
examples show the `options` and `scales` knobs that do most of the
visual work — secondary Y axes, log scale, negative-value layout,
rotated tick labels, and custom grid / tick colors. Each renders
from a plain JSON config.

## Dual axis (bar + line, two Y axes)

Mix units by giving each dataset its own `yAxisID`, then define two
linear scales — one on the left, one on the right — in
`options.scales`. The line is drawn on top by lowering its `order`.

<Example name="dual-axis-sales-vs-conversion-rate" http />

Key pieces:

- `datasets[i].yAxisID` — string that matches a scale ID.
- `scales.<id>.position` — `"left"` / `"right"`.
- `scales.<id>.grid.drawOnChartArea: false` — stops the right axis's
  grid lines from doubling up with the left axis's.

## Logarithmic scale

When the Y range spans several orders of magnitude, a linear axis
flattens the early years into nothing. `scales.y.type: "logarithmic"`
turns equal multipliers (×2, ×10) into equal pixel gaps.

<Example name="log-scale-download-growth" http />

Chart.js auto-picks base-10 ticks (`1, 10, 100, …`). Override with
`scales.y.ticks.callback` if you're driving from JS; for
chartjs2img's JSON pipeline, leave it to the defaults.

## Negative values (zero-baseline layout)

When data crosses zero, clamp the scale manually with `suggestedMin`
/ `suggestedMax` and use diverging per-bar colors to show direction.

<Example name="negative-values-profit-loss" http />

A darker `border.color` on the axis helps the zero line pop against
the lighter `grid.color` inside the chart area.

## Rotated tick labels

Long category labels on the X axis overlap at narrow chart widths.
Force them tilted with `ticks.maxRotation` / `minRotation` — set
`autoSkip: false` if you don't want Chart.js to silently drop
labels to make space.

<Example name="rotated-tick-labels" http />

## Custom grid & tick styling

Everything about the axis — gridline color, dash pattern, tick color,
axis border — is tunable per-scale. Good for matching a brand palette
or toning down the default gray to something less assertive.

<Example name="custom-grid-tick-styling" http />

The `tickBorderDash: [4, 4]` pattern on the Y axis gives the dashed
horizontal lines; the solid color on `border.color` draws the axis
line itself.

## Other scale options worth knowing

| Option                     | What it does                                                                  |
| -------------------------- | ----------------------------------------------------------------------------- |
| `scales.<id>.min` / `max`  | Hard-clamp the visible range (ignored data points draw outside the chart area). |
| `scales.<id>.suggestedMin` / `suggestedMax` | Hint only — Chart.js still adjusts to fit the data.             |
| `scales.<id>.beginAtZero`  | Force the linear axis to include 0, useful for bar charts.                    |
| `scales.<id>.reverse`      | Flip the axis direction (common on matrix Y axes).                            |
| `scales.<id>.stacked`      | Stack datasets along this axis (bar / area).                                  |
| `scales.<id>.offset`       | Leave half a tick of padding so dots / bars don't hit the edge.               |
| `scales.<id>.ticks.stepSize` | Force a specific tick spacing.                                              |
| `scales.<id>.ticks.count`  | Request an approximate number of ticks (Chart.js rounds to nice values).      |

See `chartjs2img llm` for the complete list — every scale subtype
(linear, logarithmic, time, category, radialLinear) exposes its own
knobs on top of the shared ones.

---

<!-- source: docs/en/gallery/basic.md -->
<!-- route: /en/gallery/basic -->

# Basic chart types

The nine built-in Chart.js types. Every one of these works out of the
box with `type: "…"` — no plugins required. Switch between the
rendered PNG and the source JSON with the tabs on each example.

## Bar chart

<Example name="bar-chart" http />

## Horizontal bar chart

Same `type: "bar"` with `options.indexAxis: "y"`.

<Example name="horizontal-bar-chart" http />

## Line chart

Multi-dataset with `tension: 0.3` for smooth lines.

<Example name="line-chart" http />

## Pie chart

<Example name="pie-chart" http />

## Doughnut chart

Identical to pie + `chart.type: "doughnut"`.

<Example name="doughnut-chart" http />

## Radar chart

<Example name="radar-chart" http />

## Polar area chart

<Example name="polar-area-chart" http />

## Scatter plot

Datasets take `{x,y}` objects rather than values.

<Example name="scatter-plot" http />

## Bubble chart

Scatter but with radius (`r`) per point.

<Example name="bubble-chart" http />

## Next

- [Composite charts](./composite) — filled area, stacked, mixed-type.
- [Labels & annotation](./decorations) — data labels and threshold lines.
- [Exotic plugins](./exotic) — treemap and beyond.

---

<!-- source: docs/en/gallery/composite.md -->
<!-- route: /en/gallery/composite -->

# Composite charts

Charts where multiple datasets interact visually, or multiple chart
types share an axis.

## Area chart (filled line)

Line chart with `fill: true` fills below the line.

<Example name="area-chart-filled" http />

## Stacked bar chart

Bar chart with `scales.x.stacked: true` and `scales.y.stacked: true`.

<Example name="stacked-bar-chart" http />

## Mixed chart (bar + line)

Use per-dataset `type:` to combine chart types. Parent `type:` is just
the default for datasets without their own.

<Example name="mixed-chart-bar-line" http />

---

<!-- source: docs/en/gallery/decorations.md -->
<!-- route: /en/gallery/decorations -->

# Labels & annotation

Decorator plugins — the chart shape is ordinary, but something is
drawn on top of it (or applied as a fill).

## Bar with data labels (chartjs-plugin-datalabels)

Uses `chartjs-plugin-datalabels`. Note the explicit
`options.plugins.datalabels.display: true` — datalabels is **off by
default** in chartjs2img (opposite of the plugin's own default).

<Example name="bar-with-data-labels" http />

### datalabels options recap

| Option    | Typical values                     | Effect                                    |
| --------- | ---------------------------------- | ----------------------------------------- |
| `display` | `true` / `false` / `"auto"`        | Show labels (required — see above)        |
| `anchor`  | `"start"` / `"center"` / `"end"`   | Where on the element the label is anchored |
| `align`   | `"top"` / `"bottom"` / `"center"` / number (degrees) | Direction from anchor |
| `color`   | CSS color                          | Text color                                |
| `formatter` | function                         | **Not usable over JSON** — see Developer Guide |

## Line with annotation (chartjs-plugin-annotation)

Uses `chartjs-plugin-annotation`. Here a horizontal threshold line.

<Example name="line-with-annotation" http />

### Annotation types you can use

- `"line"` — horizontal / vertical / diagonal line (what's shown above)
- `"box"` — filled rectangle
- `"label"` — standalone text
- `"point"` — small circle
- `"polygon"` — custom shape
- `"ellipse"` — filled ellipse

### Box + point annotations combined

<Example name="annotation-box-point" http />

See the [plugin docs](https://www.chartjs.org/chartjs-plugin-annotation/)
or `chartjs2img llm` for all options.

## Gradient fills (chartjs-plugin-gradient)

Map scale values to colors and the plugin interpolates along an axis —
no manual canvas code required.

<Example name="gradient-fill" http />

Keys in `colors` are **scale values**, not pixel positions — so a
gradient that transitions at `y = 15` stays correct even if the chart
is resized. Works with `line`, `bar`, `radar`, `polarArea`, and any
chart using `backgroundColor` / `borderColor`.

## Zoom framing (chartjs-plugin-zoom)

chartjs2img renders static images, so the interactive pan/zoom of
this plugin doesn't apply — but the plugin's
`options.plugins.zoom.limits` is still useful for clamping the
**initial** visible range of a crowded chart.

```json
{
  "type": "line",
  "data": {
    "labels": ["1","2","3","4","5","6","7","8","9","10","11","12","13","14","15","16","17","18","19","20"],
    "datasets": [{
      "label": "Noisy series",
      "data": [5, 12, 8, 20, 18, 25, 30, 22, 28, 34, 40, 38, 45, 50, 48, 55, 60, 58, 65, 70],
      "borderColor": "#36a2eb",
      "tension": 0.25
    }]
  },
  "options": {
    "plugins": {
      "zoom": {
        "limits": {
          "x": { "min": 4, "max": 14 },
          "y": { "min": 15, "max": 50 }
        }
      }
    },
    "scales": {
      "x": { "min": 4, "max": 14 },
      "y": { "min": 15, "max": 50 }
    }
  }
}
```

For static rendering you typically set `scales.x.min/max` and
`scales.y.min/max` directly; the zoom plugin simply enforces those
bounds globally if downstream code ever needs them.

## Time-series axis (chartjs-adapter-date-fns)

The date-fns adapter is pre-loaded — set `scales.x.type: "time"` to
enable it. Input dates can be ISO strings, millisecond timestamps, or
anything date-fns can parse.

<Example name="time-series-date-fns-adapter" http />

> **Format tokens:** date-fns uses `yyyy` / `d` (not Day.js's `YYYY` /
> `D`). If Chart.js throws `Use \`d\` instead of \`D\``, swap the tokens.

See the [date-fns adapter](https://github.com/chartjs/chartjs-adapter-date-fns)
or `chartjs2img llm` for every `time.*` option.

---

<!-- source: docs/en/gallery/exotic.md -->
<!-- route: /en/gallery/exotic -->

# Exotic plugins

These chart types are **not** part of Chart.js core. Each is brought
in by a dedicated plugin, all bundled with chartjs2img. Every example
below shows the rendered PNG, the JSON config, and a ready-to-run CLI
/ HTTP snippet — flip between tabs to see each.

## Treemap (chartjs-chart-treemap)

Hierarchical blocks, sized by the `tree` values of each node.

<Example name="treemap-chart" http />

## Matrix / heatmap (chartjs-chart-matrix)

Discrete cell grid with per-cell color. JSON can't express a
value-to-color function, so pre-compute one color per cell.

<Example name="matrix-heatmap" http />

## Sankey (chartjs-chart-sankey)

Flow between categorical nodes. `flow` is the width of each band.

<Example name="sankey-flow" http />

## Word cloud (chartjs-chart-wordcloud)

Words come from `data.labels`, font sizes come from `datasets[0].data`.

<Example name="word-cloud" http />

## Venn / Euler (chartjs-chart-venn)

Set overlaps. Use `"type": "venn"` for a standard layout,
`"type": "euler"` when circle sizes and overlaps should be
proportional to values.

<Example name="euler-diagram-3-set" http />

## Force-directed graph (chartjs-chart-graph)

Network layout via physics simulation — no coordinates needed.

<Example name="force-directed-graph" http />

For a **manual-layout** graph instead (explicit `{x,y}` per node), use
`"type": "graph"` and supply coordinates in `data`. The
[plugin docs](https://github.com/sgratzl/chartjs-chart-graph) cover
the full option surface.

## Tidy tree (chartjs-chart-graph)

Hierarchical layout driven by a `parent` index per node.

<Example name="tidy-tree" http />

Switch to `"type": "dendrogram"` for a fixed-depth cluster layout, or
set `options.tree.orientation: "radial"` for a circular tree.

## Bubble map (chartjs-chart-geo)

`chartjs-chart-geo` provides two chart types: `bubbleMap` (shown
below) and `choropleth`. Both take a GeoJSON `outline` as the map
bounds; bubble map then plots `{longitude, latitude, value}` points
on top, sizing each bubble via the `size` scale.

This gallery example uses six hand-written polygon features in a
3 × 2 abstract grid so the config stays readable. For real maps,
drop in a world / country FeatureCollection from Natural Earth or
TopoJSON as the `outline`.

<Example name="bubble-map-abstract-grid" http />

Key shape:

- `datasets[i].outline` — array of GeoJSON `Feature` objects for the
  map bounds.
- `datasets[i].data[i]` — `{ longitude, latitude, value }`. `value`
  drives bubble radius via `options.scales.size.size: [min, max]`.
- `options.scales.projection` — any
  [d3-geo projection](https://github.com/d3/d3-geo#projections) name
  (e.g. `"equirectangular"`, `"equalEarth"`, `"mercator"`).

For `choropleth`, keep the same `outline` / projection config and
pass `{ feature, value }` points — each feature's interior gets
colored by value, driven by an `options.scales.color` scale.

> **Payload tip:** Real-world TopoJSON is often several hundred KB.
> If you're driving chartjs2img from an HTTP client, POST the config
> rather than using `GET /render?chart=…` — query-string limits bite
> long before the JSON body does.

## Why not every exotic type?

The gallery stays small on purpose so visual regressions are easy to
eyeball. The rendered examples above cover the primary layout styles
each plugin provides; every other exotic variant is exercised by
`chartjs2img llm`'s canonical example (agents read those
automatically) and by the JSON snippets above. To preview any of
them with your own data, paste the snippet into
`chartjs2img render -i <file> -o out.png`.

---

<!-- source: docs/en/gallery/i18n.md -->
<!-- route: /en/gallery/i18n -->

# Internationalization

The headless browser has access to whatever fonts the host OS /
container provides. The Docker image bundles **Noto Sans CJK**, which
covers Japanese, Chinese, and Korean without tofu.

## Japanese labels

<Example name="japanese-labels" http />

## Why it works

- **In Docker**: the `Dockerfile` installs `fonts-noto-cjk`. Chromium
  picks it up automatically as the fallback for CJK glyphs.
- **On your host** (without Docker): whatever your OS uses. On macOS
  and recent Windows, CJK just works. On fresh Linux minimal installs,
  you may need to `apt install fonts-noto-cjk` or similar.

## Verifying a non-default locale

Quickest smoke test:

```bash
# JA
echo '{"type":"bar","data":{"labels":["東京"],"datasets":[{"data":[1]}]}}' \
  | chartjs2img render -o /tmp/ja.png

# ZH
echo '{"type":"bar","data":{"labels":["北京","上海"],"datasets":[{"data":[1,2]}]}}' \
  | chartjs2img render -o /tmp/zh.png

# KO
echo '{"type":"bar","data":{"labels":["서울","부산"],"datasets":[{"data":[1,2]}]}}' \
  | chartjs2img render -o /tmp/ko.png
```

If any of those render as boxes, check font install on the host (or
use the Docker image).

## Right-to-left scripts

RTL (Arabic, Hebrew) also render correctly — Chart.js + Chromium
handle the text layout natively. Punctuation and bidi isolates behave
as expected. We don't ship an RTL-specific font pack; the glyph
coverage of Noto Sans gets you there on most systems.

## Forcing a specific font

Chart.js `options.font.family` cascades down to every text element.
Whatever you set needs to be installed on the server. chartjs2img
doesn't preload custom fonts — you own that layer if the default
stack doesn't cover your content.

---

<!-- source: docs/en/gallery/sizing.md -->
<!-- route: /en/gallery/sizing -->

# Sizing

The default is 800 × 600 pixels. The `width` and `height` HTTP/CLI
options override it. Device pixel ratio (`devicePixelRatio`) is
separate — it scales the image up for retina screens but doesn't
affect the chart's content area.

## Small size (400 × 300)

Typical for inline thumbnails or email headers.

<Example name="small-size-400x300" http caption="Renders at 400×300." />

## Wide chart (1200 × 400)

Banner / sparkline-style.

<Example name="wide-chart-1200x400" http caption="Renders at 1200×400." />

## Tips

- **The canvas doesn't reflow for `options.responsive: true` in
  chartjs2img.** We set it internally so the chart fills the
  container, but the container is sized by `width` / `height` at
  request time.
- **Aspect ratio is usually implicit.** `maintainAspectRatio` is set
  to `false` inside the template, so your `width` × `height` is what
  you get.
- **Device pixel ratio multiplies output pixels, not chart detail.**
  `devicePixelRatio: 2` at 800 × 600 produces a 1600 × 1200 PNG — the
  chart renders at 800 × 600 CSS pixels, then the canvas is exported
  at 2× resolution. Good for retina screens; bad if you want a small
  file.
- **The screenshot is of `#chart-container`**, not the page. No HTML
  chrome, no margin, no surrounding white space beyond what you put
  in the chart itself.

---

<!-- source: docs/en/guide/index.md -->
<!-- route: /en/guide -->

# Quick start

Install the `chartjs2img` binary and render your first chart in under
a minute. If you'd rather not pipe a remote script into a shell, see
[Install](./install) for manual alternatives.

## Install

Pick the command for your operating system. Both scripts place
`chartjs2img` on your `PATH` automatically.

### macOS / Linux

```sh
curl -fsSL https://bin.ideamans.com/install/chartjs2img.sh | bash
```

### Windows (PowerShell)

```powershell
irm https://bin.ideamans.com/install/chartjs2img.ps1 | iex
```

### Verify

```sh
chartjs2img --help
```

You should see the usage banner. If `chartjs2img: command not found`,
open a new shell (so the updated `PATH` is picked up) or consult
[Install](./install).

On the first render, Chromium is **auto-downloaded** to your user
cache (~250 MB). On linux-arm64 the auto-download is not available —
install Chromium from your distro and set `CHROMIUM_PATH`. Details in
[Install](./install).

## Render your first chart

Pipe a one-line Chart.js config straight into `chartjs2img` — the
`render` command reads from stdin by default and writes the PNG to
`-o`.

### macOS / Linux

```sh
echo '{"type":"bar","data":{"labels":["Jan","Feb","Mar"],"datasets":[{"label":"Sales","data":[12,19,3],"backgroundColor":"rgba(54,162,235,0.7)"}]}}' \
  | chartjs2img render -o hello.png
```

### Windows (PowerShell)

```powershell
'{"type":"bar","data":{"labels":["Jan","Feb","Mar"],"datasets":[{"label":"Sales","data":[12,19,3],"backgroundColor":"rgba(54,162,235,0.7)"}]}}' `
  | chartjs2img render -o hello.png
```

Open `hello.png` in your image viewer — you should see a three-bar
chart. It should come out like this:

<Example name="bar-chart" caption="The output of the command above." />

Want JPEG, a wider canvas, or a transparent background? The `render`
command takes flags for all of that — see [CLI rendering](./cli/) for
the full surface.

## Where to next

The rest of the User Guide is split into two tracks:

- **[CLI rendering](./cli/)** — the primary workflow. One chart in,
  one image out. Read this first.
- **[HTTP server](./http/)** — for long-running services where many
  clients hit the same renderer. Includes cache, auth, and Docker.

Or first learn what's available:

- **[Bundled plugins](./plugins)** — Chart.js plus 12 ecosystem plugins
  and which `type` values they unlock (treemap, sankey, wordcloud,
  choropleth, …). Bundled into every render without extra setup.
- **[Install](./install)** — GitHub Releases, build from source, and
  other ways to get the binary.

---

<!-- source: docs/en/guide/cli/index.md -->
<!-- route: /en/guide/cli -->

# CLI rendering

The `render` subcommand takes a Chart.js configuration as JSON and
writes an image. It's the primary way to use chartjs2img: one input
JSON in, one image out. Great for CI pipelines, Makefile targets,
report generation scripts, and ad-hoc one-offs.

```bash
chartjs2img render [options]
```

If you haven't installed yet, see the [Quick start](../).

Every example in this page renders a real Chart.js config. The
embedded widgets let you flip between the rendered PNG, the JSON
config, and a ready-to-paste CLI command:

<Example name="line-chart" caption="Flip tabs to see JSON / CLI." />

## Usage patterns

### From stdin

The default. Pipe JSON on stdin, write the image via `-o`.

```bash
echo '{"type":"bar","data":{"labels":["A","B","C"],"datasets":[{"data":[1,2,3]}]}}' \
  | chartjs2img render -o chart.png
```

### From a file

```bash
chartjs2img render -i chart.json -o chart.png
```

### To stdout

Omit `-o` (or pass `-o -`) and the binary image goes to stdout. Handy
for piping directly into `identify`, `magick`, or an HTTP POST
request.

```bash
chartjs2img render -i chart.json > chart.png

# Pipe the image straight into ImageMagick for post-processing
chartjs2img render -i chart.json | magick - -resize 640x jpg:chart.jpg
```

### JPEG output

```bash
chartjs2img render -i chart.json -o chart.jpg -f jpeg -q 85
```

### Custom dimensions, DPR, background

```bash
chartjs2img render -i chart.json -o wide.png -w 1200 -h 400
chartjs2img render -i chart.json -o retina.png --device-pixel-ratio 3
chartjs2img render -i chart.json -o transparent.png --background-color transparent
```

## Input shape

The CLI input is the Chart.js config **directly** — no wrapper.
Compare with the HTTP body, which wraps it in a `chart` field.

```json
{
  "type": "bar",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      { "label": "Sales", "data": [12, 19, 3], "backgroundColor": "rgba(54,162,235,0.7)" }
    ]
  },
  "options": {
    "plugins": {
      "title": { "display": true, "text": "Monthly Sales" }
    }
  }
}
```

::: warning JSON only — functions are silently dropped
The config travels through `JSON.stringify` on its way into the
headless browser, which drops function values, symbols, and
`undefined`. Any `formatter: (ctx) => ...` callback, tooltip
callback, or scale tick callback will disappear in transit. Use
static values instead.
:::

Every `type` plus the options each plugin adds are documented in
[Bundled plugins](../plugins), or run `chartjs2img llm` for the full
LLM-targeted reference.

## Flags

| Flag                          | Default  | Description                          |
| ----------------------------- | -------- | ------------------------------------ |
| `-i, --input <file>`          | stdin    | Input JSON file, or `-` for stdin    |
| `-o, --output <file>`         | stdout   | Output image file, or `-` for stdout |
| `-w, --width <px>`            | `800`    | Canvas width                         |
| `-h, --height <px>`           | `600`    | Canvas height                        |
| `--device-pixel-ratio <n>`    | `2`      | Retina scale factor                  |
| `--background-color <color>`  | `white`  | CSS color, or `transparent`          |
| `-f, --format <fmt>`          | `png`    | `png` or `jpeg`                      |
| `-q, --quality <0-100>`       | `90`     | Quality for JPEG                     |

## Other subcommands

### `chartjs2img examples`

Render every built-in example into an output directory. Useful for
smoke-testing a new plugin or Chromium version.

```bash
chartjs2img examples -o ./out
chartjs2img examples -o ./out -f jpeg -q 80
```

| Flag                    | Default       | Description      |
| ----------------------- | ------------- | ---------------- |
| `--outdir, -o <dir>`    | `./examples`  | Output directory |
| `-f, --format <fmt>`    | `png`         | `png` or `jpeg`  |
| `-q, --quality <0-100>` | `90`          | JPEG quality     |

### `chartjs2img llm`

Print the full Chart.js + plugin reference as Markdown, designed for
piping into an LLM context window.

```bash
chartjs2img llm > reference.md
chartjs2img llm | pbcopy                              # macOS clipboard
chartjs2img llm | llm -s "Generate a stacked bar..."  # pipe to an LLM CLI
```

### `chartjs2img help` / `--help`

Prints the full usage banner: every subcommand, every flag, every
environment variable.

### `chartjs2img version` / `--version`

Prints the version.

## Exit codes

| Code | Meaning                                           |
| ---- | ------------------------------------------------- |
| `0`  | Success                                           |
| `1`  | I/O failure or Chromium launch failure            |
| `2`  | Argument error (missing value for a value flag)   |

Chart.js runtime errors (invalid `type`, dataset shape mismatch, etc.)
do **not** cause a non-zero exit. They are surfaced via stderr — see
[Error feedback](./error-feedback).

## Performance notes

- Chromium is launched on the first render in the process and reused
  for subsequent renders within the same invocation. One-shot CLI
  calls pay the launch cost (~300 ms) every time.
- For batch rendering of many charts, prefer `chartjs2img examples -o
  ./out` (which reuses one browser across all entries) or run the
  [HTTP server](../http/) and POST each chart.

## Where to next

- **[Environment variables](./env-vars)** — tune Chromium discovery,
  render timeouts, and cache behavior for CLI use.
- **[Error feedback](./error-feedback)** — how Chart.js warnings and
  errors appear on stderr.
- **[Bundled plugins](../plugins)** — the 12 Chart.js plugins
  available without extra setup.

---

<!-- source: docs/en/guide/cli/env-vars.md -->
<!-- route: /en/guide/cli/env-vars -->

# Environment variables (CLI)

Running `chartjs2img render` reads a small set of environment
variables — mostly to locate Chromium and to tune the render budget.
Variables specific to the HTTP server (`PORT`, `HOST`, `API_KEY`)
have no effect here; see [HTTP server → Environment variables](../http/env-vars)
for those.

| Variable                   | Default     | Description                                                                             |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------- |
| `CHROMIUM_PATH`            | *(none)*    | Explicit path to a Chromium / Chrome executable. Wins over the auto-detection chain.     |
| `PLAYWRIGHT_BROWSERS_PATH` | *(none)*    | Override the Playwright cache directory searched during detection.                       |
| `MAX_RENDER_TIME_SECONDS`  | `30`        | Upper bound for a single render (applied to `page.goto` and `waitForFunction`).          |
| `PAGE_TIMEOUT_SECONDS`     | *(derived)* | Override the safety-net force-close timer. Default: `MAX_RENDER_TIME_SECONDS * 2 + 10s`. |
| `CONCURRENCY`              | `8`         | Not exercised by one-shot `render`, but respected by `chartjs2img examples` batch mode. |

The cache variables (`CACHE_MAX_ENTRIES`, `CACHE_TTL_SECONDS`) are
also read at startup, but the cache lives only as long as the process
— so a single one-shot `render` call cannot benefit from cache hits.
They are effectively a server concern.

## Setting them

### Per-command

```bash
CHROMIUM_PATH=/usr/bin/chromium-browser chartjs2img render -i chart.json -o chart.png
```

### Per-shell

```bash
export CHROMIUM_PATH=/usr/bin/chromium-browser
export MAX_RENDER_TIME_SECONDS=60

chartjs2img render -i chart.json -o chart.png
```

### In CI / systemd

Set them alongside your job definition. On GitHub Actions:

```yaml
- name: Render charts
  env:
    CHROMIUM_PATH: /usr/bin/chromium-browser
    MAX_RENDER_TIME_SECONDS: 60
  run: chartjs2img render -i chart.json -o chart.png
```

## When to tune

### `CHROMIUM_PATH`

Set it when the auto-detection chain can't find a browser you know is
installed — Linux ARM64 is the common case because the Chrome for
Testing auto-download does not publish linux-arm64 builds. See
[Install → Linux ARM64](../install#linux-arm64-manual-chromium-required).

### `MAX_RENDER_TIME_SECONDS`

Raise it when you legitimately need long renders — e.g. a very
large force-directed graph or a CDN cold start on a slow network.
The default 30 s covers every bundled example several times over.

### `PAGE_TIMEOUT_SECONDS`

Leave it alone unless you see a `Safety net fired after Xms` warning
in stderr without the render actually hanging. If that happens the
derived default is too tight — raise it (or increase
`MAX_RENDER_TIME_SECONDS`, which re-derives the safety net).

## See also

- [Install](../install) — Chromium detection order and linux-arm64 notes.
- [Error feedback](./error-feedback) — interpreting render-time
  warnings on stderr.

---

<!-- source: docs/en/guide/cli/error-feedback.md -->
<!-- route: /en/guide/cli/error-feedback -->

# Error feedback (CLI)

A Chart.js config with a typo (e.g. `"type": "pi"` instead of
`"pie"`) renders a blank or partial image. Without console access
you'd be left guessing why your chart is empty. The CLI captures the
same messages you'd see in the browser's DevTools and streams them to
**stderr** as the render runs.

## The shape

Each message is prefixed with its level and the literal message text
from Chart.js:

```
[chart ERROR] "pi" is not a registered controller.
[chart WARN]  Some warning message from Chart.js.
```

Two levels are emitted:

- `ERROR` — Chart.js threw or refused to render the config.
- `WARN` — Chart.js rendered something but flagged a likely mistake.

## Example

```bash
$ echo '{"type":"pi","data":{"labels":["A"],"datasets":[{"data":[1]}]}}' \
  | chartjs2img render -o chart.png

[chart ERROR] "pi" is not a registered controller.
Written to chart.png (hash: 1234abcd5678efgh)
```

Notice: the render **still completes** (writing an empty or partial
PNG) and the CLI still exits `0`. Chart.js warnings are not treated as
CLI failures, so pipelines don't fail on a typo — you have to watch
stderr and decide yourself.

## Piping the image while capturing messages

Since stdout carries the image binary and stderr carries diagnostics,
you can redirect them independently:

```bash
chartjs2img render -i chart.json 2> errors.log > chart.png
```

Check `errors.log` for messages and `chart.png` for the image.

## When rendering "succeeds but is wrong"

A Chart.js config can be syntactically valid, render, and still be
wrong — e.g. a `scatter` chart given `labels` + `datasets[0].data:
[1,2,3]` instead of `{x,y}` pairs. These often don't throw but emit a
warning. Always scan stderr before declaring success in a CI job.

## Recommended agent workflow

If you're driving `chartjs2img render` from an LLM agent:

1. Run the render, capturing stderr.
2. If stderr is non-empty, feed the messages back into the agent and
   ask it to fix the config.
3. Loop until stderr is clean.

This is effectively how the `chartjs2img-render` Agent Skill works.
See [AI Guide → Claude Code plugin](/en/ai/claude-plugin) for the full
loop.

## Common messages

| Message                                         | Usual cause                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| `"X" is not a registered controller.`           | Typo in `chart.type`, or a plugin chart type missing from the bundle.       |
| `Cannot read properties of undefined...`        | Missing `datasets`, wrong dataset shape, or numeric `data` where object expected. |
| `No dataset matched the index`                  | Mismatch between `labels.length` and `data.length`.                         |
| `The scale "y" doesn't have a parser`           | Time-series data without a time adapter — use `scales.x.type: "time"`.      |

When in doubt, the full Chart.js
[error reference](https://www.chartjs.org/docs/latest/) tells you what
each message means.

## Non-Chart.js errors

Messages about Chromium (download, launch, container permissions)
appear **without** the `[chart …]` prefix and typically exit non-zero.
They signal an environment problem, not a config problem:

```
[renderer] Chrome/Chromium not found. Installing Chrome for Testing...
[renderer] Downloading Chrome 123.0.0.0 for mac-arm64...
```

See [Install → Chromium / Chrome detection](../install#chromium--chrome-detection)
if the auto-install doesn't work for your platform.

---

<!-- source: docs/en/guide/http/index.md -->
<!-- route: /en/guide/http -->

# HTTP server

Run `chartjs2img serve` to expose the same renderer over HTTP. This is
the right mode when multiple clients render charts, when renders
benefit from a shared in-memory cache, or when you want a single
long-running process rather than per-chart subprocess startup.

```bash
chartjs2img serve --port 3000
```

On startup the server prints:

```
chartjs2img v0.2.2 listening on http://0.0.0.0:3000
  POST /render      - render chart from JSON body
  GET  /render      - render chart from query params
  GET  /cache/:hash - retrieve cached image
  GET  /examples    - examples gallery
  GET  /health      - health check + stats
```

Press `Ctrl-C` (or send `SIGTERM`) to shut down cleanly — the server
drains in-flight requests before closing Chromium.

A quick taste of what the POST produces — flip to the **HTTP** tab to
see the exact `curl` that generates the preview:

<Example name="pie-chart" http caption="POST /render output." />

## Server flags

| Flag          | Default    | Env var   | Description                   |
| ------------- | ---------- | --------- | ----------------------------- |
| `--port, -p`  | `3000`     | `PORT`    | TCP listen port               |
| `--host`      | `0.0.0.0`  | `HOST`    | Bind address                  |
| `--api-key`   | *(none)*   | `API_KEY` | Require this token on auth-gated endpoints |

Other knobs (concurrency, cache, timeouts) are configured via
environment variables only — see [Environment variables](./env-vars).

## `POST /render`

Render a chart from a JSON body.

```bash
curl -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{
    "chart": {
      "type": "bar",
      "data": { "labels": ["Jan","Feb"], "datasets": [{"data":[1,2]}] }
    },
    "width": 800,
    "height": 600,
    "format": "png"
  }' \
  -o chart.png
```

### Request body

| Field              | Type    | Default        | Description                                          |
| ------------------ | ------- | -------------- | ---------------------------------------------------- |
| `chart`            | object  | **required**   | Chart.js config (`type`, `data`, `options`, …)        |
| `width`            | number  | `800`          | Image width in pixels                                |
| `height`           | number  | `600`          | Image height in pixels                               |
| `devicePixelRatio` | number  | `2`            | Retina scaling factor                                |
| `backgroundColor`  | string  | `"white"`      | CSS color (`"transparent"` supported)                |
| `format`           | string  | `"png"`        | `png` or `jpeg`                                       |
| `quality`          | number  | `90`           | JPEG quality (0-100)                                  |

::: warning JSON only — functions are silently dropped
The `chart` field travels through `JSON.stringify` on its way into the
headless browser. Any `formatter: (ctx) => ...` callback, tooltip
callback, or scale tick callback disappears in transit. Use static
values instead.
:::

Missing / invalid input returns `400` with a JSON error body:

```json
{ "error": "Missing or invalid required field: chart (must be an object)" }
```

### Response headers

| Header              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `Content-Type`      | `image/png` or `image/jpeg`                                      |
| `X-Cache-Hash`      | SHA-256 hash (first 16 hex chars) of the canonicalized request    |
| `X-Cache-Url`       | Full URL to re-fetch this image from `/cache/<hash>`              |
| `X-Cache-Hit`       | `"true"` if served from cache, `"false"` if freshly rendered      |
| `X-Chart-Messages`  | JSON array of `{level, message}` — only present on warnings/errors |

See [Error feedback](./error-feedback) for how to interpret
`X-Chart-Messages`, and [Cache](./cache) for how the hash is computed.

## `GET /render`

Same semantics as POST, but all parameters come from query strings.
Useful for embedding in `<img>` tags.

```
GET /render?chart={"type":"bar","data":{...}}&width=400&height=300
```

The `chart` query parameter must be a URL-encoded JSON string.
Beyond a few hundred data points you'll want POST — most clients cap
URL length well below chartjs2img's server limit.

## `GET /cache/:hash`

Re-fetch a previously rendered image by its cache hash.

```bash
# Render and grab the hash
HASH=$(curl -s -D- -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{"chart":{"type":"bar","data":{"labels":["A","B"],"datasets":[{"data":[1,2]}]}}}' \
  -o /dev/null | grep -i x-cache-hash | awk '{print $2}' | tr -d '\r')

# Fetch the cached image later
curl -o chart.png "http://localhost:3000/cache/$HASH"
```

Cached entries expire after `CACHE_TTL_SECONDS` (default 3600).
Missing or expired hashes return `404`. Details in [Cache](./cache).

## `GET /health`

Returns server status, renderer stats, cache info, and concurrency
counters. Useful for liveness / readiness probes.

```json
{
  "status": "ok",
  "version": "0.2.2",
  "renderer": {
    "browserConnected": true,
    "concurrency": { "max": 8, "active": 2, "pending": 0 },
    "activePages": 2,
    "maxRenderTimeSeconds": 30,
    "pageSafetyNetSeconds": 70,
    "pageTimeoutSeconds": 70
  },
  "cache": {
    "size": 42,
    "maxEntries": 1000,
    "ttlSeconds": 3600
  }
}
```

`pageTimeoutSeconds` is a deprecated alias of `pageSafetyNetSeconds`
retained for clients shipped before the field was renamed.

## `GET /examples`

Built-in gallery showing every example chart rendered live. The page
displays each chart plus its source JSON — a convenient way to verify
the service is up and browse available chart types.

::: tip
When `API_KEY` is set, `/examples` requires the key too (otherwise
the page would embed the key in its HTML for the subsequent `/render`
calls and leak it on any unauthenticated fetch). See
[Authentication](./auth).
:::

## Capacity

Incoming renders wait on a semaphore with `CONCURRENCY` slots
(default `8`). Extra requests queue until a slot frees up. Tune via
[Environment variables](./env-vars).

## Where to next

- **[Cache](./cache)** — hash-based caching mechanism and CDN-friendly URLs.
- **[Authentication](./auth)** — optional API key setup.
- **[Docker](./docker)** — container image, docker-compose, reverse proxy.
- **[Environment variables](./env-vars)** — every tunable for the server.
- **[Error feedback](./error-feedback)** — `X-Chart-Messages` and HTTP error codes.

---

<!-- source: docs/en/guide/http/auth.md -->
<!-- route: /en/guide/http/auth -->

# Authentication

API key authentication is **optional**. When disabled (the default),
all endpoints are reachable anonymously. When enabled, `/render`,
`/cache/:hash`, and `/examples` require the key; `/health` stays
public so liveness probes keep working.

## Enabling

Pick one of the two:

```bash
# CLI flag
chartjs2img serve --api-key s3cret

# Environment variable
API_KEY=s3cret chartjs2img serve
```

Either is fine; the CLI flag wins if both are set.

## Passing the key

Clients may pass the key in three ways. Pick whichever fits your
call site; the server accepts all three.

### `Authorization: Bearer`

```bash
curl -H 'Authorization: Bearer s3cret' \
  http://localhost:3000/render ...
```

### `X-API-Key`

```bash
curl -H 'X-API-Key: s3cret' \
  http://localhost:3000/render ...
```

### `?api_key=`

Useful for `<img>` embeds where you can't set headers.

```
http://localhost:3000/render?api_key=s3cret&chart=...
```

## Public vs. auth-gated endpoints

| Endpoint            | Without `API_KEY` | With `API_KEY`     |
| ------------------- | ----------------- | ------------------ |
| `POST /render`      | Public            | Requires key       |
| `GET /render`       | Public            | Requires key       |
| `GET /cache/:hash`  | Public            | Requires key       |
| `GET /examples`     | Public            | **Requires key**   |
| `GET /health`       | Public            | Public             |

`/examples` is gated when `API_KEY` is set because the page embeds
the key in its HTML for the subsequent `/render` calls. Leaving the
page public would leak the key to any fetch of `/examples`. This was
tightened in version 0.3 — versions before that used to leave
`/examples` open even with `API_KEY` set.

## What to do when the key is missing / wrong

The server returns `401 Unauthorized` with a JSON body:

```json
{ "error": "Unauthorized" }
```

No hint is leaked about whether the key was missing or merely wrong.

## Recommended setup

For anything beyond local dev:

1. Put chartjs2img behind a reverse proxy (nginx, Caddy, a CDN) that
   also handles TLS.
2. Set `API_KEY` to a long random string. Rotate periodically.
3. Pass the key server-side; don't ship it to browsers.
4. Optionally, bind to `127.0.0.1` and let the proxy be the only
   public entry point.

---

<!-- source: docs/en/guide/http/cache.md -->
<!-- route: /en/guide/http/cache -->

# Cache

Every `POST /render` computes a SHA-256 hash of the canonicalized
request (chart config + size + format + options). If the same hash
has been rendered recently, the cached image is returned instantly.

## How the hash is computed

The cache key is deterministic over:

- `chart` (full JSON, canonicalized key order — `{a:1,b:2}` and
  `{b:2,a:1}` hash the same)
- `width`, `height`, `devicePixelRatio`
- `backgroundColor`, `format`, `quality`

Reorder the keys, change whitespace, or swap a float for an
equivalent integer — the hash still matches, because the input is
normalized before hashing. Change a single data point and you'll get
a new hash.

The hash is the first 16 hex chars of the SHA-256 digest. Collision
probability at this length is negligible for a cache layer.

## Headers to watch

Every `/render` response carries:

| Header         | Example                                     | Meaning                      |
| -------------- | ------------------------------------------- | ---------------------------- |
| `X-Cache-Hash` | `6b4cc4e8940fd921`                          | The key for this image       |
| `X-Cache-Url`  | `http://host:3000/cache/6b4cc4e8940fd921`   | Direct URL to re-fetch       |
| `X-Cache-Hit`  | `true` / `false`                            | Served from cache?           |

## CDN-friendly URLs

Because `X-Cache-Url` points at `/cache/:hash` — a plain GET
endpoint — you can hand that URL to a browser, a Markdown document,
or a CDN. Once fetched, most CDNs can cache it indefinitely (entries
are immutable for their hash).

```html
<!-- Rendered once; reused forever -->
<img src="https://charts.example.com/cache/6b4cc4e8940fd921">
```

## Eviction and TTL

| Setting                | Default | Env var              |
| ---------------------- | ------- | -------------------- |
| Max entries in memory  | 1000    | `CACHE_MAX_ENTRIES`  |
| Time-to-live (seconds) | 3600    | `CACHE_TTL_SECONDS`  |

The cache is bounded (FIFO eviction when full) plus per-entry TTL.
Fetching an evicted or expired `/cache/:hash` returns `404`.

## When to rely on the cache

- **Dashboards** that render the same charts repeatedly for many
  viewers.
- **LLM agents** that propose the same configuration multiple times
  during iteration.
- **Snapshot emails / reports** where the chart is computed once at
  publish time and embedded everywhere.

## When NOT to rely on it

- Live data streams where every render has new inputs — the hash will
  always miss.
- Compliance scenarios where each request must physically re-render
  (to prove fresh data). Set `CACHE_MAX_ENTRIES=0` or skip the cache
  by always sending unique inputs.
- Horizontal-scale-out deployments — the cache is per-process, not
  shared. Put a CDN in front to coalesce across instances.

## Smoke test

```bash
# First call — fresh render
curl -s -D- -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{"chart":{"type":"bar","data":{"labels":["A","B"],"datasets":[{"data":[1,2]}]}}}' \
  -o /dev/null | grep -i x-cache

# Second call — same body, should be a hit
curl -s -D- -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{"chart":{"type":"bar","data":{"labels":["A","B"],"datasets":[{"data":[1,2]}]}}}' \
  -o /dev/null | grep -i x-cache
```

You should see `X-Cache-Hit: false` followed by `X-Cache-Hit: true`.

---

<!-- source: docs/en/guide/http/docker.md -->
<!-- route: /en/guide/http/docker -->

# Docker

The Docker image is intended for the **HTTP server** workflow: one
container, one long-running server, many clients. If you want to
render a single chart on your laptop, the [CLI](../cli/) is
lighter — no container needed.

## Build

```bash
docker build -t chartjs2img .
```

What the image includes:

- The compiled `chartjs2img` binary (via Bun's `--compile`)
- Chromium (preinstalled, so no first-run download at service start)
- **Noto Sans CJK** — Japanese, Chinese, and Korean labels render correctly

## Run

```bash
docker run -p 3000:3000 chartjs2img
```

With configuration:

```bash
docker run -p 3000:3000 \
  -e API_KEY=s3cret \
  -e CONCURRENCY=4 \
  -e CACHE_MAX_ENTRIES=2000 \
  -e CACHE_TTL_SECONDS=7200 \
  chartjs2img
```

See [Environment variables](./env-vars) for the full list.

## docker-compose

```yaml
services:
  chartjs2img:
    build: .
    ports:
      - "3000:3000"
    environment:
      API_KEY: s3cret
      CONCURRENCY: 8
      CACHE_MAX_ENTRIES: 2000
      CACHE_TTL_SECONDS: 7200
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
```

## Behind a reverse proxy

For production, front chartjs2img with nginx / Caddy / a CDN for TLS,
rate-limiting, and request logging.

### nginx

```nginx
upstream chartjs2img {
  server 127.0.0.1:3000;
}

server {
  listen 443 ssl;
  server_name charts.example.com;

  location / {
    proxy_pass http://chartjs2img;
    proxy_set_header Host $host;
    # Don't buffer at the proxy — /cache/:hash is already immutable
    proxy_buffering off;
    # Long-tail renders can take several seconds
    proxy_read_timeout 60s;
  }
}
```

### Caddy

```
charts.example.com {
  reverse_proxy localhost:3000 {
    transport http {
      read_timeout 60s
    }
  }
}
```

## Persistence

The hash cache is **in-memory**. Restarting the container clears it —
clients just get `X-Cache-Hit: false` until the cache rewarms.

If you need durable caching across restarts, either:

- Place a CDN in front and cache `/cache/:hash` at the edge
  (best-in-class for immutable content).
- Write your own caching layer that stores the rendered PNG somewhere
  durable and bypasses chartjs2img's internal cache entirely.

## Linux ARM64

The Docker image builds on linux/amd64 by default. For linux/arm64
(Apple Silicon, AWS Graviton), use buildx:

```bash
docker buildx build --platform linux/arm64 -t chartjs2img .
```

The base image uses Debian's packaged Chromium which **does** support
linux-arm64 — unlike the auto-download path. See
[Install → Linux ARM64](../install#linux-arm64-manual-chromium-required)
for native (non-Docker) notes.

## Troubleshooting

### Container starts but renders time out

Check `docker logs <container>` — look for Chromium launch errors.
Common fixes:

- Give the container enough shared memory: `--shm-size=1g`
- Ensure the container user has write access to `/tmp` (Chromium
  scratch space)

### Japanese / CJK text shows up as boxes

This shouldn't happen with the provided Dockerfile (Noto Sans CJK
is baked in). If you customized it, install the fonts explicitly:

```dockerfile
RUN apt-get update && apt-get install -y \
  fonts-noto-cjk fonts-noto-color-emoji \
  && rm -rf /var/lib/apt/lists/*
```

### Image builds but Chromium isn't found at runtime

Set `CHROMIUM_PATH` explicitly:

```bash
docker run -e CHROMIUM_PATH=/usr/bin/chromium chartjs2img
```

---

<!-- source: docs/en/guide/http/env-vars.md -->
<!-- route: /en/guide/http/env-vars -->

# Environment variables (HTTP server)

All server-side settings can be configured by env var — convenient
for Docker, Kubernetes, CI, and systemd. Variables relevant only to
the CLI (`CHROMIUM_PATH` when Chromium is auto-installed, for
example) are duplicated here because the server also reads them; see
[CLI → Environment variables](../cli/env-vars) for their CLI-specific
nuances.

| Variable                   | Default     | Description                                                                               |
| -------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `PORT`                     | `3000`      | HTTP server port                                                                          |
| `HOST`                     | `0.0.0.0`   | HTTP server bind address                                                                  |
| `API_KEY`                  | *(none)*    | Enable auth with this token. See [Authentication](./auth).                                |
| `CONCURRENCY`              | `8`         | Max simultaneous renders. Additional requests queue.                                      |
| `CACHE_MAX_ENTRIES`        | `1000`      | Max cached images in memory.                                                              |
| `CACHE_TTL_SECONDS`        | `3600`      | Cache entry lifetime.                                                                     |
| `MAX_RENDER_TIME_SECONDS`  | `30`        | Upper bound for a single render (applied to `page.goto` and `waitForFunction`).           |
| `PAGE_TIMEOUT_SECONDS`     | *(derived)* | Override the safety-net force-close timer. Default: `MAX_RENDER_TIME_SECONDS * 2 + 10s`.  |
| `CHROMIUM_PATH`            | *(none)*    | Explicit path to a Chromium binary. Wins over the detection chain. See [Install](../install). |

## Setting them

### Shell

```bash
export PORT=8080
export CONCURRENCY=4
export API_KEY=s3cret
chartjs2img serve
```

### Docker

```bash
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e API_KEY=s3cret \
  -e CONCURRENCY=4 \
  chartjs2img
```

### docker-compose

```yaml
services:
  chartjs2img:
    build: .
    ports:
      - "3000:3000"
    environment:
      API_KEY: s3cret
      CONCURRENCY: 8
      CACHE_MAX_ENTRIES: 2000
      CACHE_TTL_SECONDS: 7200
      MAX_RENDER_TIME_SECONDS: 45
```

### systemd

```ini
[Service]
Environment=PORT=3000
Environment=API_KEY=s3cret
Environment=CONCURRENCY=8
ExecStart=/usr/local/bin/chartjs2img serve
```

## Tuning guidelines

### `CONCURRENCY`

Match it to available CPU cores. Each active render uses one browser
tab and 50-150 MB of memory. Too high and you'll see OOMs or page
timeouts; too low and clients wait in the queue.

Typical values:

- 2 cores → `CONCURRENCY=2`
- 8 cores → `CONCURRENCY=6` (leave headroom for I/O + OS)
- 32 cores → `CONCURRENCY=16` (memory becomes the bottleneck, not CPU)

Watch `GET /health` → `renderer.concurrency.pending` to decide whether
to raise the ceiling or scale out horizontally.

### `CACHE_MAX_ENTRIES` / `CACHE_TTL_SECONDS`

Identical requests are cheap; wide-variety requests don't benefit.
Profile with `X-Cache-Hit: true/false`:

- Dashboard with ~50 charts shown many times a day → large cache, long TTL.
- Ad-hoc one-offs → small cache, short TTL.
- Stateless horizontal scale-out → set `CACHE_MAX_ENTRIES=0` and
  cache at the CDN instead (see [Cache](./cache)).

### `MAX_RENDER_TIME_SECONDS`

Raise only when you have legitimately slow renders (huge datasets,
slow CDN on a cold start). Lower to fail-fast on stuck charts.

### `PAGE_TIMEOUT_SECONDS`

The safety-net timer only fires when the render finally block never
runs (genuinely orphaned tab). You should rarely need to override the
derived default; if you see `Safety net fired after Xms` warnings in
the server logs without the request actually hanging, it indicates a
bug in the renderer — please file an issue.

## See also

- [CLI → Environment variables](../cli/env-vars) — overlapping
  variables read by one-shot `render` calls.
- [Authentication](./auth) — `API_KEY` usage.
- [Cache](./cache) — how `CACHE_MAX_ENTRIES` and `CACHE_TTL_SECONDS`
  interact.

---

<!-- source: docs/en/guide/http/error-feedback.md -->
<!-- route: /en/guide/http/error-feedback -->

# Error feedback (HTTP)

Rendering a chart over HTTP can produce three kinds of signal:

1. **The image itself** — always returned, even when something went wrong.
2. **Chart.js console messages** — captured from the headless browser
   and returned via an HTTP header.
3. **Server-level errors** — authentication, input validation, or
   Chromium failures. Returned as standard HTTP status codes.

This page is about all three.

## `X-Chart-Messages` — Chart.js console

When Chart.js logs errors or warnings during a render, the response
includes:

```
X-Chart-Messages: [{"level":"error","message":"\"pi\" is not a registered controller."}]
```

Parse it as JSON:

```bash
curl -s -D- -X POST http://localhost:3000/render \
  -H 'Content-Type: application/json' \
  -d '{"chart":{"type":"pi","data":{"labels":["A"],"datasets":[{"data":[1]}]}}}' \
  -o /dev/null | grep X-Chart-Messages
```

Each message is:

| Field     | Values              | Description                 |
| --------- | ------------------- | --------------------------- |
| `level`   | `"error"`, `"warn"` | Severity                    |
| `message` | string              | Verbatim text from Chart.js |

The header is **only present** when at least one message occurred. No
header means clean render. The render itself still completes and
returns `200` with the PNG — a warning is an advisory, not a failure.

## HTTP status codes

| Status | Meaning                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------- |
| `200`  | Render OK. May still carry `X-Chart-Messages` if Chart.js warned.                              |
| `400`  | Client input invalid: missing `chart`, malformed JSON body, bad `?chart=` query parameter.     |
| `401`  | `API_KEY` required and not provided / wrong. See [Authentication](./auth).                     |
| `404`  | Unknown path, expired/unknown cache hash.                                                      |
| `405`  | Method not allowed on `/render` (e.g. `PUT`).                                                  |
| `500`  | Internal server error — Chromium failed to launch, disk full, network problem with the CDN.   |

The body of 4xx and 5xx responses is a JSON object:

```json
{ "error": "Missing or invalid required field: chart (must be an object)" }
```

400 vs. 500 is deliberate: client input errors are not monitoring
alerts. If you see 5xx in production, treat it as a real incident
(not a user typo).

## When rendering "succeeds but is wrong"

A Chart.js config can be syntactically valid, render, and still be
wrong — e.g. a `scatter` chart given `labels` + `datasets[0].data:
[1,2,3]` instead of `{x,y}` pairs. These often don't throw but emit
warnings. Always scan `X-Chart-Messages` before declaring success.

## Recommended agent workflow

If you're driving chartjs2img from an LLM agent over HTTP:

1. Submit the render.
2. If the response is 4xx/5xx, feed the `error` string back and ask
   the agent to fix the request or the environment.
3. If the response is 200, check `X-Chart-Messages`. If non-empty,
   feed the messages back and ask for a config fix.
4. Loop until messages are empty.

This is effectively how the `/chartjs2img-render` Agent Skill works.
See [AI Guide → Claude Code plugin](/en/ai/claude-plugin).

## Common Chart.js messages

| Message                                         | Usual cause                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| `"X" is not a registered controller.`           | Typo in `chart.type`, or a plugin chart type missing from the bundle.       |
| `Cannot read properties of undefined...`        | Missing `datasets`, wrong dataset shape, or numeric `data` where object expected. |
| `No dataset matched the index`                  | Mismatch between `labels.length` and `data.length`.                         |
| `The scale "y" doesn't have a parser`           | Time-series data without a time adapter — use `scales.x.type: "time"`.      |

When in doubt, the full Chart.js
[error reference](https://www.chartjs.org/docs/latest/) tells you
what each message means.

## Chromium-level failures

If the browser itself fails to launch (missing binary, permissions,
container without shared memory), the server responds `500` with a
message like:

```json
{ "error": "Failed to install Chrome automatically: ..." }
```

and logs the underlying error to stderr. Fix the environment, not
the chart config. See
[Install → Chromium / Chrome detection](../install#chromium--chrome-detection).

---

<!-- source: docs/en/guide/install.md -->
<!-- route: /en/guide/install -->

# Install

The fastest way to install `chartjs2img` is the one-liner shown in the
[Quick start](./) — a curl-pipes-bash script that downloads the right
binary for your platform and drops it on your `PATH`. This page covers
every other option: the install landing page, GitHub Releases,
Docker, and building from source.

## The install landing page

The install scripts are served from a dedicated page:

**<https://bin.ideamans.com/oss/chartjs2img>**

::: tip
The landing page itself is in Japanese, but the install commands are
universal and work as-is on any locale.
:::

It publishes the latest versioned script for each platform:

| Platform             | Command                                                              |
|----------------------|----------------------------------------------------------------------|
| macOS / Linux        | `curl -fsSL https://bin.ideamans.com/install/chartjs2img.sh \| bash` |
| Windows (PowerShell) | `irm https://bin.ideamans.com/install/chartjs2img.ps1 \| iex`        |

Default install locations:

- **Linux / macOS** — a system-wide directory (usually `/usr/local/bin`).
  Override per-user with `--install-dir $HOME/bin`:
  ```sh
  curl -fsSL https://bin.ideamans.com/install/chartjs2img.sh | bash -s -- --install-dir "$HOME/bin"
  ```
- **Windows (admin)** — `C:\Program Files\chartjs2img\chartjs2img.exe`
- **Windows (standard user)** — `%USERPROFILE%\bin\chartjs2img.exe`

If you installed to a custom directory, make sure it's on your `PATH`.

## GitHub Releases (manual download)

Every tagged release publishes prebuilt archives. Download, extract,
and move the binary yourself.

**<https://github.com/ideamans/chartjs2img/releases/latest>**

| Platform              | Asset                                        |
|-----------------------|----------------------------------------------|
| Linux x64             | `chartjs2img_<version>_linux_amd64.tar.gz`   |
| Linux ARM64           | `chartjs2img_<version>_linux_arm64.tar.gz`   |
| macOS (Intel)         | `chartjs2img_<version>_darwin_amd64.tar.gz`  |
| macOS (Apple Silicon) | `chartjs2img_<version>_darwin_arm64.tar.gz`  |
| Windows x64           | `chartjs2img_<version>_windows_amd64.zip`    |

### Linux / macOS

```sh
VERSION=0.2.2
OS=linux       # or darwin
ARCH=amd64     # or arm64

curl -fsSL -o chartjs2img.tar.gz \
  "https://github.com/ideamans/chartjs2img/releases/download/v${VERSION}/chartjs2img_${VERSION}_${OS}_${ARCH}.tar.gz"

tar -xzf chartjs2img.tar.gz
sudo mv chartjs2img /usr/local/bin/
```

### Windows (PowerShell)

```powershell
$Version = "0.2.2"
$Url = "https://github.com/ideamans/chartjs2img/releases/download/v$Version/chartjs2img_${Version}_windows_amd64.zip"

Invoke-WebRequest $Url -OutFile chartjs2img.zip
Expand-Archive chartjs2img.zip -DestinationPath .
# move chartjs2img.exe somewhere on your PATH, e.g. %USERPROFILE%\bin
```

## Docker (HTTP server only)

If you want to run chartjs2img as a long-running HTTP service, pull or
build the Docker image — it ships with Chromium and Noto Sans CJK
fonts baked in so there's no first-run download and Japanese / Chinese
/ Korean labels render correctly.

See [HTTP server → Docker](./http/docker) for build, run, and
docker-compose recipes.

## Build from source

chartjs2img is built with [Bun](https://bun.sh). Install Bun, then:

```sh
git clone https://github.com/ideamans/chartjs2img
cd chartjs2img
bun install
bun run build        # produces ./chartjs2img in the repo root
```

Or run without compiling — handy for hacking on the CLI itself:

```sh
bun run src/index.ts render -i chart.json -o chart.png
```

## Chromium / Chrome detection

On first render, chartjs2img searches for a browser in this order:

1. **`CHROMIUM_PATH`** environment variable — explicit override wins.
2. **Puppeteer browser cache** — `~/.cache/puppeteer/`, etc.
3. **System-installed Chrome/Chromium** — `/Applications/Google Chrome.app`,
   `/usr/bin/google-chrome`, etc.
4. **Auto-download** — [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/)
   is pulled into the user cache dir (no sudo required).

Auto-download is available for **macOS (x64/arm64)**, **Windows (x64)**,
and **Linux (x64)**.

### Linux ARM64 (manual Chromium required)

Chrome for Testing does **not** publish linux-arm64 builds. Install
Chromium yourself and point `CHROMIUM_PATH` at it:

```sh
# Debian / Ubuntu
sudo apt install chromium-browser   # or `chromium`

export CHROMIUM_PATH=/usr/bin/chromium-browser
chartjs2img render -i chart.json -o chart.png
```

You can also set it in the systemd unit / Docker run environment to
persist it.

## Upgrade

Re-run the one-liner from the [Quick start](./), or pull the latest
asset from Releases. The script is idempotent — it replaces the
existing binary in place.

## Uninstall

Delete the binary from wherever it was installed
(`/usr/local/bin/chartjs2img`, `$HOME/bin/chartjs2img`, or the Windows
install directory). That's the only file the installer writes. At
runtime `chartjs2img` may also cache a downloaded Chromium under
`~/Library/Caches/ms-playwright/` (macOS), `~/.cache/ms-playwright/`
(Linux), or `%LOCALAPPDATA%\ms-playwright\` (Windows); delete that
directory to reclaim the ~250 MB.

---

<!-- source: docs/en/guide/plugins.md -->
<!-- route: /en/guide/plugins -->

# Bundled plugins

The plugin bundle is the same whether you render via the
[CLI](./cli/) or the [HTTP server](./http/) — both share a single
renderer. This page is the reference both tracks point back to.

chartjs2img ships with Chart.js core **plus 12 ecosystem plugins**,
all pre-loaded in the headless browser. You don't install anything —
just use the options in your config JSON.

For each plugin's full option schema, run `chartjs2img llm` and grep
the relevant section, or see the upstream docs linked below.

## Core

| Plugin                                            | Version | Use for                 |
| ------------------------------------------------- | ------- | ----------------------- |
| [chart.js](https://www.chartjs.org/)              | 4.4.9   | Everything — this is Chart.js itself |

Supported `chart.type` values out of the box: `bar`, `line`, `pie`,
`doughnut`, `radar`, `polarArea`, `scatter`, `bubble`.

## Visual decorations

| Plugin                                                                                      | Version | Use for                                      |
| ------------------------------------------------------------------------------------------- | ------- | -------------------------------------------- |
| [chartjs-plugin-datalabels](https://chartjs-plugin-datalabels.netlify.app/)                 | 2.2.0   | Display values on bars, points, slices       |
| [chartjs-plugin-annotation](https://www.chartjs.org/chartjs-plugin-annotation/)             | 3.1.0   | Threshold lines, boxes, labels, polygons     |
| [chartjs-plugin-zoom](https://www.chartjs.org/chartjs-plugin-zoom/)                          | 2.2.0   | Initial-range / zoom configuration           |
| [chartjs-plugin-gradient](https://github.com/kurkle/chartjs-plugin-gradient)                 | 0.6.1   | Gradient fills without manual canvas code    |

> **Note on datalabels:** datalabels is **hidden by default**; turn it on
> explicitly per-chart via `options.plugins.datalabels.display: true`
> (or per-dataset) if you want values to appear.

## Additional chart types

| Plugin                                                                                | Version | Adds chart.type                               |
| ------------------------------------------------------------------------------------- | ------- | --------------------------------------------- |
| [chartjs-chart-matrix](https://chartjs-chart-matrix.pages.dev/)                        | 2.0.1   | `matrix` — heatmaps                           |
| [chartjs-chart-sankey](https://github.com/kurkle/chartjs-chart-sankey)                 | 0.12.1  | `sankey` — flow diagrams                      |
| [chartjs-chart-treemap](https://chartjs-chart-treemap.pages.dev/)                      | 2.3.1   | `treemap` — hierarchical boxes                |
| [chartjs-chart-wordcloud](https://github.com/sgratzl/chartjs-chart-wordcloud)          | 4.4.3   | `wordcloud` — word clouds                     |
| [chartjs-chart-geo](https://github.com/sgratzl/chartjs-chart-geo)                      | 4.3.3   | `choropleth`, `bubbleMap` — geographic charts |
| [chartjs-chart-graph](https://github.com/sgratzl/chartjs-chart-graph)                  | 4.3.3   | `graph`, `forceDirectedGraph`, `dendrogram`, `tree` — networks |
| [chartjs-chart-venn](https://github.com/sgratzl/chartjs-chart-venn)                    | 4.3.3   | `venn`, `euler` — set diagrams                |

## Date adapter

| Plugin                                                                                       | Version | Use for                                       |
| -------------------------------------------------------------------------------------------- | ------- | --------------------------------------------- |
| [chartjs-adapter-date-fns](https://github.com/chartjs/chartjs-adapter-date-fns)              | 3.0.0   | Time-scale axes (`scales.x.type: "time"`)     |

## What's NOT bundled

- **Animation** — `options.animation` is forced OFF internally. The
  renderer needs a stable final frame to screenshot; animations would
  be cropped mid-transition.
- **Custom plugins you bring yourself** — the browser runs only the
  plugins listed above (loaded at page init). To add another plugin,
  see Developer Guide → [Adding a Chart.js plugin](/en/developer/adding-plugin).

## Forcing / overriding at render time

A Chart.js plugin can usually be enabled via
`options.plugins.<name>`. For per-dataset overrides (e.g.
`datalabels`) you can also set per-dataset properties
— see each plugin's upstream docs. `chartjs2img llm` includes the full
option tree for every bundled plugin.

---

<!-- source: src/llm-docs/** (via chartjs2img llm) -->

## chartjs2img — Usage Guide for LLMs

> **Disclaimer:** This documentation may contain inaccuracies or be out of date
> with the actual Chart.js and plugin versions used by this service. If you
> encounter an error message from Chart.js during rendering, **always trust the
> error message over this documentation**. Use the error feedback mechanism
> (stderr for CLI, X-Chart-Messages header for HTTP) to diagnose and correct
> your configuration.

This service renders Chart.js configurations (JSON) into PNG or JPEG images.
All Chart.js plugins listed below are **pre-loaded** — no extra setup needed.

### Important Constraints

- **JSON only** — no JavaScript functions, callbacks, or code. All config must be pure JSON.
- **Animations are forced OFF** — do not set animation options; they are overridden.
- **responsive and maintainAspectRatio** are forced internally.
- All plugins are **auto-registered**. Do not add `plugins: []` array in the config.

### CLI Input Format

The CLI accepts a **Chart.js config object directly** as JSON:

```json
{
  "type": "bar",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [{
      "label": "Revenue",
      "data": [100, 200, 150],
      "backgroundColor": "rgba(54, 162, 235, 0.7)"
    }]
  },
  "options": {
    "plugins": {
      "title": { "display": true, "text": "Monthly Revenue" }
    }
  }
}
```

Usage: `echo '<json>' | chartjs2img render -o chart.png`

### HTTP API Input Format

Wrap the Chart.js config in a `"chart"` field alongside optional render settings:

```json
{
  "chart": { "type": "bar", "data": { ... }, "options": { ... } },
  "width": 800,
  "height": 600,
  "devicePixelRatio": 2,
  "backgroundColor": "white",
  "format": "png",
  "quality": 90
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `chart` | object | **required** | Chart.js configuration |
| `width` | number | 800 | Image width in pixels |
| `height` | number | 600 | Image height in pixels |
| `devicePixelRatio` | number | 2 | Retina scaling factor |
| `backgroundColor` | string | `"white"` | CSS color or `"transparent"` |
| `format` | string | `"png"` | `"png"` or `"jpeg"` |
| `quality` | number | 90 | JPEG quality (0-100) |

### Error Feedback

Errors and warnings from Chart.js are captured and returned:
- **CLI**: printed to stderr as `[chart ERROR]` or `[chart WARN]`
- **HTTP**: returned in the `X-Chart-Messages` response header as a JSON array of `{level, message}`

## Chart.js 4.4.9 — Core Configuration

### Top-Level Structure

```json
{
  "type": "<chart-type>",
  "data": {
    "labels": ["Label1", "Label2", ...],
    "datasets": [{ "label": "Series", "data": [...], ... }]
  },
  "options": {
    "indexAxis": "x",
    "plugins": { ... },
    "scales": { ... },
    "layout": { "padding": 10 },
    "interaction": { "mode": "nearest", "intersect": true }
  }
}
```

### Built-in Chart Types

`bar`, `line`, `pie`, `doughnut`, `radar`, `polarArea`, `scatter`, `bubble`

### Bar Chart Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | number[] | **required** | Data values |
| `label` | string | `""` | Dataset label |
| `backgroundColor` | Color\|Color[] | — | Bar fill color(s) |
| `borderColor` | Color\|Color[] | — | Bar border color(s) |
| `borderWidth` | number\|object | `0` | Border width (`{top,right,bottom,left}`) |
| `borderRadius` | number\|object | `0` | Corner radius |
| `borderSkipped` | string\|boolean | `"start"` | Which edge to skip (`"start"`, `"end"`, `"middle"`, `"bottom"`, `"left"`, `"top"`, `"right"`, `false`) |
| `barPercentage` | number | `0.9` | Bar width as fraction of category |
| `categoryPercentage` | number | `0.8` | Category width as fraction of available space |
| `barThickness` | number\|string | — | Fixed bar width in px, or `"flex"` |
| `maxBarThickness` | number | — | Maximum bar width in px |
| `minBarLength` | number | — | Minimum bar length in px |
| `indexAxis` | string | `"x"` | Set to `"y"` for horizontal bars |
| `grouped` | boolean | `true` | Group bars of different datasets |
| `stack` | string | — | Stack group identifier |
| `order` | number | `0` | Drawing order |
| `base` | number | — | Base value for the bar |

### Line Chart Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | number[]\|{x,y}[] | **required** | Data values |
| `label` | string | `""` | Dataset label |
| `backgroundColor` | Color | — | Fill color (when `fill` is set) |
| `borderColor` | Color | — | Line color |
| `borderWidth` | number | `3` | Line width |
| `borderDash` | number[] | `[]` | Dash pattern (e.g., `[5, 5]`) |
| `borderDashOffset` | number | `0` | Dash offset |
| `borderCapStyle` | string | `"butt"` | Line cap: `"butt"`, `"round"`, `"square"` |
| `borderJoinStyle` | string | `"miter"` | Line join: `"bevel"`, `"round"`, `"miter"` |
| `fill` | boolean\|string\|object | `false` | Fill area. `true`, `"origin"`, `"start"`, `"end"`, `{target, above, below}` |
| `tension` | number | `0` | Bezier curve tension (`0` = straight, `0.4` = smooth) |
| `stepped` | boolean\|string | `false` | Stepped line: `true`, `"before"`, `"after"`, `"middle"` |
| `cubicInterpolationMode` | string | `"default"` | `"default"` or `"monotone"` |
| `showLine` | boolean | `true` | Draw the line |
| `spanGaps` | boolean\|number | — | Connect across null values |
| `pointBackgroundColor` | Color | — | Point fill |
| `pointBorderColor` | Color | — | Point border |
| `pointBorderWidth` | number | `1` | Point border width |
| `pointRadius` | number | `3` | Point size (`0` to hide) |
| `pointStyle` | string | `"circle"` | `"circle"`, `"cross"`, `"crossRot"`, `"dash"`, `"line"`, `"rect"`, `"rectRounded"`, `"rectRot"`, `"star"`, `"triangle"`, `false` |
| `pointHitRadius` | number | `1` | Hit detection radius |
| `pointHoverRadius` | number | `4` | Hover size |
| `order` | number | `0` | Drawing order |
| `stack` | string | — | Stack group (for stacked area) |

### Pie / Doughnut Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | number[] | **required** | Slice values |
| `backgroundColor` | Color[] | — | Slice colors |
| `borderColor` | Color | `"#fff"` | Border between slices |
| `borderWidth` | number | `2` | Border width |
| `borderRadius` | number\|object | `0` | Slice corner radius |
| `borderAlign` | string | `"center"` | `"center"` or `"inner"` |
| `circumference` | number | — | Sweep angle per dataset (degrees) |
| `hoverOffset` | number | `0` | Hover expansion |
| `offset` | number\|number[] | `0` | Slice offset from center |
| `rotation` | number | — | Starting angle (degrees) |
| `spacing` | number | `0` | Gap between slices |
| `weight` | number | `1` | Relative thickness (multi-dataset) |

For doughnut, also set `options.cutout` (default `"50%"`) to control the hole size.

### Radar Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | number[] | **required** | Values per axis |
| `label` | string | `""` | Dataset label |
| `backgroundColor` | Color | — | Fill color |
| `borderColor` | Color | — | Line color |
| `borderWidth` | number | `3` | Line width |
| `fill` | boolean\|string | `false` | Fill area |
| `pointBackgroundColor` | Color | — | Point fill |
| `pointBorderColor` | Color | — | Point border |
| `pointRadius` | number | `3` | Point size |
| `pointStyle` | string | `"circle"` | Point shape |
| `tension` | number | `0` | Curve tension |

### Polar Area Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | number[] | **required** | Slice values |
| `backgroundColor` | Color[] | — | Slice colors |
| `borderColor` | Color | `"#fff"` | Border color |
| `borderWidth` | number | `2` | Border width |

### Scatter Dataset

Same as Line chart, but `showLine` defaults to `false`. Data must be `{x, y}` objects:

```json
{ "data": [{"x": 10, "y": 20}, {"x": 15, "y": 10}] }
```

### Bubble Dataset

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | {x,y,r}[] | **required** | Bubble positions and radius |
| `backgroundColor` | Color | — | Fill color |
| `borderColor` | Color | — | Border color |
| `borderWidth` | number | `3` | Border width |
| `pointStyle` | string | `"circle"` | Marker shape |
| `radius` | number | `3` | Default radius (overridden by `r` in data) |
| `rotation` | number | `0` | Rotation in degrees |

### Scales Configuration

`options.scales` is an object where keys are scale IDs (e.g., `"x"`, `"y"`, `"r"`):

```json
{
  "scales": {
    "x": { "type": "category", "title": { "display": true, "text": "Month" } },
    "y": { "type": "linear", "beginAtZero": true, "max": 100 }
  }
}
```

#### Scale Types

| Type | Usage | Key Properties |
|------|-------|----------------|
| `linear` | Numeric data | `min`, `max`, `beginAtZero`, `suggestedMin`, `suggestedMax`, `grace` |
| `logarithmic` | Log scale | `min`, `max` |
| `category` | Discrete labels | `labels`, `min`, `max` |
| `time` | Dates (requires dayjs adapter) | `time.unit`, `time.displayFormats`, `time.parser`, `time.tooltipFormat` |
| `timeseries` | Even-spaced time data | Same as `time` |
| `radialLinear` | Radar / polar area | `angleLines`, `pointLabels`, `ticks`, `min`, `max` |

#### Common Scale Options

| Property | Type | Description |
|----------|------|-------------|
| `type` | string | Scale type (see above) |
| `display` | boolean | Show the scale |
| `position` | string | `"top"`, `"left"`, `"bottom"`, `"right"` |
| `min` | number | Minimum value |
| `max` | number | Maximum value |
| `reverse` | boolean | Reverse the scale |
| `stacked` | boolean\|string | Enable stacking |
| `offset` | boolean | Extra space at edges |
| `title.display` | boolean | Show axis title |
| `title.text` | string | Axis title text |
| `title.color` | Color | Title color |
| `title.font` | Font | Title font |
| `ticks.display` | boolean | Show tick labels |
| `ticks.color` | Color | Tick label color |
| `ticks.font` | Font | Tick label font |
| `ticks.stepSize` | number | Fixed step between ticks |
| `ticks.maxTicksLimit` | number | Max number of ticks |
| `ticks.precision` | number | Decimal precision |
| `grid.display` | boolean | Show grid lines |
| `grid.color` | Color | Grid line color |
| `grid.lineWidth` | number | Grid line width |
| `border.display` | boolean | Show axis border line |
| `border.color` | Color | Border color |

### Title Plugin (`options.plugins.title`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `display` | boolean | `false` | Show the title |
| `text` | string\|string[] | `""` | Title text (array for multiline) |
| `color` | Color | — | Text color |
| `font` | Font | `{weight:"bold"}` | Font config |
| `position` | string | `"top"` | `"top"`, `"left"`, `"bottom"`, `"right"` |
| `align` | string | `"center"` | `"start"`, `"center"`, `"end"` |
| `padding` | number\|object | `10` | Padding around title |
| `fullSize` | boolean | `true` | Span full width/height |

### Subtitle Plugin (`options.plugins.subtitle`)

Same options as title. Rendered below the title.

### Legend Plugin (`options.plugins.legend`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `display` | boolean | `true` | Show the legend |
| `position` | string | `"top"` | `"top"`, `"left"`, `"bottom"`, `"right"` |
| `align` | string | `"center"` | `"start"`, `"center"`, `"end"` |
| `reverse` | boolean | `false` | Reverse dataset order |
| `labels.boxWidth` | number | `40` | Color box width |
| `labels.boxHeight` | number | — | Color box height |
| `labels.color` | Color | — | Text color |
| `labels.font` | Font | — | Font config |
| `labels.padding` | number | `10` | Padding between items |
| `labels.usePointStyle` | boolean | `false` | Use point style instead of box |
| `labels.pointStyle` | string | — | Override point style |
| `title.display` | boolean | `false` | Show legend title |
| `title.text` | string | — | Legend title text |

### Tooltip Plugin (`options.plugins.tooltip`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable tooltips |
| `mode` | string | `interaction.mode` | Interaction mode (inherits from `options.interaction.mode`, default `"nearest"`) |
| `intersect` | boolean | `interaction.intersect` | Require direct hover (inherits from `options.interaction.intersect`, default `true`) |
| `position` | string | `"average"` | `"average"` or `"nearest"` |
| `backgroundColor` | Color | `"rgba(0,0,0,0.8)"` | Background |
| `titleColor` | Color | `"#fff"` | Title color |
| `titleFont` | Font | `{weight:"bold"}` | Title font |
| `bodyColor` | Color | `"#fff"` | Body text color |
| `bodyFont` | Font | — | Body font |
| `footerColor` | Color | `"#fff"` | Footer color |
| `cornerRadius` | number | `6` | Corner radius |
| `displayColors` | boolean | `true` | Show color boxes |
| `borderColor` | Color | — | Border color |
| `borderWidth` | number | `0` | Border width |
| `padding` | number\|object | `6` | Inner padding |
| `caretSize` | number | `5` | Caret triangle size |
| `usePointStyle` | boolean | `false` | Use point style in tooltip |
| `xAlign` | string | — | `"left"`, `"center"`, `"right"` |
| `yAlign` | string | — | `"top"`, `"center"`, `"bottom"` |

### Font Object

Wherever `Font` is used:

```json
{ "family": "Arial", "size": 14, "style": "normal", "weight": "bold", "lineHeight": 1.2 }
```

### Color Values

Any CSS color string: `"red"`, `"#ff0000"`, `"rgb(255,0,0)"`, `"rgba(255,0,0,0.5)"`, `"hsl(0,100%,50%)"`

## chartjs-plugin-datalabels 2.2.0 — Display Values on Chart Elements

Configure globally via `options.plugins.datalabels` or per-dataset via `dataset.datalabels`.

> **Note:** In this service, all option values must be JSON-serializable. Function-based (scriptable) options are not available.

### Options

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `display` | boolean\|string | `true` | Show labels. Set `"auto"` to hide overlapping labels |
| `align` | string\|number | `"center"` | Label position: `"center"`, `"start"`, `"end"`, `"right"`, `"bottom"`, `"left"`, `"top"`, or degrees (0-360) |
| `anchor` | string | `"center"` | Anchor point on the element: `"center"`, `"start"`, `"end"` |
| `offset` | number | `4` | Distance (px) from anchor point |
| `rotation` | number | `0` | Label rotation in degrees |
| `clamp` | boolean | `false` | Keep label within chart area |
| `clip` | boolean | `false` | Clip label to chart area |
| `opacity` | number | `1` | Label opacity (0-1) |

### Text Styling

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `color` | Color | Chart.defaults.color | Text color |
| `font` | Font | inherits from Chart.js defaults | Font: `{family, size, style, weight, lineHeight}`. Default weight: `"normal"`, lineHeight: `1.2` |
| `textAlign` | string | `"start"` | Multi-line alignment: `"start"`, `"center"`, `"end"` |
| `textStrokeColor` | Color | inherits from `color` | Text stroke (outline) color |
| `textStrokeWidth` | number | `0` | Text stroke width |
| `textShadowBlur` | number | `0` | Text shadow blur radius |
| `textShadowColor` | Color | inherits from `color` | Text shadow color |

### Background & Border

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `backgroundColor` | Color\|null | `null` | Label background color |
| `borderColor` | Color\|null | `null` | Label border color |
| `borderRadius` | number | `0` | Border corner radius |
| `borderWidth` | number | `0` | Border width |
| `padding` | number\|object | `4` | Inner padding. Number or `{top, right, bottom, left}` |

### Multiple Labels

Use `labels` to show multiple labels per data point:

```json
{
  "plugins": {
    "datalabels": {
      "labels": {
        "value": {
          "color": "blue",
          "font": { "weight": "bold" }
        },
        "name": {
          "color": "gray",
          "align": "top",
          "font": { "size": 10 }
        }
      }
    }
  }
}
```

### Example

```json
{
  "type": "bar",
  "data": {
    "labels": ["A", "B", "C"],
    "datasets": [{
      "data": [10, 20, 15],
      "backgroundColor": ["#36a2eb", "#ff6384", "#ffce56"]
    }]
  },
  "options": {
    "plugins": {
      "datalabels": {
        "display": true,
        "color": "#333",
        "anchor": "end",
        "align": "top",
        "font": { "weight": "bold", "size": 14 }
      }
    }
  }
}
```

## chartjs-plugin-annotation 3.1.0 — Lines, Boxes, Labels as Overlays

Configure via `options.plugins.annotation.annotations`. The value is an object where each key is an annotation ID.

### Common Options (All Types)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `type` | string | — | `"line"`, `"box"`, `"ellipse"`, `"point"`, `"polygon"`, `"label"` |
| `display` | boolean | `true` | Visibility |
| `drawTime` | string | `"afterDatasetsDraw"` | `"beforeDraw"`, `"beforeDatasetsDraw"`, `"afterDatasetsDraw"`, `"afterDraw"` |
| `xScaleID` | string | `undefined` | X scale to bind to (defaults to detecting `"x"` axis) |
| `yScaleID` | string | `undefined` | Y scale to bind to (defaults to detecting `"y"` axis) |
| `xMin` | number\|string | — | Left bound (scale value) |
| `xMax` | number\|string | — | Right bound |
| `yMin` | number\|string | — | Bottom bound |
| `yMax` | number\|string | — | Top bound |
| `backgroundColor` | Color | `options.color` | Fill color |
| `borderColor` | Color | `options.color` | Stroke color |
| `borderWidth` | number | type-dependent | Stroke width (line: `2`, label: `0`, others: `1`) |
| `borderDash` | number[] | `[]` | Dash pattern (e.g., `[6, 6]`) |
| `z` | number | `0` | Drawing stack order |
| `adjustScaleRange` | boolean | `true` | Expand scale if annotation is out of range |

### Line Annotation

Draws a horizontal or vertical line (or angled line).

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `scaleID` | string | — | Scale to position on (`"x"` or `"y"`) |
| `value` | number\|string | — | Position on the scale |
| `endValue` | number\|string | — | End position (for angled lines) |
| `borderWidth` | number | `2` | Line width |
| `curve` | boolean | `false` | Draw as Bezier curve |
| `controlPoint` | number\|string\|object | `{y:"-50%"}` | Bezier curve control point (when `curve` is `true`) |
| `label` | object | — | Label on the line (see below) |
| `arrowHeads` | object | — | Arrow heads at line ends |

**Line label:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `display` | boolean | `false` | Show label |
| `content` | string\|string[] | — | Label text |
| `color` | Color | `"#fff"` | Text color |
| `backgroundColor` | Color | `"rgba(0,0,0,0.8)"` | Background |
| `font` | Font | `{weight:"bold"}` | Font config |
| `padding` | number\|object | `6` | Inner padding |
| `borderRadius` | number | `6` | Corner radius |
| `textAlign` | string | `"center"` | Text alignment |
| `position` | string | `"center"` | `"start"`, `"center"`, `"end"`, or percentage `"25%"` |
| `rotation` | number\|string | `0` | Rotation (`"auto"` to follow line) |
| `xAdjust` | number | `0` | X pixel offset |
| `yAdjust` | number | `0` | Y pixel offset |

**Arrow heads:**

```json
{ "arrowHeads": { "end": { "display": true, "length": 16, "width": 8 } } }
```

### Box Annotation

Draws a rectangular region.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `borderRadius` | number\|object | `0` | Corner radius |
| `rotation` | number | `0` | Rotation in degrees |
| `label` | object | — | Inner label (similar to line label, but `color` defaults to `"black"`, `textAlign` defaults to `"start"`) |

Defined by `xMin`, `xMax`, `yMin`, `yMax`.

### Ellipse Annotation

Draws an elliptical region. Same bounds as box.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `rotation` | number | `0` | Rotation in degrees |
| `label` | object | — | Inner label (same options as box label) |

### Point Annotation

Draws a marker at a specific data point.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `xValue` | number\|string | — | X coordinate |
| `yValue` | number\|string | — | Y coordinate |
| `radius` | number | `10` | Point size in px |
| `pointStyle` | string | `"circle"` | Marker style |
| `rotation` | number | `0` | Rotation |
| `xAdjust` | number | `0` | X pixel offset |
| `yAdjust` | number | `0` | Y pixel offset |

### Polygon Annotation

Draws a regular polygon.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `xValue` | number\|string | — | Center X |
| `yValue` | number\|string | — | Center Y |
| `radius` | number | `10` | Size in px |
| `sides` | number | `3` | Number of sides |
| `rotation` | number | `0` | Rotation |

### Label Annotation

Draws a standalone text label (not attached to a line/box).

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `xValue` | number\|string | — | X coordinate |
| `yValue` | number\|string | — | Y coordinate |
| `content` | string\|string[] | — | Text content (array for multiline) |
| `color` | Color | `"black"` | Text color |
| `font` | Font | — | Font config |
| `textAlign` | string | `"center"` | `"left"`, `"center"`, `"right"` |
| `backgroundColor` | Color | — | Background |
| `borderRadius` | number | `0` | Corner radius |
| `padding` | number\|object | `6` | Padding |
| `position` | string | `"center"` | Position within bounds |
| `rotation` | number | `0` | Rotation |
| `width` | number\|string | — | Fixed width |
| `height` | number\|string | — | Fixed height |
| `xAdjust` | number | `0` | X offset |
| `yAdjust` | number | `0` | Y offset |

### Example: Threshold Line with Label

```json
{
  "options": {
    "plugins": {
      "annotation": {
        "annotations": {
          "threshold": {
            "type": "line",
            "yMin": 75,
            "yMax": 75,
            "borderColor": "red",
            "borderWidth": 2,
            "borderDash": [6, 6],
            "label": {
              "display": true,
              "content": "Target: 75",
              "position": "end",
              "backgroundColor": "red",
              "color": "white"
            }
          }
        }
      }
    }
  }
}
```

## chartjs-plugin-zoom 2.2.0 — Pan & Zoom

Configure via `options.plugins.zoom`.

> **Note:** In server-side rendering, zoom/pan are mainly useful for setting **initial ranges** via scale limits. Interactive zoom (wheel, drag, pinch) has no effect on static images.

### Zoom Configuration

```json
{
  "plugins": {
    "zoom": {
      "zoom": {
        "wheel": { "enabled": false },
        "drag": { "enabled": false },
        "pinch": { "enabled": false },
        "mode": "xy"
      },
      "pan": {
        "enabled": false,
        "mode": "xy"
      },
      "limits": {
        "x": { "min": 0, "max": 100 },
        "y": { "min": 0, "max": 1000 }
      }
    }
  }
}
```

### Pan Options (`pan`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable panning |
| `mode` | string | `"xy"` | `"x"`, `"y"`, or `"xy"` |
| `modifierKey` | string | `null` | Required key: `"ctrl"`, `"alt"`, `"shift"`, `"meta"` |
| `threshold` | number | `10` | Minimum pixels before panning starts |
| `scaleMode` | string | — | Scale-specific panning: `"x"`, `"y"`, `"xy"` |

### Zoom Options (`zoom`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `mode` | string | `"xy"` | Zoom directions: `"x"`, `"y"`, or `"xy"` |
| `scaleMode` | string | — | Scale-specific zoom |

**Wheel sub-options (`zoom.wheel`):**

| Property | Type | Default |
|----------|------|---------|
| `enabled` | boolean | `false` |
| `speed` | number | `0.1` |
| `modifierKey` | string | `null` |

**Drag sub-options (`zoom.drag`):**

| Property | Type | Default |
|----------|------|---------|
| `enabled` | boolean | `false` |
| `backgroundColor` | Color | `"rgba(225,225,225,0.3)"` |
| `borderColor` | Color | `"rgba(225,225,225)"` |
| `borderWidth` | number | `0` |
| `threshold` | number | `0` |
| `modifierKey` | string | `null` |
| `drawTime` | string | `"beforeDatasetsDraw"` |

**Pinch sub-options (`zoom.pinch`):**

| Property | Type | Default |
|----------|------|---------|
| `enabled` | boolean | `false` |

### Limits (`limits`)

Per-axis limits (e.g., `limits.x`, `limits.y`):

| Property | Type | Description |
|----------|------|-------------|
| `min` | number\|string | Minimum scale value. `"original"` = initial value |
| `max` | number\|string | Maximum scale value. `"original"` = initial value |
| `minRange` | number | Smallest allowed range (max zoom level) |

## chartjs-plugin-gradient 0.6.1 — Gradient Fills

Configure per-dataset via a `gradient` property.

### Dataset Configuration

```json
{
  "datasets": [{
    "label": "Gradient Line",
    "data": [10, 25, 50, 75, 100],
    "borderColor": "blue",
    "gradient": {
      "backgroundColor": {
        "axis": "y",
        "colors": {
          "0": "rgba(54, 162, 235, 0.0)",
          "50": "rgba(54, 162, 235, 0.5)",
          "100": "rgba(54, 162, 235, 1.0)"
        }
      },
      "borderColor": {
        "axis": "x",
        "colors": {
          "0": "red",
          "100": "blue"
        }
      }
    }
  }]
}
```

### Options

| Property | Type | Description |
|----------|------|-------------|
| `gradient.backgroundColor.axis` | `"x"\|"y"` | Gradient direction for fill |
| `gradient.backgroundColor.colors` | object | Map of scale value to CSS color |
| `gradient.borderColor.axis` | `"x"\|"y"` | Gradient direction for stroke |
| `gradient.borderColor.colors` | object | Map of scale value to CSS color |

The keys in `colors` correspond to **scale values** (not pixel positions). The plugin interpolates colors between defined stops along the specified axis.

### Supported Chart Types

Works with: `line`, `bar`, `radar`, `polarArea`, and any type that uses `backgroundColor` or `borderColor`.

## chartjs-chart-treemap 2.3.1 — Treemap Charts

Chart type: `"treemap"`

### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `tree` | number[]\|object[] | **required** | Source data |
| `key` | string | — | Property name for numerical values (when `tree` is object[]) |
| `groups` | string[] | — | Hierarchy grouping keys (e.g., `["category", "subcategory"]`) |
| `sumKeys` | string[] | — | Additional keys to aggregate |
| `treeLeafKey` | string | `"_leaf"` | Key identifying leaf nodes |
| `label` | string | — | Dataset label |
| `backgroundColor` | Color | — | Rectangle fill color |
| `borderColor` | Color | — | Rectangle border color |
| `borderWidth` | number\|object | `0` | Border width |
| `borderRadius` | number | `0` | Corner radius |
| `spacing` | number | `0.5` | Gap between rectangles (px) |

### Labels (inside rectangles)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `labels.display` | boolean | `false` | Show labels |
| `labels.align` | string | `"center"` | Horizontal alignment |
| `labels.position` | string | `"middle"` | Vertical position |
| `labels.color` | Color\|Color[] | `"black"` | Text color |
| `labels.font` | Font\|Font[] | — | Font config |
| `labels.overflow` | string | `"cut"` | `"cut"`, `"hidden"`, `"fit"` |
| `labels.padding` | number | `3` | Padding |

### Captions (group headers)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `captions.display` | boolean | `true` | Show group captions |
| `captions.align` | string | — | Text alignment |
| `captions.color` | Color | `"black"` | Text color |
| `captions.font` | Font | — | Font config |
| `captions.padding` | number | `3` | Padding |

### Dividers (between groups)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `dividers.display` | boolean | `false` | Show dividers |
| `dividers.lineColor` | Color | `"black"` | Line color |
| `dividers.lineWidth` | number | `1` | Line width |
| `dividers.lineDash` | number[] | `[]` | Dash pattern |

### Example: Flat Data

```json
{
  "type": "treemap",
  "data": {
    "datasets": [{
      "tree": [15, 6, 6, 5, 4, 3, 2, 2],
      "backgroundColor": ["#36a2eb", "#ff6384", "#ffce56", "#4bc0c0", "#9966ff", "#ff9f40", "#c9cbcf", "#7bc8a4"],
      "borderWidth": 1,
      "borderColor": "white",
      "labels": {
        "display": true,
        "color": "white",
        "font": { "weight": "bold" }
      }
    }]
  }
}
```

### Example: Grouped Object Data

```json
{
  "type": "treemap",
  "data": {
    "datasets": [{
      "tree": [
        { "category": "A", "sub": "x", "value": 10 },
        { "category": "A", "sub": "y", "value": 20 },
        { "category": "B", "sub": "x", "value": 15 },
        { "category": "B", "sub": "y", "value": 5 }
      ],
      "key": "value",
      "groups": ["category", "sub"],
      "backgroundColor": "#36a2eb",
      "borderWidth": 2,
      "borderColor": "white",
      "captions": { "display": true, "color": "black" },
      "labels": { "display": true, "color": "white" }
    }]
  }
}
```

## chartjs-chart-matrix 2.0.1 — Heatmap / Matrix Charts

Chart type: `"matrix"`

### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | {x,y,v}[] | **required** | Array of cell objects |
| `label` | string | — | Dataset identifier |
| `backgroundColor` | Color | — | Cell fill color |
| `borderColor` | Color | — | Cell border color |
| `borderWidth` | number | — | Border thickness |
| `width` | number | — | Cell width in px (also accepts function in JS, but only number in JSON) |
| `height` | number | — | Cell height in px (also accepts function in JS, but only number in JSON) |

### Data Format

Each data point is an object with `x`, `y` coordinates and an optional `v` (value):

```json
{ "data": [
  { "x": 1, "y": 1, "v": 10 },
  { "x": 2, "y": 1, "v": 25 },
  { "x": 1, "y": 2, "v": 5 },
  { "x": 2, "y": 2, "v": 40 }
]}
```

### Example: Heatmap

```json
{
  "type": "matrix",
  "data": {
    "datasets": [{
      "label": "Heatmap",
      "data": [
        { "x": 1, "y": 1, "v": 5 },
        { "x": 2, "y": 1, "v": 15 },
        { "x": 3, "y": 1, "v": 25 },
        { "x": 1, "y": 2, "v": 10 },
        { "x": 2, "y": 2, "v": 30 },
        { "x": 3, "y": 2, "v": 20 }
      ],
      "backgroundColor": "rgba(54, 162, 235, 0.7)",
      "borderColor": "white",
      "borderWidth": 1,
      "width": 40,
      "height": 40
    }]
  },
  "options": {
    "scales": {
      "x": { "type": "linear", "position": "bottom", "offset": true },
      "y": { "type": "linear", "position": "left", "offset": true }
    }
  }
}
```

> **Tip:** To create a true heatmap with color mapping, use different `backgroundColor` values per data point based on the `v` value. Since this service only accepts JSON (no functions), you must pre-compute colors for each cell.

## chartjs-chart-sankey 0.12.1 — Sankey Flow Diagrams

Chart type: `"sankey"`

### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | {from,to,flow}[] | **required** | Flow connections |
| `colorFrom` | Color | — | Source node/flow color |
| `colorTo` | Color | — | Target node/flow color |
| `hoverColorFrom` | Color | — | Source hover color |
| `hoverColorTo` | Color | — | Target hover color |
| `colorMode` | string | `"gradient"` | `"gradient"`, `"from"`, or `"to"` |
| `alpha` | number | `0.5` | Flow band transparency (0-1) |
| `labels` | object | — | Node ID to display name mapping |
| `priority` | object | — | Node ordering (lower = higher priority) |
| `column` | object | — | Override column placement per node |
| `size` | string | `"max"` | `"max"` (prevent overlap) or `"min"` (allow overlap) |
| `nodeWidth` | number | `10` | Width of each node bar in px |
| `nodePadding` | number | `10` | Vertical padding between nodes in px |
| `borderWidth` | number | `1` | Node border width |
| `borderColor` | Color | `"black"` | Node border color |
| `color` | Color | `"black"` | Default node color |

### Data Format

Each flow is defined by source (`from`), target (`to`), and volume (`flow`):

```json
{ "data": [
  { "from": "Oil", "to": "Fossil Fuels", "flow": 15 },
  { "from": "Coal", "to": "Fossil Fuels", "flow": 25 },
  { "from": "Fossil Fuels", "to": "Energy", "flow": 40 },
  { "from": "Solar", "to": "Renewables", "flow": 10 },
  { "from": "Renewables", "to": "Energy", "flow": 10 }
]}
```

### Labels Mapping

Map internal node IDs to display names:

```json
{ "labels": { "Oil": "Crude Oil", "Coal": "Coal Mining", "Solar": "Solar Power" } }
```

### Column Override

Force specific nodes into columns (0-based):

```json
{ "column": { "Oil": 0, "Coal": 0, "Fossil Fuels": 1, "Energy": 2 } }
```

### Example

```json
{
  "type": "sankey",
  "data": {
    "datasets": [{
      "data": [
        { "from": "A", "to": "B", "flow": 10 },
        { "from": "A", "to": "C", "flow": 5 },
        { "from": "B", "to": "D", "flow": 10 },
        { "from": "C", "to": "D", "flow": 5 }
      ],
      "colorFrom": "#36a2eb",
      "colorTo": "#ff6384",
      "colorMode": "gradient",
      "labels": { "A": "Source", "B": "Process 1", "C": "Process 2", "D": "Output" }
    }]
  }
}
```

## chartjs-chart-wordcloud 4.4.3 — Word Cloud Charts

Chart type: `"wordCloud"`

### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `label` | string | — | Dataset identifier |
| `data` | number[] | **required** | Font sizes in px for each word |

### Data Structure

Words come from `data.labels`, sizes come from `datasets[].data`:

```json
{
  "type": "wordCloud",
  "data": {
    "labels": ["JavaScript", "Python", "Java", "TypeScript", "Go", "Rust"],
    "datasets": [{
      "data": [60, 50, 45, 40, 30, 25]
    }]
  }
}
```

### Word Element Options

Set via `options.elements.word` or per-dataset:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `color` | Color | — | Word text color |
| `family` | string | — | Font family |
| `style` | string | `"normal"` | Font style |
| `weight` | string | `"normal"` | Font weight |
| `rotate` | number | random | Rotation angle in degrees |
| `rotationSteps` | number | `2` | Number of rotation steps |
| `minRotation` | number | `-90` | Minimum rotation |
| `maxRotation` | number | `0` | Maximum rotation |
| `padding` | number | `1` | Padding around each word (layout spacing) |

### Controller Options

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `fit` | boolean | `true` | Scale word cloud to fit chart bounds |

### Example

```json
{
  "type": "wordCloud",
  "data": {
    "labels": ["Chart.js", "D3", "Plotly", "Recharts", "Highcharts", "Vega", "ECharts", "ApexCharts"],
    "datasets": [{
      "data": [90, 80, 60, 50, 45, 35, 70, 40],
      "color": ["#36a2eb", "#ff6384", "#ffce56", "#4bc0c0", "#9966ff", "#ff9f40", "#c9cbcf", "#7bc8a4"]
    }]
  },
  "options": {
    "elements": {
      "word": {
        "minRotation": 0,
        "maxRotation": 0,
        "padding": 3
      }
    },
    "plugins": {
      "legend": { "display": false }
    }
  }
}
```

## chartjs-chart-geo 4.3.3 — Choropleth & Bubble Map Charts

Chart types: `"choropleth"`, `"bubbleMap"`

> **Note:** GeoJSON feature data must be provided inline in the JSON config. You can obtain GeoJSON from sources like Natural Earth or TopoJSON. The features must be included directly in the dataset `data` array — there is no URL-loading mechanism.

### Choropleth Chart

Renders colored regions based on values.

#### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | {feature,value}[] | **required** | GeoJSON features with values |
| `outline` | GeoJSON Feature[] | — | Features used to compute map bounds |
| `showOutline` | boolean | `false` | Display outline border |
| `backgroundColor` | Color | — | Default fill color |
| `borderColor` | Color | — | Region border color |
| `borderWidth` | number | — | Border thickness |

#### Data Format

```json
{
  "data": [
    { "feature": { "type": "Feature", "geometry": { ... }, "properties": { "name": "France" } }, "value": 67 },
    { "feature": { "type": "Feature", "geometry": { ... }, "properties": { "name": "Germany" } }, "value": 83 }
  ]
}
```

#### Scales

| Scale ID | Type | Key Options |
|----------|------|-------------|
| `projection` (or `x`) | `"projection"` | `projection`: map projection type |
| `color` (or `y`) | `"color"` | `quantize`: number of discrete color steps |

Projection types: `"albersUsa"`, `"equalEarth"`, `"equirectangular"`, `"naturalEarth1"`, `"mercator"`, `"albers"`, `"azimuthalEqualArea"`, `"azimuthalEquidistant"`, `"conicConformal"`, `"conicEqualArea"`, `"conicEquidistant"`, `"gnomonic"`, `"orthographic"`, `"stereographic"`, `"transverseMercator"`

#### Scale Configuration

```json
{
  "scales": {
    "projection": {
      "axis": "x",
      "projection": "equalEarth"
    },
    "color": {
      "axis": "x",
      "quantize": 5,
      "display": false
    }
  }
}
```

### BubbleMap Chart

Renders bubbles at geographic coordinates.

#### Data Format

```json
{
  "data": [
    { "longitude": 2.35, "latitude": 48.86, "value": 2161 },
    { "longitude": 13.4, "latitude": 52.52, "value": 3645 }
  ]
}
```

| Property | Type | Description |
|----------|------|-------------|
| `longitude` | number | Longitude coordinate |
| `latitude` | number | Latitude coordinate |
| `value` | number | Maps to bubble radius |

#### Dataset Properties (BubbleMap)

Same as choropleth for `outline`, `showOutline`. Data points use `{longitude, latitude, value}` instead of `{feature, value}`.

## chartjs-chart-graph 4.3.3 — Network & Tree Graphs

Chart types: `"graph"`, `"forceDirectedGraph"`, `"dendrogram"`, `"tree"`

### Common Dataset Properties

| Property | Type | Description |
|----------|------|-------------|
| `data` | object[] | Node objects |
| `edges` | {source,target}[] | Edge connections (by array index) |
| `labels` | string[] | Node labels |

### Node Styling

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `pointBackgroundColor` | Color | — | Node fill color |
| `pointBorderColor` | Color | — | Node border color |
| `pointRadius` | number | `3` | Node size in px |
| `pointStyle` | string | `"circle"` | Node shape |

### Edge Styling

Set via `options.elements.edge` or per-dataset:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `borderColor` | Color | — | Edge color |
| `borderWidth` | number | — | Edge width |

### graph (Manual Layout)

Nodes require explicit `x`, `y` coordinates:

```json
{
  "type": "graph",
  "data": {
    "labels": ["A", "B", "C"],
    "datasets": [{
      "data": [
        { "x": 0, "y": 0 },
        { "x": 100, "y": 50 },
        { "x": 50, "y": 100 }
      ],
      "edges": [
        { "source": 0, "target": 1 },
        { "source": 1, "target": 2 },
        { "source": 2, "target": 0 }
      ],
      "pointRadius": 8,
      "pointBackgroundColor": "#36a2eb"
    }]
  }
}
```

### forceDirectedGraph (Auto Layout)

Nodes are positioned by physics simulation. No coordinates needed:

```json
{
  "type": "forceDirectedGraph",
  "data": {
    "labels": ["A", "B", "C", "D", "E"],
    "datasets": [{
      "data": [{}, {}, {}, {}, {}],
      "edges": [
        { "source": 0, "target": 1 },
        { "source": 0, "target": 2 },
        { "source": 1, "target": 3 },
        { "source": 2, "target": 4 }
      ],
      "pointRadius": 10,
      "pointBackgroundColor": "#36a2eb"
    }]
  }
}
```

#### Simulation Options

Set via `options.simulation` (or dataset `simulation`):

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `autoRestart` | boolean | `true` | Restart on data change |
| `initialIterations` | number | — | Pre-render iterations (higher = more stable layout) |
| `forces.center` | object | enabled | Centering force: `{x, y}` |
| `forces.collide` | object | disabled | Collision: `{radius, strength}` |
| `forces.link` | object | enabled | Spring: `{distance, strength}` |
| `forces.manyBody` | object | enabled | Repulsion: `{strength, theta, distanceMin, distanceMax}` |
| `forces.x` | object | disabled | X pull: `{x, strength}` |
| `forces.y` | object | disabled | Y pull: `{y, strength}` |
| `forces.radial` | object | disabled | Circular: `{radius, x, y, strength}` |

### dendrogram (Hierarchical Cluster)

Uses `parent` index to define hierarchy:

```json
{
  "type": "dendrogram",
  "data": {
    "labels": ["Root", "A", "B", "A1", "A2", "B1"],
    "datasets": [{
      "data": [
        {},
        { "parent": 0 },
        { "parent": 0 },
        { "parent": 1 },
        { "parent": 1 },
        { "parent": 2 }
      ],
      "pointRadius": 6,
      "pointBackgroundColor": "#36a2eb"
    }]
  }
}
```

### tree (Tidy Tree)

Same structure as dendrogram, different layout algorithm:

```json
{ "type": "tree" }
```

### Tree/Dendrogram Options

Set via `options.tree` or `dataset.tree`:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `orientation` | string | `"horizontal"` | `"horizontal"`, `"vertical"`, `"radial"` |

## chartjs-chart-venn 4.3.3 — Venn & Euler Diagrams

Chart types: `"venn"`, `"euler"`

- **venn**: Standard Venn diagram with simple layout
- **euler**: Proportional diagram where circle sizes and overlaps reflect actual values (up to 5 sets)

### Data Format

```json
{
  "type": "venn",
  "data": {
    "labels": ["Set A", "Set B", "A ∩ B"],
    "datasets": [{
      "label": "My Venn",
      "data": [
        { "sets": ["A"], "value": 10 },
        { "sets": ["B"], "value": 8 },
        { "sets": ["A", "B"], "value": 3 }
      ]
    }]
  }
}
```

### Data Point Structure

| Property | Type | Description |
|----------|------|-------------|
| `sets` | string[] | Set identifiers. Single = individual set, multiple = intersection |
| `value` | number | Size of the set or intersection |

### Three-Set Example

```json
{
  "type": "euler",
  "data": {
    "labels": ["A", "B", "C", "A∩B", "A∩C", "B∩C", "A∩B∩C"],
    "datasets": [{
      "data": [
        { "sets": ["A"], "value": 12 },
        { "sets": ["B"], "value": 10 },
        { "sets": ["C"], "value": 8 },
        { "sets": ["A", "B"], "value": 4 },
        { "sets": ["A", "C"], "value": 3 },
        { "sets": ["B", "C"], "value": 2 },
        { "sets": ["A", "B", "C"], "value": 1 }
      ],
      "backgroundColor": [
        "rgba(54,162,235,0.5)",
        "rgba(255,99,132,0.5)",
        "rgba(255,206,86,0.5)"
      ],
      "borderColor": [
        "rgba(54,162,235,1)",
        "rgba(255,99,132,1)",
        "rgba(255,206,86,1)"
      ]
    }]
  }
}
```

### Dataset Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `data` | {sets,value}[] | **required** | Set definitions |
| `backgroundColor` | Color\|Color[] | — | Circle fill colors |
| `borderColor` | Color\|Color[] | — | Circle border colors |
| `borderWidth` | number | — | Border thickness |

### Notes

- Labels in `data.labels` correspond to each entry in `data` array (sets first, then intersections)
- `backgroundColor` array colors correspond to individual sets only (not intersections)
- Intersection colors are automatically blended
- The `euler` type uses numerical optimization so circle overlaps are proportional to values

## chartjs-adapter-date-fns 3.0.0 — date-fns Date Adapter for Time Axes

This adapter is **pre-loaded** (as a bundle that also contains date-fns
itself) and enables the `"time"` and `"timeseries"` scale types.

### Time Scale Configuration

```json
{
  "options": {
    "scales": {
      "x": {
        "type": "time",
        "time": {
          "unit": "day",
          "displayFormats": {
            "day": "MMM d",
            "month": "MMM yyyy"
          },
          "tooltipFormat": "yyyy-MM-dd",
          "parser": "yyyy-MM-dd"
        },
        "title": {
          "display": true,
          "text": "Date"
        }
      }
    }
  }
}
```

### Time Options (`scales.x.time`)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `unit` | string | auto | Display unit: `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, `"quarter"`, `"year"` |
| `displayFormats` | object | — | date-fns format string per unit |
| `parser` | string | — | Input date parse format (date-fns format string) |
| `tooltipFormat` | string | — | Tooltip date format |
| `round` | string | — | Round dates to unit start |
| `minUnit` | string | `"millisecond"` | Minimum display granularity |
| `isoWeekday` | boolean\|number | `false` | ISO week start (0=Sun, 1=Mon, etc.) |

### Format token differences vs Day.js

date-fns tokens are **case-sensitive** and differ from Day.js:

| What you want         | date-fns | Day.js (NOT this adapter) |
|-----------------------|----------|---------------------------|
| 4-digit year          | `yyyy` | `YYYY` |
| Month (Jan)           | `MMM`  | `MMM`  |
| Day of month (1..31)  | `d`    | `D`    |
| Hour (0..23)          | `H`    | `H`    |
| Minute                | `mm`   | `mm`   |

If Chart.js throws an error of the form **Use d instead of D**, you
are using Day.js-style tokens in a date-fns format string — rewrite
them to the date-fns column above.

### Data Formats

Time scale accepts dates in various formats:
- ISO 8601 string: `"2024-01-15"`, `"2024-01-15T10:30:00Z"`
- Millisecond timestamps: `1705305600000`
- date-fns-parseable strings (when `parser` is set)

### Example: Time Series Line Chart

```json
{
  "type": "line",
  "data": {
    "datasets": [{
      "label": "Daily Sales",
      "data": [
        { "x": "2024-01-01", "y": 100 },
        { "x": "2024-01-02", "y": 150 },
        { "x": "2024-01-03", "y": 120 },
        { "x": "2024-01-04", "y": 200 },
        { "x": "2024-01-05", "y": 180 }
      ],
      "borderColor": "#36a2eb",
      "fill": false,
      "tension": 0.3
    }]
  },
  "options": {
    "scales": {
      "x": {
        "type": "time",
        "time": {
          "unit": "day",
          "displayFormats": { "day": "MMM d" },
          "tooltipFormat": "yyyy-MM-dd"
        }
      },
      "y": {
        "beginAtZero": true
      }
    }
  }
}
```