Apache ECharts — Administrator & Architect Guide

Comprehensive operational, architectural, and developer reference for Apache ECharts v6.0.0. Audience: platform engineers embedding ECharts at scale, library authors extending it, build engineers configuring tree-shaken bundles, and security/compliance reviewers.

Executive Summary

Apache ECharts is a browser-based charting and data-visualization library, governed by the Apache Software Foundation under the Apache 2.0 license. Version 6.0.0 (commit c8adaf4, 2026-02-26) ships 23 chart types, 28 component types, 7 coordinate systems, dual renderers (Canvas + SVG), server-side rendering, 53 locales, and 37 built-in themes.

ECharts is library-as-platform: it does not run a server, does not own data, and does not perform network I/O. All operational concerns concern embedding it in a host application — bundle size, render performance, accessibility, SSR hydration, theme governance, and locale loading.

Architecture

High-level component diagram

┌────────────────────────────────────────────────────────────────────────┐
│                            Host Application                            │
│   (React / Vue / Angular / vanilla — provides DOM container & data)    │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  │  init(dom, theme, opts)
                                  ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          ECharts Instance (core)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  │
│  │ GlobalModel │  │  Scheduler  │  │  ChartView  │  │ ComponentView│  │
│  │ (option →   │→ │  (pipeline  │→ │  (per-      │  │ (axis, grid, │  │
│  │  models)    │  │   stages)   │  │   series)   │  │  legend, …)  │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────────┘  │
│         │                │                │                  │        │
│         ▼                ▼                ▼                  ▼        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                  Coordinate Systems Manager                      │  │
│  │   cartesian (grid) │ polar │ geo │ single │ parallel │ calendar │  │
│  │                          │ matrix (v6 NEW)                       │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│         │                                                              │
│         ▼                                                              │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │            Visual Pipeline (visual/, processor/, layout/)        │  │
│  │   data transform → scale → visual mapping → label layout         │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  │  render display objects
                                  ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        zrender (graphics engine)                       │
│           ┌─────────────────────┴──────────────────────┐               │
│           ▼                                            ▼               │
│   ┌───────────────┐                            ┌──────────────┐        │
│   │ CanvasPainter │                            │  SVGPainter  │        │
│   │  (default)    │                            │  (a11y / SSR)│        │
│   └───────────────┘                            └──────────────┘        │
└────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
                   ┌───────────────────────────────┐
                   │    DOM <canvas> / <svg>       │
                   └───────────────────────────────┘

Layered model

ECharts is organized in five distinct layers, each with a clear contract. Files live under src/:

The flow on every setOption() call is strictly one-way: option → models → coord systems → visual pipeline → views → zrender → painter → DOM. Data never flows backward; user interaction enters via actions dispatched at the core, which mutate models and trigger a new render cycle.

Note

The one-way data flow is a deliberate architectural constraint. If you are building a custom extension that needs to feed information back from a view to a model, use dispatchAction to route through the core — never mutate model state directly from a view.

Core class hierarchy

Sourced from _briefing/extracted/class_hierarchy.tsv (53 classes). Highlights:

Render pipeline (Scheduler stages)

The Scheduler (src/core/Scheduler.ts) runs an ordered set of stages on every render. Each stage may register tasks via registerProcessor, registerVisual, or registerLayout. The pipeline:

1. Preprocessor — normalize raw option (legacy migrations live in src/preprocessor/)
2. Statistic / Filter — processor/dataFilter.ts, processor/dataSample.ts for downsampling
3. Visual — color/size/symbol assignment (visual/)
4. Coordinate system update — recompute axis extents, ticks, view rects
5. Layout — series-specific positioning (bar layout, pie layout, force-directed, …)
6. Render — instruct each ChartView/ComponentView to update display objects
7. Label layout — LabelManager resolves collisions globally

Tasks are stream-aware: large datasets run incrementally across animation frames so the main thread is never blocked for long.

Tip

When profiling render performance, look at the Scheduler pipeline in DevTools — each Task node corresponds to a discrete render stage. Long-running tasks in the "Visual" or "Layout" stages typically indicate too many data points or overly complex label collision resolution.

Bundle anatomy

Three pre-built entries are shipped:

Build is driven by build/build.js (Rollup) and produces UMD (dist/echarts.js), ESM (dist/echarts.esm.mjs), and minified variants. The sideEffects array in package.json (lines 33-44 of dependencies.cbf) explicitly marks only the entry indexes, theme, i18n, chart, component, and extension modules as side-effecting; everything else is tree-shakable.

