Onboarding: apache/echarts

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit 1d ago
• 5 active contributors
• Distributed ownership (top contributor 33%)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Apache ECharts is a browser-based charting and data visualization library written in TypeScript, built on top of the zrender canvas/SVG rendering engine. It solves the problem of creating complex, interactive charts (line, bar, scatter, pie, geo maps, 3D, etc.) without requiring low-level canvas or SVG manipulation. It supports WebGL acceleration, streaming data updates, and declarative option-based configuration. Monorepo-style single package: core source lives in TypeScript under src/ (not visible in top-60 but implied by 4.6MB TS), build tooling is under build/ (build.js, config.js, dev-fast.js), and compiled output goes to dist/. The build/ directory contains separate scripts for i18n (build-i18n.js), header checks (checkHeader.js, addHeader.js), nightly releases (build/nightly/), and Apache source releases (build/source-release/).

Who it's for

Frontend and full-stack developers building data dashboards, analytics UIs, and business intelligence tools who need production-quality interactive charts with minimal boilerplate. Also used by framework wrapper authors (e.g. vue-echarts, echarts-for-react) and contributors extending chart types or rendering logic.

Maturity & risk

Extremely mature — Apache top-level project, originally released by Baidu in 2013, now at v5.x with millions of weekly npm downloads. The repo has active CI via GitHub Actions (.github/workflows/ci.yml), nightly builds (nightly.yml, nightly-next.yml), and structured release workflows. Verdict: production-ready and actively maintained.

Very low risk for adoption — Apache-governed with a large contributor base, eliminating single-maintainer risk. The codebase is 4.6MB of TypeScript with strict typing enforced via 'npm run checktype'. The main risk is the large API surface area and frequent option-level breaking changes between major versions (v4→v5 had significant migration costs documented externally).

Active areas of work

Active work includes nightly CI builds targeting a 'next' branch (nightly-next.yml), automated PR previews deployed and torn down via pr-preview.yml and teardown-pr-preview.yml, and automated NOTICE year updates (.github/workflows/update-notice-year.yml). The .github/workflows/.scripts/update-notice-year.js suggests ongoing Apache compliance automation.

Get running

git clone https://github.com/apache/echarts.git cd echarts npm install npm run dev

Then open ./test/-cases.html in a browser to browse all test cases.

To build production dist files: npm run release

To type-check: npm run checktype

Daily commands: npm run dev # watch mode + test server on ./test directory npm run release # full production build to dist/ npm run checktype # TypeScript type validation only npm run mktest:help # learn how to scaffold a new test case

Map of the codebase

• build/build.js — Main build entry point that orchestrates the Rollup-based bundling pipeline, producing all dist artifacts (full, common, simple, ESM variants).
• build/config.js — Defines all Rollup bundle configurations, entry points, output formats, and tree-shaking rules — understanding this is required before any build change.
• extension-src/bmap/bmap.ts — Reference implementation of an external map extension, showing how to register coordinate systems, models, and views as a self-contained ECharts extension.
• extension-src/bmap/BMapCoordSys.ts — Implements the coordinate system abstraction that bridges Baidu Maps to ECharts, the pattern all custom coordinate systems must follow.
• build/template/core.js — Template for the tree-shakable core entry, defining what is exported as the minimum ECharts runtime — critical for understanding the modular API surface.
• build/template/charts.js — Template listing all chart type registrations, used during build to produce per-feature bundles and must be updated when adding any new chart type.
• build/template/components.js — Template listing all component registrations (legend, tooltip, grid, etc.), the companion to charts.js for the modular bundle strategy.

How to make changes

Add a new chart type

1. Create the chart series model, view, and processor TypeScript files under src/chart/<chartName>/ following the existing pattern. (extension-src/bmap/BMapModel.ts)
2. Register the new chart type by adding its import and use() call to the charts template so it is included in full bundles. (build/template/charts.js)
3. Add the corresponding TypeScript declaration to the charts type template so consumers get proper autocomplete. (build/template/charts.d.ts)
4. Run the build to verify the new chart appears in all dist artifacts and update the Rollup config if a dedicated entry is needed. (build/config.js)

Add a new extension (coordinate system or renderer)

1. Create a new directory under extension-src/<extensionName>/ with an entry file that exports an install(registers) function. (extension-src/bmap/bmap.ts)
2. Implement the coordinate system class with dataToPoint/pointToData methods following the BMapCoordSys pattern. (extension-src/bmap/BMapCoordSys.ts)
3. Implement the view class that renders the external map DOM/canvas layer. (extension-src/bmap/BMapView.ts)
4. Add a new Rollup output entry for the extension in the build config so it produces a standalone dist/extension/<name>.js bundle. (build/config.js)

