@grokify/echartify

A non-polymorphic JSON Intermediate Representation (IR) for Apache ECharts that lets AI assistants and applications reliably generate and validate chart configurations.

ECharts' native option object is highly polymorphic — the series shape changes with type, fields are context-sensitive, and cross-field dependencies abound. EChartify replaces that with a flat, explicit IR (datasets, marks, axes, encodings) validated by Zod, then compiles it to a valid ECharts option.

Installation

npm install @grokify/echartify
# or
pnpm add @grokify/echartify

echarts (^5.6) is a peer of your rendering layer.

Usage

import { compile, chartIRSchema, type ChartIR } from '@grokify/echartify'

const ir: ChartIR = {
  datasets: [
    {
      id: 'main',
      columns: [
        { name: 'name', type: 'string' },
        { name: 'value', type: 'number' },
      ],
      rows: [
        ['A', 40],
        ['B', 60],
      ],
    },
  ],
  marks: [
    {
      id: 'pie',
      datasetId: 'main',
      geometry: 'pie',
      encode: { name: 'name', value: 'value' },
    },
  ],
}

chartIRSchema.parse(ir) // optional: validate before compiling
const option = compile(ir) // → a valid ECharts option

Pass option to any ECharts renderer, e.g. echarts.setOption(option) or echarts-for-react.

Supported geometries

line, bar, pie, scatter, area, radar, funnel, gauge, heatmap, treemap, and sankey.

Documentation

• Full docs: https://grokify.github.io/echartify/
• Schema reference, examples & API: github.com/grokify/echartify
• Changelog: CHANGELOG.md

License

MIT © John Wang