Overview

Relevant source files

• .eslintignore
• .eslintrc.js
• CONTRIBUTING.md
• LICENSE
• README-zh_CN.md
• README.md
• package.json
• packages/components/avatar/__tests__/__snapshots__/vitest-avatar.test.jsx.snap
• packages/components/back-top/__tests__/__snapshots__/vitest-back-top.test.jsx.snap
• packages/components/icon/_example/IconExample.tsx
• packages/components/icon/icon.en-US.md
• packages/components/icon/icon.md
• packages/components/image/__tests__/__snapshots__/vitest-image.test.jsx.snap
• packages/components/table/__tests__/__snapshots__/pagination.test.tsx.snap
• packages/components/upload/__tests__/__snapshots__/vitest-upload.test.jsx.snap
• packages/components/upload/themes/DraggerFile.tsx
• packages/tdesign-react/CHANGELOG.md
• packages/tdesign-react/README-zh_CN.md
• packages/tdesign-react/README.md
• packages/tdesign-react/package.json
• packages/tdesign-react/site/package.json
• packages/tdesign-react/site/src/App.jsx
• packages/tdesign-react/site/src/components/Demo.jsx
• packages/tdesign-react/site/src/components/DraggableButton.jsx
• packages/tdesign-react/site/src/main.jsx
• packages/tdesign-react/site/vite.config.js
• test/snap/__snapshots__/csr.test.jsx.snap
• test/snap/__snapshots__/ssr.test.jsx.snap

This document provides a high-level introduction to the tdesign-react repository, a React UI component library for desktop applications maintained by Tencent's TDesign team. The repository is structured as a pnpm monorepo that produces multiple build artifacts for different consumption patterns, supports comprehensive testing strategies, and includes an integrated documentation site.

Scope: This page covers the overall repository architecture, package organization, build system, and development infrastructure. For detailed information about specific subsystems, see:

• Component architecture patterns → 2.1
• Build pipeline details → 4.1
• Testing framework → 3
• Documentation system → 5

Sources: README.md1-106 README-zh_CN.md1-106 CONTRIBUTING.md1-207

Project Identity and Purpose

tdesign-react is a production-grade React component library with the following characteristics:

Attribute	Value
Package Name	tdesign-react
Current Version	1.15.9
License	MIT
React Support	>=16.13.1 (peer dependency)
Package Manager	pnpm 9.15.9
Repository Type	Monorepo workspace

Core Features:

• 50+ desktop UI components with consistent APIs
• Multiple module formats: ES Modules, CommonJS, UMD
• Tree-shaking support for optimal bundle sizes
• Dark mode and theme customization via CSS variables
• SSR (Server-Side Rendering) compatibility
• Internationalization (i18n) with zh_CN and en_US built-in

Sources: packages/tdesign-react/package.json1-98 README.md28-35 package.json2-56

Repository Architecture

Diagram: Monorepo Package Relationships and Data Flow

The repository follows a three-package architecture:

1. packages/components/ - Component implementations with co-located tests and examples
2. packages/common/ - Git submodule containing shared styles, tokens, and documentation structure
3. packages/tdesign-react/ - Build entry point and NPM package configuration

Sources: CONTRIBUTING.md38-59 package.json137-144 packages/tdesign-react/package.json1-20

Key Directory Structure and Entry Points

Diagram: Critical File Paths for Development and Distribution

Component Organization Pattern: Each component follows this structure within packages/components/:

component-name/
├── ComponentName.tsx          # Main implementation
├── type.ts                    # TypeScript interfaces
├── _example/                  # Demo examples
│   ├── base.tsx
│   └── advanced.tsx
├── __tests__/                 # Unit tests
│   └── vitest-component.test.tsx
└── style/                     # Component-specific styles (if any)

Sources: CONTRIBUTING.md50-59 packages/components/upload/themes/DraggerFile.tsx1-175

Package Distribution Configuration

The published tdesign-react package exposes five distinct entry points for different module systems:

Field	Path	Purpose
main	lib/index.js	CommonJS for Node.js
module	es/index.js	ES Modules for bundlers
typings	es/index.d.ts	TypeScript definitions
unpkg	dist/tdesign.min.js	CDN (UMD) via unpkg.com
jsdelivr	dist/tdesign.min.js	CDN (UMD) via jsdelivr.com

Side Effects Configuration: The package declares side effects for specific paths to ensure correct tree-shaking:

Sources: packages/tdesign-react/package.json5-29 README.md64-65

Build System Overview

The build process uses a dual-track approach:

1. Rollup - Creates optimized UMD bundles for CDN usage ([dist/tdesign.min.js])
2. TypeScript Compiler (tsc) - Generates four parallel module formats with type declarations

Build Scripts from package.json25-31:

Build Configuration Files:

• Rollup: script/rollup.config.js (referenced in package.json26)
• TypeScript: tsconfig.build.json (referenced in package.json28-31)

Sources: package.json25-31 packages/tdesign-react/package.json41-47 CONTRIBUTING.md135-149

Development Workflow and Commands

Diagram: Developer Command Flow and Interactions

Key Development Ports:

• Development server: http://localhost:15000 (packages/tdesign-react/site/vite.config.js51)
• Component page: /react/components/{component-name}
• Individual demo: /react/demos/{component}/{demo-name}