Add a new i18n locale

1. Create i18n/lang<CODE>-obj.js exporting a plain object with all required translation keys, mirroring the structure of an existing locale. (i18n/langAR-obj.js)
2. Create i18n/lang<CODE>.js as the UMD side-effect bundle that calls echarts.registerLocale() with the plain object. (i18n/langAR.js)
3. Update the i18n build script to include the new locale code so it is compiled and validated during CI. (build/build-i18n.js)

Add a new UI component (e.g. toolbar button, visual control)

1. Implement the component model and view TypeScript source files under src/component/<componentName>/. (extension-src/bmap/BMapModel.ts)
2. Register the component in the components template so it is bundled in full and common builds. (build/template/components.js)
3. Add the TypeScript declaration to the components type template for proper option typing. (build/template/components.d.ts)
4. Verify the feature is listed in the features template if it is an optional opt-in feature rather than a default component. (build/template/features.js)

Why these technologies

• TypeScript — Provides strong typing for the complex option schema, chart models, coordinate systems, and rendering pipeline, catching integration errors at compile time across a large contributor base.
• Rollup — Produces clean ES module output with deep tree-shaking, enabling consumers to import only the chart types and components they use, dramatically reducing bundle size.
• zrender — A thin, high-performance 2D canvas/SVG rendering primitive library maintained by the same team, giving ECharts direct control over the rendering layer without browser API differences.
• UMD + ESM dual publish — UMD bundles support legacy script-tag usage and CommonJS bundlers; ESM bundles enable modern tree-shaking in Webpack/Vite

Traps & gotchas

1. The build/package.json has 'type: commonjs' which is separate from the root package.json — build scripts run in CJS context, not ESM. 2) Apache license headers are strictly enforced; adding new source files without the ASF header block will fail the checkHeader.js CI step. 3) The .husky/pre-commit hook runs lint/typecheck before every commit — ensure Node.js matches the required version or husky hooks will silently fail. 4) zrender is a peer/sibling dependency maintained in a separate repo; local development against unreleased zrender changes requires npm link.

Architecture

Concepts to learn

• zrender Canvas/SVG Dual Renderer — ECharts delegates all actual pixel drawing to zrender, which abstracts over canvas 2D, SVG, and VML — understanding this split explains why ECharts can switch renderers via the 'renderer' init option.
• Declarative Option Diffing (setOption dirty flags) — ECharts uses a diffing strategy on the option object passed to setOption() to determine minimal re-render scope — understanding notMerge and lazyUpdate parameters is critical for performance-sensitive streaming use cases.
• Series / Component Plugin Architecture — Chart types (bar, line, etc.) and UI components (tooltip, legend) are registered as plugins via echarts.use() — the tree-shakable build depends entirely on understanding this registration model.
• WebGL Rendering via echarts-gl — 3D and large-dataset charts use a separate WebGL extension (echarts-gl) that hooks into the same option/component system — contributors need to understand where the canvas renderer ends and WebGL begins.
• Rollup Code Splitting for Tree Shaking — The build/config.js configures rollup to emit separate ESM chunks per component so bundlers can eliminate unused chart types — modifying the build incorrectly breaks downstream tree-shaking.
• Apache Release Process (IPMC voting) — As an Apache TLP, releases require formal voting via mailing list with cryptographic signing — the build/source-release/ scripts automate artifact preparation but contributors must understand the ASF release process to cut versions.
• Visual Encoding / Data-to-Visual Mapping — ECharts has a first-class visualMap component that maps data dimensions to visual channels (color, size, opacity) — this is distinct from axis mapping and is a core concept for understanding how series data flows to rendered output.

Related repos

• ecomfe/zrender — The underlying 2D rendering engine (canvas/SVG) that ECharts is built directly on top of — required peer dependency.
• ecomfe/vue-echarts — Official Vue.js wrapper component for ECharts, the most common integration layer for Vue users.
• hustcc/echarts-for-react — Most widely used React wrapper for ECharts, widely used alongside this repo in the React ecosystem.
• d3/d3 — Primary alternative/predecessor in the browser visualization space; ECharts competes with and occasionally borrows concepts from D3's data-join model.
• highcharts/highcharts — Direct commercial alternative solving the same interactive charting problem; frequently compared against ECharts for enterprise adoption decisions.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add visual regression tests for SSR (Server-Side Rendering) client utilities in build/template/ssr/