Module reference (top-level src/)

Plugin / extension architecture

ECharts uses a registration-by-import model. Every chart, component, renderer, feature, and extension exports an install function. The user calls echarts.use([install1, install2, …]), which pushes each installer onto a registry consulted during init(). Tree-shakers can then prune unused installers.

Cross-repo pattern observation: this use() model resembles Mermaid's plugin API and Storybook's addon registration — a use() function that takes an array of installers, each registering capabilities into a global manager. Library authors who already understand those ecosystems can apply the same mental model here.

Built-in installer categories:

Coordinate systems

Build flavors and entry points

From package.json exports (dependencies.cbf:111-238):

Type definitions are split (types/dist/{all,charts,components,core,echarts,features,option,renderers,shared}.d.ts) so tree-shaken bundles can have correspondingly narrow type imports.

System Requirements

Browser runtime

Build / Node

SSR runtime

Data scale guidance

Configuration Reference

ECharts is option-driven — there is no .env, no config file, no global mutable settings beyond what is set per-instance via init() opts and per-render via setOption(). Three levels of configuration matter to operators.

Level 1 — init(dom, theme?, opts?) (per-instance)

Level 2 — setOption(option, opts?) (per-render)

option is the entire chart definition. The full schema is too large to enumerate here (every chart type, component, axis, item-style, label, and emphasis state has its own subtree). Top-level keys:

setOption second-arg opts:

Level 3 — module-level

Negative knowledge — what does NOT exist

To prevent fabrication, the following commonly-assumed configuration does not exist in v6.0.0:

• No environment variables. ECharts reads no process.env at runtime; bundle-time __DEV__ is the only build flag and is replaced by Rollup.
• No global config file. No echarts.config.js, no .echartsrc. Pure JS API.
• No CLI binary. echarts is not a command; the package has no bin field. The build/build.js script is internal-only.
• No automatic data fetching. ECharts never issues HTTP requests on its own. Data is always provided by the host.
• No persistence layer. No localStorage, no cookies, no IndexedDB writes by ECharts itself.
• No telemetry / analytics. No outbound network calls of any kind.
• No license key / activation. Apache-2.0; no key required.

Important

The negative-knowledge list above is exhaustive for v6.0.0. If your team's documentation or wiki references ECharts environment variables, config files, or CLI commands, those references are incorrect — ECharts is configured entirely through its JavaScript API.

Deployment

Bundling strategies

Strategy A — Pre-bundled CDN (zero build)

Best for static sites, demos, and admin dashboards where bundle size is not critical.

<script src="https://cdn.jsdelivr.net/npm/echarts@6.0.0/dist/echarts.min.js"></script>

Variants: echarts.common.min.js (smaller, common subset), echarts.simple.min.js (smallest, line/bar/pie only).

Operational notes: pin a specific version (@6.0.0, never @latest); add Subresource Integrity (integrity="sha384-..."); host a self-mirrored copy if your CSP forbids third-party CDNs.

Warning

Never use @latest or unpinned CDN URLs in production. A breaking change in a patch release could silently break your dashboards across all deployed instances simultaneously.

Strategy B — npm + tree-shaken use() (recommended for prod)

import * as echarts from 'echarts/core';
import { LineChart, BarChart } from 'echarts/charts';
import {
  GridComponent, TooltipComponent, LegendComponent, DataZoomComponent
} from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';
import { LabelLayout, UniversalTransition } from 'echarts/features';

echarts.use([
  LineChart, BarChart,
  GridComponent, TooltipComponent, LegendComponent, DataZoomComponent,
  CanvasRenderer,
  LabelLayout, UniversalTransition,
]);

Result: production bundle typically 150–300 KB minified+gzipped vs. ~1 MB for the full bundle.

Strategy C — SSR

// Server (Node):
import * as echarts from 'echarts';
const chart = echarts.init(null, null, {
  renderer: 'svg', ssr: true, width: 600, height: 400,
});
chart.setOption(option);
const svg = chart.renderToSVGString();
chart.dispose();
// Send `svg` in HTML payload.

// Client (browser):
import { hydrate } from 'echarts/ssr/client';
hydrate(domElement, { option, /* same as server */ });

The hydrate path attaches event handlers to the existing SVG without re-painting.

Strategy D — Self-hosted dist