Special Route for Demo Debugging: The Demo.jsx component (packages/tdesign-react/site/src/components/Demo.jsx1-100) provides isolated demo rendering at /react/demos/:component/:demo, enabling focused debugging without loading the full documentation page.

Sources: package.json5-35 CONTRIBUTING.md13-36 packages/tdesign-react/site/vite.config.js49-57 packages/tdesign-react/site/src/components/Demo.jsx64-99

Testing Infrastructure

The repository implements three parallel testing strategies:

Test Type	Tool	Environment	Purpose
Unit Tests	Vitest	happy-dom	Component logic and rendering
SSR Tests	Vitest	Node.js	Server-side rendering validation
E2E Tests	Cypress	Real browser	Integration testing

Test Execution Commands from package.json19-24:

Snapshot Test Strategy:

• CSR Snapshots: test/snap/__snapshots__/csr.test.jsx.snap (231KB, ~50 components)
• SSR Snapshots: test/snap/__snapshots__/ssr.test.jsx.snap (158KB, ~50 components)

These snapshots validate the HTML output of every component example, ensuring UI consistency across changes.

Sources: package.json19-24 test/snap/__snapshots__/csr.test.jsx.snap1-100 test/snap/__snapshots__/ssr.test.jsx.snap1-50

Documentation Site Architecture

Diagram: Documentation Site Routing and Component Hierarchy

Key Site Files:

• Entry: packages/tdesign-react/site/src/main.jsx1-26 - Renders App with React.StrictMode
• Router: packages/tdesign-react/site/src/App.jsx1-156 - Defines all routes
• Demo Loader: packages/tdesign-react/site/src/components/Demo.jsx7-20 - Uses import.meta.glob() for dynamic demo loading
• Vite Config: packages/tdesign-react/site/vite.config.js1-63 - Build configuration with custom plugins

TDoc Components (from @tdesign/site-components):

• <td-doc-layout> - Main layout wrapper
• <td-header> - Top navigation with framework selector
• <td-doc-aside> - Sidebar navigation
• <td-doc-content> - Markdown content renderer
• <td-doc-search> - Algolia-powered search

Sources: packages/tdesign-react/site/src/App.jsx1-156 packages/tdesign-react/site/src/components/Demo.jsx1-100 packages/tdesign-react/site/vite.config.js1-63

Icon System Integration

The component library integrates with a separate icon package (tdesign-icons-react) that provides 2100+ icons:

Icon Consumption Patterns:

1. On-Demand Import (Recommended):

2. Full Import via CDN:

Icon Features (from v0.6.1+):

• Variable stroke width control
• Multi-color fill support (up to 4 colors)
• 25+ categorized icon sets

Version Dependency: packages/tdesign-react/package.json94 specifies "tdesign-icons-react": "^0.6.1"

Sources: packages/tdesign-react/package.json94 packages/components/icon/icon.en-US.md1-50 packages/components/icon/_example/IconExample.tsx1-51

Code Quality and Linting

ESLint Configuration (.eslintrc.js1-88):

• Base: airbnb-base, prettier, plugin:react/recommended
• Parser: @typescript-eslint/parser
• Plugins: @typescript-eslint, react-hooks
• React version: Auto-detected
• Custom rules enforced:
  • react-hooks/rules-of-hooks: error
  • react-hooks/exhaustive-deps: warn
  • @typescript-eslint/no-unused-vars: error
  • import/order: error

Lint Staged (package.json42-46):

Commit Conventions:

• Uses cz-conventional-changelog (package.json38-40)
• Enforced via husky git hooks (package.json35)
• Follows Angular commit message format

Sources: .eslintrc.js1-88 package.json37-46 CONTRIBUTING.md186-193

Git Submodule Strategy

The packages/common/ directory is a git submodule pointing to the tdesign-common repository:

Initialization: pnpm run init executes:

Submodule Contents:

• style/web/ - Shared CSS and design tokens
• docs/web/api/ - Component API documentation structure
• js/ - Framework-agnostic utility functions

Development Workflow with Submodule:

1. Fork and clone tdesign-common separately
2. Make changes in a feature branch
3. Submit PR to tdesign-common
4. Update submodule pointer in main repo after merge

Sources: CONTRIBUTING.md113-144 package.json7 CONTRIBUTING.md6-10

Browser Compatibility

Browser	Minimum Version
Chrome	84+
Firefox	83+
Edge	84+
Safari	14.1+

The library does not support Internet Explorer. SSR compatibility is validated through dedicated test suites.

Sources: README.md71-77 test/snap/__snapshots__/ssr.test.jsx.snap1-50

Peer Dependencies and Ecosystem

Required Peer Dependencies (packages/tdesign-react/package.json67-70):

React 19 Support: The library includes a React 19 adapter at es/_util/react-19-adapter.js (packages/tdesign-react/package.json26) for forward compatibility.

Related TDesign Libraries:

• tdesign-vue-next - Vue 3.x implementation
• tdesign-vue - Vue 2.x implementation
• tdesign-miniprogram - WeChat mini-program components

Sources: packages/tdesign-react/package.json67-70 README.md79-86 packages/tdesign-react/CHANGELOG.md259