The SSR client module at build/template/ssr/client/ (index.js and index.d.ts) handles server-side rendering, which is a critical and complex feature. There are no visible test files covering SSR-specific rendering paths. Since SSR output must be pixel-stable and match client-side hydration, automated visual regression or snapshot tests would catch regressions before they reach users. This is especially important as ECharts SSR is a relatively newer feature that still sees active development.

• [ ] Examine build/template/ssr/client/index.js and index.d.ts to understand the public API surface (e.g., renderToSVGString, hydrate)
• [ ] Create a test file such as test/ssr/ssr-client.test.ts that exercises renderToSVGString with common chart types (line, bar, pie)
• [ ] Add snapshot assertions using jest or vitest to lock in expected SVG output structure
• [ ] Verify hydration does not throw or produce layout differences vs. pure client-side render
• [ ] Add the new test target to the existing CI workflow in .github/workflows/ci.yml so it runs on every PR

Split build/config.js into per-bundle configuration modules to reduce cognitive complexity

build/config.js is the single file that defines rollup/webpack bundle configurations for all ECharts output targets (echarts.common.js visible in dist/, plus ESM, full, and custom bundles). As the number of build targets grows, this file becomes a maintenance burden — a new contributor cannot easily identify which config block corresponds to which dist artifact. Splitting it into separate files (e.g., build/configs/common.js, build/configs/esm.js, build/configs/full.js) with a thin build/config.js re-exporting them improves discoverability and makes targeted changes safer.

• [ ] Read build/config.js in full and enumerate distinct bundle configurations (e.g., commonjs, ESM, IIFE full, IIFE common)
• [ ] Create a build/configs/ directory and extract each configuration into its own file (e.g., build/configs/cjs.js, build/configs/esm.js, build/configs/iife-full.js, build/configs/iife-common.js)
• [ ] Update build/config.js to import and re-export all configs from build/configs/ so downstream scripts (build/build.js, build/dev-fast.js) require no changes
• [ ] Verify that running the existing build scripts (e.g., npm run build referenced in build/package.json) still produces identical output in dist/
• [ ] Update CONTRIBUTING.md to reference the new build/configs/ directory so future contributors know where to add new targets

Add a GitHub Actions workflow to automatically validate TypeScript declaration files in build/template/

The build/template/ directory contains hand-authored .d.ts files (charts.d.ts, components.d.ts, core.d.ts, features.d.ts, renderers.d.ts, option.d.ts, and SSR-related declarations). These are the public TypeScript API surface shipped to end users, yet the existing .github/workflows/ci.yml has no dedicated step that type-checks these templates in isolation (e.g., using tsc --noEmit against the templates). A broken .d.ts silently ships to npm consumers who rely on these types. A focused workflow that compiles only the template declarations against a minimal tsconfig would catch such regressions immediately.

• [ ] Audit all .d.ts files under build/template/ and build/template/ssr/ to understand their import graph and dependencies on src/ types
• [ ] Create a build/template/tsconfig.check.json that sets strict: true, noEmit: true, and includes all template .d.ts files
• [ ] Add a new workflow file .github/workflows/check-dts.yml that

Good first issues

1. Add missing TypeScript type tests for edge cases in src/util/graphic.ts — the utility functions there have complex overloads that lack explicit test coverage in the test/ directory. 2) The build/source-release/template/ vote email templates use hardcoded year references; wire them into the same update-notice-year.js automation used for NOTICE. 3) Several .github/ISSUE_TEMPLATE fields in bug_report.yml could include a 'ECharts version' dropdown auto-populated from npm release tags rather than a free-text field, reducing triage effort.

Top contributors

• @plainheart — 24 commits
• @Ovilia — 17 commits
• @Justin-ZS — 14 commits
• @100pah — 11 commits
• @dependabot[bot] — 7 commits

Recent commits