Copy node_modules/echarts/dist/echarts.min.js into your static/ and reference with a relative URL. Useful in airgapped or strict-CSP environments.

CSP (Content Security Policy)

ECharts itself does not evaluate strings as code. It is compatible with strict CSP. Considerations:

getDataURL() and getConnectedDataURL() produce data: URIs purely client-side; no network egress.

Deployment checklist

• [ ] Pin exact version (echarts@6.0.0, no caret/tilde) in production lockfiles.
• [ ] Use the tree-shaken use() pattern; verify bundle size with webpack-bundle-analyzer or equivalent.
• [ ] Set useDirtyRect: true for canvas charts that update incrementally.
• [ ] Decide renderer: Canvas for perf/large data; SVG for accessibility, vector export, or tiny-DOM constraints.
• [ ] Register only the locales your audience needs (each adds ~10–30 KB).
• [ ] Register only the maps you actually render (world.json is ~700 KB).
• [ ] Configure ResizeObserver or window.resize listener → chart.resize().
• [ ] Always call chart.dispose() in component unmount paths to free Canvas/SVG GPU resources.
• [ ] Verify SSR and hydration if you ship server-rendered charts.
• [ ] Add accessibility: enable aria.enabled: true and provide aria.label.description.
• [ ] If embedding user-supplied option, sanitize formatter functions (see Security).
• [ ] Subscribe to apache/echarts CVE feeds and the ASF security mailing list.

Operations

ECharts has no daemon, no log file, no metric exporter. "Operations" means monitoring the host application for issues caused by the chart instance.

Lifecycle management

init(dom, theme?, opts?)  →  ECharts instance
   ↓
setOption(option)          →  render
   ↓ (repeat as data changes)
resize() | dispatchAction(...) | clear() | appendData(...)
   ↓
dispose()                  →  release Canvas/SVG, detach listeners, free zrender scene

Always dispose. Failure to call dispose() on unmount leaks Canvas-backed buffers and prevents GC of the ECharts instance. In React: call inside useEffect cleanup. In Vue: onBeforeUnmount. In Angular: ngOnDestroy.

Caution

A single missed dispose() call in a SPA can leak 10–50 MB per chart instance (Canvas buffer + zrender scene graph + event listeners). In dashboards that mount/unmount charts on tab switches, this compounds quickly and will eventually crash the browser tab.

Resize strategy

ECharts does not auto-resize. Hook ResizeObserver:

const ro = new ResizeObserver(() => chart.resize());
ro.observe(container);
// On unmount: ro.disconnect(); chart.dispose();

For mobile orientation changes, also hook window.addEventListener('orientationchange', () => chart.resize()).

Health signals to monitor

Operational runbooks

Runbook: Chart appears blank

1. Verify container has non-zero width/height (CSS).
2. Check console for "Initialize failed: invalid dom."
3. Confirm setOption was called and option.series is non-empty.
4. For series.type: 'map', confirm registerMap() ran first.
5. Inspect with chart.getOption() to see what model state exists.

Runbook: Memory leak in SPA

1. Open DevTools → Memory → take heap snapshot.
2. Search for ECharts constructor instances.
3. If retained, find the DOM container; the framework component likely did not call dispose().
4. Add dispose() to unmount lifecycle.

Runbook: Slow update with large dataset

1. Confirm renderer: 'canvas'.
2. Set useDirtyRect: true at init.
3. On the affected series, set large: true and progressive: 5000 (line/scatter/bar).
4. For streaming data, prefer chart.appendData({ seriesIndex, data }) over re-setOption.
5. Reduce label/axis tick density; disable animations on update (setOption(opt, { lazyUpdate: true }) + animation: false).

Runbook: SSR hydration mismatch

1. Ensure server and client receive the same option (serialize once).
2. Both sides must use([...]) the same installers.
3. Same width/height in init() opts on both sides.
4. Date/timezone: set useUTC: true to avoid server/client timezone divergence.

Observability

ECharts emits chart events via chart.on(eventName, handler). Useful events for instrumentation:

Integrate with your observability platform by hooking rendered for render-rate metrics and error-thrown paths via global window.addEventListener('error').

Tip

The rendered event's params.elapsedTime is the most reliable signal for detecting render regression. Track its P95 over time — a sudden jump after a dependency update or option change indicates a performance problem before users notice.

Performance Tuning

When to drop animations

