This document describes the build pipeline that transforms TDesign React source code into distributable packages, and explains the different module formats produced to support various consumption patterns. The build system uses Rollup for bundling and TypeScript for type generation, producing five distinct output formats (es/, esm/, cjs/, lib/, dist/) optimized for different use cases.
For information about the documentation site build process, see Static Site Generation and Prerendering. For package distribution details, see Module Formats and Entry Points.
The build process follows a multi-stage pipeline that runs Rollup bundling followed by parallel TypeScript compilation:
Sources: package.json30-37 packages/tdesign-react/package.json41-48
The build process is orchestrated through npm scripts defined in the root package.json:
| Script | Command | Purpose |
|---|---|---|
prebuild | rimraf packages/tdesign-react/... | Clean all output directories before build |
build | rollup -c ... && bundle-override.js && build:tsc | Main build command executing all stages |
build:tsc | run-p build:tsc-* | Run TypeScript compilation tasks in parallel |
build:tsc-es | tsc --outDir packages/tdesign-react/es/ | Generate type definitions for es/ format |
build:tsc-esm | tsc --outDir packages/tdesign-react/esm/ | Generate type definitions for esm/ format |
build:tsc-cjs | tsc --outDir packages/tdesign-react/cjs/ | Generate type definitions for cjs/ format |
build:tsc-lib | tsc --outDir packages/tdesign-react/lib/ | Generate type definitions for lib/ format |
The run-p (npm-run-all2) package enables parallel execution of TypeScript compilation tasks, significantly reducing build time by compiling type definitions for all formats simultaneously.
Sources: package.json30-37 package.json119
Rollup processes the source code through the configuration at script/rollup.config.js to produce JavaScript bundles for all five module formats:
The Rollup configuration uses multiple plugins to handle different aspects of the build:
@rollup/plugin-babel transpiles TypeScript and JSX syntax@rollup/plugin-node-resolve resolves node_modules dependencies@rollup/plugin-commonjs converts CommonJS modules to ESMrollup-plugin-postcss processes LESS stylesheetsrollup-plugin-terser minifies the UMD bundle for productionSources: package.json31 package.json76-81 package.json130-140
After Rollup completes bundling, TypeScript compilation runs in parallel to generate .d.ts type definition files for each module format:
The --emitDeclarationOnly flag instructs TypeScript to generate only type definition files, as the JavaScript code has already been compiled by Rollup. Each format receives identical type definitions, but placed in its respective output directory.
Sources: packages/tdesign-react/package.json43-47
The build produces five distinct module formats, each optimized for different consumption patterns:
| Format | Directory | Module System | Styles Included | Entry Point | Target Consumers |
|---|---|---|---|---|---|
| es/ | packages/tdesign-react/es/ | ESM | Yes | module field | Modern bundlers (Webpack 5+, Vite) |
| esm/ | packages/tdesign-react/esm/ | ESM | No | - | Tree-shaking optimized imports |
| cjs/ | packages/tdesign-react/cjs/ | CommonJS | No | - | Legacy Node.js environments |
| lib/ | packages/tdesign-react/lib/ | CommonJS | Yes | main field | Node.js with styles |
| dist/ | packages/tdesign-react/dist/ | UMD | Yes (bundled) | unpkg/jsdelivr | Browser CDN usage |
es/ (ESM with Styles):
module entry point in package.jsones/index.d.tsesm/ (ESM without Styles):
cjs/ (CommonJS):
require() and module.exportslib/ (Library with Styles):
main entry point in package.jsondist/ (UMD Bundle):
TDesign variableSources: packages/tdesign-react/package.json6-10 packages/tdesign-react/package.json11-19
The package.json file defines multiple entry points to direct different module resolution systems to the appropriate format:
Modern build tools follow this resolution order:
module field → es/index.js (preferred by bundlers supporting ESM)main field → lib/index.js (fallback for Node.js and older tools)unpkg/jsdelivr fields → dist/tdesign.min.js (used by CDN services)typings field → es/index.d.ts (TypeScript type definitions)Sources: packages/tdesign-react/package.json6-10
The sideEffects field in package.json informs bundlers which files have side effects and cannot be safely removed during tree-shaking:
Style Files:
es/**/style/** and esm/**/style/** contain CSS importsBundle Outputs:
dist/* contains self-executing UMD codeAdapter Modules:
react-19-adapter.js provides React 19 compatibility shimsAll other files (core components, utilities) are side-effect free and can be safely tree-shaken if unused.
Sources: packages/tdesign-react/package.json21-29
Different consumption patterns utilize different module formats based on their requirements:
For Modern Applications (Vite, Webpack 5+):
For Legacy Node.js (CommonJS):
For CDN Usage:
For Advanced Optimization:
Sources: packages/tdesign-react/package.json6-10
The complete build output creates this directory structure in the published package:
packages/tdesign-react/
├── es/ # ESM with styles (module entry)
│ ├── index.js
│ ├── index.d.ts
│ ├── button/
│ │ ├── index.js
│ │ ├── index.d.ts
│ │ └── style/
│ │ └── index.js # Style imports
│ └── ...
├── esm/ # ESM without styles
│ ├── index.js
│ ├── index.d.ts
│ ├── button/
│ │ ├── index.js
│ │ └── index.d.ts
│ └── ...
├── cjs/ # CommonJS without styles
│ ├── index.js
│ ├── index.d.ts
│ └── ...
├── lib/ # CommonJS with styles (main entry)
│ ├── index.js
│ ├── index.d.ts
│ └── ...
├── dist/ # UMD bundle
│ ├── tdesign.js
│ ├── tdesign.min.js # Minified (unpkg/jsdelivr entry)
│ └── tdesign.css # Bundled styles
└── package.json
Each format maintains the same component structure but differs in module system and style handling. The index.js and index.d.ts files provide the package entry point, while individual component directories allow direct imports.
Sources: packages/tdesign-react/package.json11-19 package.json30
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.