• d6a812f — Merge pull request #21562 from konewka17/fix-21561 (Ovilia)
• 7d6524e — Merge pull request #21590 from apache/codex/fix-21583-area-select-style (Ovilia)
• 0c0f466 — fix(parallel): preserve areaSelectStyle on persisted selection. close #21583 (Justin-ZS)
• c108d1f — fix(sankey): implemented suggested change by @Ovilia to follow sunburst.sort method. Only null and desc implemented as (konewka17)
• 6418ca2 — feat(sankey): added dedicated test file (konewka17)
• 624f520 — feat(sankey): support disabling node sorting. close #21561 (konewka17)
• c8adaf4 — Merge pull request #21518 from apache/dependabot/npm_and_yarn/test/runTest/basic-ftp-5.2.0 (plainheart)
• c7cd5e4 — chore(deps-dev): bump basic-ftp from 5.0.5 to 5.2.0 in /test/runTest (dependabot[bot])
• 33cf6e7 — Merge pull request #21508 from diysimon/fix-21507 (Ovilia)
• a46c535 — fix: test/webkit-dep.html can not be opened. close #21507 (diysimon)

Security observations

• Medium · Potential XSS via Rich Text / HTML Rendering in Chart Labels — dist/echarts.js, dist/echarts.common.js, dist/echarts.simple.js. Apache ECharts supports rich text labels and HTML tooltips that can render user-supplied data directly into the DOM. If application developers pass unsanitized user input into chart options (e.g., tooltip formatters, label formatters, series names), this can lead to Cross-Site Scripting (XSS) attacks. ECharts has historically had XSS CVEs (e.g., CVE-2022-48318) related to this vector. The dist files (echarts.js, echarts.common.js, etc.) bundle all rendering logic including HTML injection points. Fix: Ensure that all user-supplied data passed into ECharts options is sanitized before use. Disable HTML rendering in tooltips (useHTML: false or equivalent) when not required. Keep ECharts updated to the latest patched version. Implement a Content Security Policy (CSP) header to restrict inline script execution.
• Medium · Outdated or Unverified Bundled Dependencies — dist/, build/package.json. The repository includes pre-built dist files (echarts.js, echarts.common.js, echarts.esm.js, bmap.js, dataTool.js, etc.) which bundle zrender and other third-party libraries. These bundled artifacts may contain outdated dependency versions with known vulnerabilities that are not reflected in a top-level package.json with explicit version pinning. The build/package.json only contains '{"type": "commonjs"}' with no dependency declarations, making automated dependency scanning difficult. Fix: Maintain a complete package.json with all dependencies and devDependencies explicitly pinned. Run automated dependency scanning tools (e.g., npm audit, Snyk, OWASP Dependency-Check) against the full dependency tree. Rebuild dist artifacts from source rather than committing pre-built bundles to the repository. Remove committed dist files from version control if possible.
• Medium · Committed Pre-built Distribution Files — dist/. Pre-built distribution files are committed directly to the repository under the dist/ directory. This practice introduces risks: (1) the build process and integrity of these files cannot be easily verified, (2) they may contain outdated code with security patches missing, (3) they could be tampered with without detection if repository access controls are insufficient, and (4) source maps (.js.map) are included which expose internal source code structure to end users. Fix: Remove dist files from version control and generate them during the release/CI pipeline. Use subresource integrity (SRI) hashes when distributing files via CDN. Restrict source map exposure in production environments. Implement signed releases to verify artifact integrity.
• Medium · Exposed Source Maps in Production Distribution — dist/echarts.js.map, dist/echarts.common.js.map, dist/echarts.esm.js.map, dist/echarts.esm.mjs.map, dist/extension/bmap.js.map, dist/extension/dataTool.js.map. Source map files (.js.map) are included in the dist directory and are publicly accessible. Source maps expose the original source code structure, internal variable names, logic flow, and comments, which significantly aids an attacker in reverse engineering the application and identifying exploitable weaknesses or business logic vulnerabilities. Fix: Do not expose source map files in production environments. Configure web servers to block access to .map files, or store source maps in a private location accessible only to internal debugging tools. Consider using a source map management service with access controls.
• Low · GitHub Actions Workflow Supply Chain Risk — .github/workflows/ci.yml, .github/workflows/pr-preview.yml, .github/workflows/nightly.yml, .github/workflows/nightly-next.yml. The GitHub Actions workflows (.github/workflows/) likely use third-party actions which, if not pinned to specific commit SHAs, could be subject to supply chain attacks if those actions are compromised or updated with malicious code. The pr-preview.yml workflow is particularly noteworthy as PR preview workflows that checkout external PR code can be risky if they have access to secrets. Fix: Pin all GitHub Actions to specific commit SHAs rather than mutable tags (e.g., use 'actions/checkout@abc123' instead of 'actions/checkout@v3'). Ensure PR-triggered workflows do not have access to repository secrets. Use 'pull_request_target' with caution and never checkout PR code in workflows with secret access.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.