• During rapid streaming (e.g. > 5 updates/sec): set animation: false at top level.
• During programmatic dataZoom from cursor: animations cause visible lag; disable on dataZoom updates.
• For SSR: animations are irrelevant; set animation: false.

Security

Threat model

ECharts runs entirely in the host's process (browser tab or Node). It does not introduce new network endpoints or persistent state. The threat surface is therefore:

1. Untrusted option injection — if your application accepts user-authored options (e.g. a dashboard editor), an attacker may pass formatter callbacks, image URLs, or HTML strings.
2. Untrusted data — series data fields rendered into tooltips/labels.
3. Untrusted maps — registered GeoJSON contains arbitrary feature names that surface in tooltips.
4. Bundle integrity — supply chain (CDN tampering, npm package compromise).

Mitigations

Warning

If your application allows users to define their own chart options (e.g., a dashboard builder), treat the entire option object as untrusted input. Formatter functions, graphic component configs, and image:// symbol URLs are all potential XSS or SSRF vectors. Whitelist allowed option keys rather than blacklisting dangerous ones. | XSS via label formatter | Same. Labels are SVG text or canvas text — generally safe, but rich-text labels ({a|...}) parse markup. Sanitize. | | XSS via graphic component | The graphic component allows raw display-object styles including text. Treat any user-provided graphic config as untrusted. | | CSP-incompatible eval | ECharts core has no eval / new Function. Compatible with script-src 'self'. | | Image symbol SSRF | series.symbol: 'image://https://attacker/' triggers an <img> request from the user's browser to that URL. This is the same risk as embedding a <img> tag — block via img-src CSP. | | DoS via huge data | A malicious option could request 100 M points. Validate data length before passing to ECharts. | | Prototype pollution | ECharts deep-merges options; ensure your option-merge layer rejects __proto__, constructor, prototype keys. (ECharts internal merge uses hasOwnProperty checks; risk is in your pre-processing.) | | Supply chain | Pin exact version. Use Subresource Integrity for CDN. Audit package-lock.json. Subscribe to ASF security advisories. | | Map data tampering | If you accept user-uploaded GeoJSON for registerMap, validate the schema and bound coordinates. |

Renderer-specific notes

• Canvas: text rendered as glyphs — no HTML parsing, lower XSS surface. Best default for untrusted-data dashboards.
• SVG: text rendered into <text> elements; rich-text uses <tspan>. Tooltips with renderMode: 'html' (default) inject into a sibling DOM node — same XSS rules as any HTML output.

Reporting vulnerabilities

ECharts is governed by the Apache Software Foundation. Security issues should be reported to [email removed] (or the ECharts-specific list [email removed] if available). Do not file public GitHub issues for vulnerabilities.

Audit trail

ECharts emits no logs of its own. If you need an audit trail of user interactions:

chart.on('click', (params) => audit.log('chart-click', { name: params.name, value: params.value }));
chart.on('legendselectchanged', (params) => audit.log('legend-toggle', params));
chart.on('datazoom', (params) => audit.log('zoom', params));

Internationalization & Theming

i18n

53 locales ship in i18n/. Built-ins (registered via src/i18n/):

AR, BG, CA, CS, DA, DE, EL, EN (default), ES, ET, FA, FI, FR, HE, HR,
HU, ID, IT, JA, KO, LT, LV, MS, NL, NO, PL, PT-br, PT, RO, RU, SI, SK,
SL, SR, SV, TH, TR, UK, VI, ZH (Simplified Chinese), …

Custom locale:

import * as echarts from 'echarts/core';
echarts.registerLocale('myLocale', {
  time: { month: ['Jan','Feb',...], dayOfWeek: [...], /* … */ },
  legend: { selector: { all: 'All', inverse: 'Inv' } },
  toolbox: { brush: { title: { rect: 'Rect', polygon: 'Poly', /* … */ } } },
  series: { typeNames: { pie: 'Pie chart', /* … */ } },
  // … see src/i18n/lang*.ts for full key list
});
echarts.init(dom, null, { locale: 'myLocale' });

Theming

37 themes in theme/ plus theme/tool/ (theme builder). Built-in themes registered automatically on import; custom themes via:

echarts.registerTheme('corporate', {
  color: ['#0066cc', '#ff6600', /* palette */],
  backgroundColor: '#ffffff',
  textStyle: { fontFamily: 'Inter, sans-serif' },
  title: { textStyle: { color: '#1a1a1a' } },
  /* … per-component styles … */
});
echarts.init(dom, 'corporate');

