Why ECharts Requires import * and How ESM vs CJS Influence Module Imports

Hi, I am 石小石. In everyday frontend development we often use import to bring third‑party libraries or modules, such as import dayjs from "dayjs" or import { useState, useEffect } from 'react';. Some dependencies, like ECharts, throw errors (e.g., echarts is undefined) when imported as a default module and must be imported with import * as echarts from 'echarts';. This article uses ECharts as an example to explore the root cause, covering the differences between ES Module (ESM) and CommonJS (CJS) specifications.

Common import patterns

In the ES Module specification, common import forms include:

Default import

import xxx from 'module';

This requires the module to export a default value, e.g., export default xxx;.

Named import

import { a, b } from 'module';

This requires the module to have named exports such as export const a and export const b.

Namespace import

import * as mod from 'module';

This aggregates all exports of the module into a single object.

Deep dive into ECharts export style

ECharts export strategies

The entry file of ECharts shows three compatibility strategies: import * as echarts from ... – all exports are named; there is no export default. export as namespace echarts; – for UMD compatibility, allowing the library to be loaded via a <script> tag and attached to window.echarts. export = echarts; – a CommonJS‑style export that maps to module.exports = echarts, ensuring compatibility with Node.js and older bundlers; TypeScript therefore requires import * as echarts rather than a default import.

ECharts does not use export default for three main reasons:

Compatibility : It needs to work with ESM, CommonJS, and UMD environments.

Historical legacy : ECharts was originally published as a UMD module before ES Modules became widespread.

API design : The library follows a namespace‑style API where users call functions via echarts.xxx(), so a default export would break this semantic consistency.

Other scenarios for import *

Libraries that export many functions (e.g., lodash-es) or modules that provide numerous constants/enums (e.g., Node.js built‑in path module) often use the namespace import to keep code concise.

How to decide if import * is needed

If you are unsure how to import a library, you can:

Check the library’s documentation for usage examples.

Inspect the source code or the d.ts declaration file to see the export style.

Use AI‑assisted tools such as Trae or Cursor for intelligent import suggestions.