Where to Find TypeScript Type Definitions for ECharts: A Complete Developer Guide

Apache ECharts ships comprehensive TypeScript type definitions directly in the npm package, providing full IntelliSense and compile-time type safety through index.d.ts and supporting declaration files without requiring any additional @types packages.

Apache ECharts provides first-class TypeScript support by bundling complete type definitions directly within the apache/echarts repository. When you install ECharts via npm, you automatically get access to rich type definitions that cover everything from chart initialization to complex option configurations, eliminating the need for separate type packages.

Built-in TypeScript Support in Apache ECharts

Unlike many JavaScript libraries that rely on community-maintained @types packages, Apache ECharts maintains its TypeScript definitions directly alongside the source code. The package.json file includes a types field that points to index.d.ts, ensuring TypeScript compilers automatically discover these definitions when you import the library.

Core Type Definition Files

The type definitions are organized across several key files in the repository, each serving specific purposes for different use cases.

index.d.ts – The Main Entry Point

Located at the repository root, index.d.ts serves as the central declaration file that re-exports all public ECharts APIs. When you write import * as echarts from 'echarts', TypeScript resolves this import through index.d.ts, giving you typed access to:

• The init method for creating chart instances
• The dispose method for cleanup
• The EChartsOption interface for configuration objects
• Helper methods and constants

src/global.d.ts – Core Instance Types

The src/global.d.ts file contains the foundational interfaces for ECharts instances, including the core ECharts class definition with methods like init, dispose, getInstanceByDom, and use. This file also includes global augmentations and utility types that support the library's internal architecture while providing type safety for instance methods.

build/template/*.d.ts – Generated Declarations

For advanced use cases and custom builds, ECharts generates specialized declaration files in the build/template/ directory:

• option.d.ts – Type definitions for option schemas used by the builder system
• core.d.ts – Core component typings for minimal custom builds
• components.d.ts – Individual component types (legend, tooltip, toolbox, etc.)
• charts.d.ts – Chart-specific typings (line, bar, pie, scatter, etc.)

These files are particularly useful when creating server-side rendering (SSR) clients or when tree-shaking ECharts to include only specific renderers or components.

How to Use ECharts TypeScript Definitions

Once you install ECharts via npm install echarts, TypeScript automatically picks up the type definitions. Here's how to leverage them in your code:

import * as echarts from 'echarts';

// The chart instance is fully typed with all available methods
const chart = echarts.init(document.getElementById('main') as HTMLDivElement);

// Options are type-checked against the EChartsOption interface
const option: echarts.EChartsOption = {
  title: { text: 'ECharts TypeScript Example' },
  tooltip: {},
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [120, 200, 150] }]
};

chart.setOption(option);

If you enable esModuleInterop in your tsconfig.json, you can also use the default import syntax while maintaining the same type safety:

import echarts from 'echarts';

// Same typed experience with default import
const chart = echarts.init(document.getElementById('main')!);

Summary

Apache ECharts delivers comprehensive TypeScript support through built-in declaration files that require no additional configuration:

• index.d.ts provides the main entry point for all public APIs, automatically referenced by package.json
• src/global.d.ts defines core instance interfaces including init, dispose, and the ECharts class
• build/template/*.d.ts offers generated typings for custom builds, SSR, and specific chart components
• The EChartsOption interface provides compile-time validation for all chart configuration objects

These definitions enable full IntelliSense, automatic type checking, and inline documentation within modern IDEs.

Frequently Asked Questions

Do I need to install @types/echarts separately?

No. Apache ECharts includes comprehensive TypeScript definitions directly in the npm package. The package.json file specifies the types field pointing to index.d.ts, so TypeScript automatically discovers these definitions when you install echarts via npm. Installing separate @types packages is unnecessary and may cause type conflicts.

Which file contains the EChartsOption interface definition?

The EChartsOption interface is primarily defined and re-exported through index.d.ts at the repository root. This interface aggregates type definitions from various sub-modules to provide a complete typed structure for chart configuration objects. When you import from echarts, the EChartsOption type is available as a property of the imported namespace.

Can I use ECharts types for server-side rendering (SSR)?

Yes. The build/template/ directory contains specialized declaration files for SSR scenarios, including ssr-client.d.ts and renderer-specific type definitions. These files provide typings for server-side rendering clients, canvas/SVG renderers, and feature flags. When building custom ECharts bundles for Node.js environments, reference these declaration files to maintain type safety across server and client boundaries.

How do I get IntelliSense for specific chart types like line or bar charts?

The build/template/charts.d.ts file contains specific interface definitions for individual chart types including LineSeriesOption, BarSeriesOption, PieSeriesOption, and others. These types are composed into the main EChartsOption interface, so when you specify a series type property (e.g., type: 'bar'), TypeScript can narrow the type and provide specific property suggestions for that chart type. Importing from the main echarts namespace gives you access to these specialized series option types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}