Theme JSON files in theme/*.json can be loaded at runtime and passed directly:

fetch('/themes/corporate.json').then(r => r.json()).then(theme => {
  echarts.init(dom, theme);
});

Testing

Test layers

Visual regression workflow

test/runTest/server.js (1909 lines) runs a Puppeteer-driven server. Test pages live under test/data/. Snapshots are stored per-version; mismatches produce diff images. The store version (recorded baseline) and run version must match — error: "Unmatched store version and run version." (test/runTest/server.js:366).

CLI for visual tests

node test/runTest/cli.js --tests <glob> --expected <version>

Required args (errors): "Tests are required" (test/runTest/cli.js:64), "Expected version is required" (test/runTest/cli.js:67).

Continuous integration recommendations

• Run lint + checktype + test on every PR.
• Run test:visual on a stable Linux runner (font rendering is platform-sensitive; expect baseline drift on macOS/Windows).

Note

Visual regression baselines are recorded per-version. If the store version and run version mismatch, the test harness errors with "Unmatched store version and run version." Always re-record baselines after upgrading ECharts or Puppeteer.

• Build all flavors (npm run release) before a release tag and verify each dist/*.js parses with npm run lint:dist.

Code Patterns & Conventions

TypeScript style

• No semicolons inside object literals, two-space indent (Apache convention).
• All public types live in src/util/types.ts and re-exported via src/echarts.{all,common,simple}.ts.
• Interfaces for option types named XxxOption, e.g. LineSeriesOption, GridComponentOption.
• Mixin classes for shared model behavior — see src/model/mixin/ (palette, area, bordered, time, ...). Applied with TypeScript declaration merging + mixin() helper.
• Branded types for ID + dimension safety (e.g. OptionDataItemObject vs OptionDataValue).

Naming conventions

Common patterns

• encode — series.encode maps dataset dimensions to visual channels; consistent across all series types.
• emphasis / select / blur — universal interaction states. Each component supports emphasis: { itemStyle, label, ... }.
• zlevel + z — layer ordering: zlevel creates a separate canvas; z is in-canvas paint order.
• silent: true — suppress hit-testing on a series or graphic.

Custom chart authoring

Subclass ChartView (src/view/Chart.ts:98):

class MyChartView extends ChartView {
  static type = 'mychart';
  type = MyChartView.type;

  render(seriesModel: MySeriesModel, ecModel: GlobalModel, api: ExtensionAPI) {
    // Use this.group as the parent zrender Group.
    // Read coord-system: seriesModel.coordinateSystem
    // Read data: seriesModel.getData()
    // Build display objects, add to this.group
  }
}

Failure to override → error: "render method must been implemented" (src/view/Chart.ts:153).

Important

Custom chart and component classes must be registered via an install function passed to echarts.use(). Calling registerClass directly still works but bypasses tree-shaking — your custom type will be bundled even by consumers who never use it.

Extending ECharts

Custom series via series.type: 'custom'

The custom chart type (src/chart/custom/) lets you supply a renderItem function that emits zrender display objects per data row. No subclassing required. Use this for bespoke shapes when a built-in chart doesn't fit.

Custom component

1. Define a ComponentModel subclass: option type, defaults, dependencies.
2. Define a ComponentView subclass: render display objects.
3. Register: ComponentModel.registerClass() + ComponentView.registerClass().
4. Export an install function that calls registerComponentModel + registerComponentView.

Custom coordinate system

See extension-src/bmap/ as the canonical example. Implement the CoordinateSystem interface (defined in src/coord/CoordinateSystem.ts):

interface CoordinateSystem {
  type: string;
  dimensions: string[];
  dataToPoint(data: number[]): number[];
  pointToData?(point: number[]): number[];
  containPoint(point: number[]): boolean;
  // …
}

Register with CoordinateSystemManager.register(type, creator) (src/core/CoordinateSystem.ts:46).

Custom data transform

echarts.registerTransform({ type: 'myorg:filter', transform(params) { … } }). Used inside dataset.transform.

Repository Structure

echarts/
├── build/                     Build orchestration (Rollup configs, dev-fast, i18n bundler)
├── dist/                      Pre-built output (ignored in source; produced by `npm run release`)
├── extension/                 Pre-built extensions (ignored)
├── extension-src/             Extension source
│   ├── bmap/                  Baidu Maps coord system (5 files)
│   └── dataTool/              gexf parser, prepareBoxplotData (3 files)
├── i18n/                      53 locale JS files (legacy CommonJS form)
├── lib/                       Per-module entry shims (ignored — generated)
├── licenses/                  Third-party license texts
├── src/                       TypeScript source (1,909 files, ~5.49 M chars)
│   ├── core/                  Engine: echarts.ts, Scheduler, Task, CoordinateSystem
│   ├── model/                 Global, Component, Series, OptionManager, referHelper
│   ├── data/                  SeriesData, DataStore, Source, Graph, Tree, Differ
│   ├── chart/                 23 chart-type folders
│   ├── component/             33 component-type folders
│   ├── coord/                 12 coord-system folders
│   ├── visual/                Visual mappings (color, symbol, decal, …)
│   ├── processor/             Data-stage operators (filter, sample, stack)
│   ├── layout/                Cross-series layout helpers
│   ├── scale/                 Interval, Log, Ordinal, Time, AxisBreak
│   ├── label/                 LabelManager + helpers
│   ├── animation/             UniversalTransition, AnimationWrap, custom transitions
│   ├── view/                  Chart.ts, Component.ts base view classes
│   ├── renderer/              installCanvasRenderer, installSVGRenderer
│   ├── theme/                 Default + dark theme registration
│   ├── i18n/                  Locale registration helpers
│   ├── loading/               Default loading spinner
│   ├── preprocessor/          Legacy option migrations
│   ├── legacy/                Deprecated-shape compatibility shims
│   ├── export/                Public API surface and per-flavor entry points
│   ├── util/                  Cross-cutting utilities (KDTree, throttle, conditional expressions, …)
│   ├── echarts.all.ts         Full bundle entry
│   ├── echarts.common.ts      Common-subset bundle entry
│   └── echarts.simple.ts      Minimal bundle entry
├── ssr/
│   └── client/src/            hydrate(dom, options) for SSR
├── test/                      ~600 files: ut/, types/, runTest/, data/, asset/, lib/, node/
├── theme/                     37 theme JSON files + theme/tool/
├── types/                     Declaration generation outputs (ignored)
├── package.json               Multi-entry exports (lines 111-238 of dependencies.cbf)
├── rollup.config.js           Rollup config
├── tsconfig.json              TS 4.4.3 config
└── LICENSE / NOTICE           Apache-2.0 + Apache attribution

Build System

Build commands

Build CLI flags (build/build.js)

Discovered from extracted CLI commands (16 total). Common flags:

Output anatomy

dist/
├── echarts.js              UMD bundle, all charts/components
├── echarts.min.js          Terser-minified UMD
├── echarts.esm.mjs         ESM bundle
├── echarts.esm.min.mjs     Terser-minified ESM
├── echarts.common.js       UMD common subset
├── echarts.common.min.js   Minified common
├── echarts.simple.js       UMD minimal
├── echarts.simple.min.js   Minified simple
└── extension/
    ├── bmap.js / bmap.min.js
    └── dataTool.js / dataTool.min.js

Type generation

Driven by @microsoft/api-extractor 7.31.2 + @lang/rollup-plugin-dts. Outputs:

types/dist/
├── all.d.ts
├── charts.d.ts
├── components.d.ts
├── core.d.ts
├── echarts.d.ts        (canonical)
├── echarts.d.cts       (CommonJS variant referenced by package.json:23)
├── features.d.ts
├── option.d.ts
├── renderers.d.ts
└── shared.d.ts

Build internals

build/build.js orchestrates Rollup with these plugins:

• @rollup/plugin-node-resolve 11
• @rollup/plugin-commonjs 17
• @rollup/plugin-replace 2 (substitutes __DEV__ → false for prod)
• rollup-plugin-terser 7 (when --min)
• Custom esbuild loader for fast dev mode (build/dev-fast.js)

The dev:fast path uses esbuild directly for sub-second incremental rebuilds; production uses Rollup for tree-shaking quality.

Error Reference

The library raises 31 distinct errors (extracted from _briefing/extracted/error_messages.tsv). The most operationally significant:

Test-suite errors (test/runTest/, test/lib/) appear during local development only and are not user-facing.

Improvements & Tech-Debt Notes

Observations from the v6.0.0 source (open as suggestions; not bugs):

1. Extracted-fact yield is low for TS-only libraries. The pipeline counted 0 functions in 1,909 files because all top-level surface is class-method based. Documentation tooling consumers should rely on index.d.ts walks, not text extraction, when targeting ECharts.
2. src/core/echarts.ts is 5,000+ lines. A future refactor could split ECharts instance methods (export, hydration, action dispatch) into adjacent files; this would simplify static analysis and tree-shaking.
3. src/legacy/ shim layer exists for deprecated shapes from v3/v4. A v7 release could drop these (with a migration guide), shrinking the engine bundle.
4. Type-test (test:dts) requires a separate npm install in test/types/ (declared in test/types/package.json). CI should cache that subtree to keep the verification fast.
5. No first-party React/Vue wrappers in the repo. Community wrappers exist (echarts-for-react, vue-echarts); consumers should pin those to ECharts 6 explicitly.
6. Visual regression baselines are platform-sensitive. Linux container is the canonical reference; macOS/Windows differ slightly in font rasterization. Document this on the test harness page.
7. Bundle entries have implicit transitive imports. index.common.js and index.simple.js lock in a curated set; consumers wanting different subsets must use the core + use([...]) path, not edit the published flavors.

Contributing

ECharts is governed by the Apache Software Foundation; contributions follow ASF process.

1. Sign the Apache ICLA (Individual Contributor License Agreement) before any non-trivial PR.
2. Discuss large changes on [email removed] before opening a PR.
3. Branching: master for current major; release branches as release/X.Y.
4. Commit format: imperative subject, body explains why; reference GitHub issues with #NNNN.
5. Required checks before PR: npm run lint, npm run checktype, npm run test, npm run test:dts, header check.
6. Visual regression: add or update snapshots in test/runTest/ for any visual change; reviewer runs the full suite.
7. Code style: enforced by ESLint + @typescript-eslint; run npm run lint:fix.
8. Add an install function for any new chart/component/feature so users can tree-shake.
9. Write at least one Jest unit test for new logic in src/.
10. Update locale strings in src/i18n/lang*.ts for any new user-visible text.

Issue triage

Issues are tracked at https://github.com/apache/echarts/issues. Selected open threads relevant to operators:

• Memory growth in long-running dashboards (recurring; usually fixed by ensuring dispose() on unmount).
• DataZoom + scroll-wheel interaction inside scrollable containers (configure dataZoom.preventDefaultMouseMove).
• SSR + universal transition mismatch on hydration (workaround: disable universal transition during SSR).

Quick Reference Card

Module-level API

import * as echarts from 'echarts/core';

echarts.use(installers);
echarts.init(dom, theme?, opts?);                      // → ECharts instance
echarts.connect(groupIdOrCharts);
echarts.disconnect(groupId);
echarts.dispose(domOrIdOrInstance);
echarts.getInstanceByDom(dom);
echarts.getInstanceById(id);
echarts.registerTheme(name, theme);
echarts.registerMap(name, geoJson, specialAreas?);
echarts.getMap(name);
echarts.registerLocale(name, locale);

Instance API (53 public methods/props selected)

chart.setOption(option, opts?);
chart.getOption();
chart.getWidth();
chart.getHeight();
chart.getDom();
chart.getZr();                                         // zrender instance (advanced)
chart.resize(opts?);
chart.dispatchAction(action);
chart.on(eventName, query?, handler, context?);
chart.off(eventName, handler?);
chart.showLoading(type?, opts?);
chart.hideLoading();
chart.convertToPixel(finder, value);
chart.convertFromPixel(finder, value);
chart.containPixel(finder, value);
chart.getDataURL(opts?);                               // base64 data URL
chart.getConnectedDataURL(opts?);                      // composite of all connected
chart.appendData({ seriesIndex, data });
chart.clear();
chart.isDisposed();
chart.dispose();
chart.renderToCanvas(opts?);                           // canvas renderer only
chart.renderToSVGString(opts?);                        // svg renderer only
chart.makeActionFromEvent(event);
chart.group;                                           // string; for connect()

Renderer matrix

Config file locations

ECharts has no config files. All settings via:

• init(dom, theme, opts) → instance settings
• chart.setOption(option) → render settings
• echarts.register*() → module-level registration

Required global state

None. ECharts maintains a per-bundle module-level registry for plugins (populated by use()), maps (registerMap), themes (registerTheme), and locales (registerLocale). All other state is per-instance.