This document provides a high-level introduction to the Pro React Admin codebase, a dual-purpose system that functions both as an enterprise-grade admin application and as a publishable component library (@w.ui/wui-react). This overview covers the system's architectural design, technology stack, major subsystems, and build configurations.
For detailed information about specific subsystems:
Sources: README.md1-429 package.json1-421
Pro React Admin is architected to serve two distinct purposes:
https://wkylin.github.io/pro-react-admin/@w.ui/wui-react containing 120+ reusable UI components with tree-shakeable exportsThis dual-purpose design is achieved through separate build configurations:
The library is structured with three entry points defined in package.json14-36:
./dist-lib/pro-react-components.es.js)@w.ui/wui-react/core for core infrastructure components@w.ui/wui-react/stateful for stateful business components@w.ui/wui-react/stateless for pure presentation componentsSources: package.json1-42 README.md15-68 webpack.common.js1-306
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Core Framework | React | 19.2.3 | UI rendering with concurrent features |
| Type System | TypeScript | 5.9.3 | Static type checking |
| UI Library | Ant Design | 6.1.2 | Component design system |
| Routing | React Router | 7.11.0 | Client-side routing with v7 data APIs |
| Build Tools | Webpack | 5.104.1 | Application bundling |
| Vite | 7.3.0 | Fast dev server & library builds | |
| Transpilation | Babel | 7.28.5 | JavaScript transformation |
| esbuild | 0.27.2 | Fast minification via esbuild-loader | |
| State Management | React Context API | 19.x | Theme, auth, tab state |
| Styling | Tailwind CSS | 4.1.18 | Utility-first CSS |
| CSS Modules | - | Scoped component styles | |
| Less | 4.5.1 | Ant Design theming | |
| Testing | Jest | 30.2.0 | Unit testing |
| Playwright | 1.57.0 | E2E testing | |
| React Testing Library | 16.3.1 | Component testing | |
| Internationalization | i18next | 25.7.3 | Multi-language support |
| Monitoring | Sentry | 10.32.1 | Error tracking |
| Vercel Analytics | 1.6.1 | Performance monitoring |
Sources: package.json291-380 README.md58-68
Sources: src/index.tsx1-110 src/theme/index.tsx
Sources: src/routers/index.jsx1-260 src/routers/authRouter.jsx1-227 webpack/webpack.common.js1-306 package.json1-421
The system supports multiple build targets and environments:
| Build Command | Tool | Output | Purpose |
|---|---|---|---|
npm run dev | Webpack Dev Server | In-memory | Development with HMR at port 3006 |
npm run dev:vite | Vite Dev Server | In-memory | Alternative fast dev at port 5173 |
npm run build:production | Webpack | dist/ | Production app with code splitting |
npm run build:vite | Vite | dist/ | Production app via Vite |
npm run build:lib | Vite Library Mode | dist-lib/ | Main library bundle (ESM + UMD) |
npm run build:lib:entries | Vite Library Mode | dist-lib/entries/ | Sub-path exports (core, stateful, stateless) |
npm run prepublishOnly | Combined | dist-lib/ | Pre-publish preparation |
Environment Variables:
NODE_ENV: development | productionBUILD_GOAL: development | production | dev | testSENTRY_SOURCE_MAP: map | no - controls source map uploadUSE_ANALYZE: 1 - enables bundle analysisDIST_ZIP: 1 - creates deployment archiveSources: package.json58-145 webpack/webpack.common.js20-42 webpack/webpack.prod.js1-205
The routing system is built on React Router v7 with a three-tier permission checking mechanism:
meta.routePath and meta.routeKeyannotateRoutesWithPermissions() injects meta.permission based on path patterns src/routers/utils.tsmeta.permission or meta.roles requirementspermissionService.canAccessRoute() with accessible route whitelistThe annotatedRootRouter exported from src/routers/index.jsx256 serves as the canonical route configuration.
Sources: src/routers/index.jsx1-260 src/routers/authRouter.jsx1-227 docs/PERMISSION_STRATEGY.md1-40
The system implements sophisticated multi-page management:
display toggling instead of DOM manipulation, significantly reducing layout recalculationsProTabContext and can sync to URL query parametersuseVideo hookThe tab key resolution uses getKeyName() from src/routers/index.jsx165-235 to match routes including dynamic parameters and wildcards.
Sources: src/routers/index.jsx165-235 README.md120-122
The theme infrastructure combines multiple layers:
Theme settings include:
themeMode: 'light' | 'dark'colorPrimary: Brand colorlayout: 'side' | 'top' | 'mix'navTheme: 'light' | 'dark' | 'realDark'colorWeak, greyThemeSources: src/theme/hooks.tsx README.md51
The authentication service is a singleton at src/service/authService.ts that:
localStoragelogin(), logout(), isAuthenticated() methodspermissionService for RBAC dataSources: src/service/authService.ts README.md43-47
The library is organized into three categories defined in src/lib/:
| Category | Entry Point | Components | Usage |
|---|---|---|---|
| Core | src/lib/core.ts | ErrorBoundary, KeepAlive, WatermarkProvider, ResponsiveTable, GlobalSearch | Infrastructure & containers |
| Stateful | src/lib/stateful.ts | MermaidHooks, MarkmapHooks, TreeList, CheckableTags | Data-driven & third-party integrations |
| Stateless | src/lib/stateless.ts | AnimText, SpotlightCard, MusicPlayer, SmartVideoPlayer, 100+ more | Pure presentation components |
Library consumers can import via:
Sources: package.json14-36 README.md32-33
The codebase uses path aliases configured in both webpack/webpack.common.js61-76 and tsconfig.json:
| Alias | Resolves To | Purpose |
|---|---|---|
@/ | ./src/ | General source reference |
@src | ./src/ | Explicit source root |
@assets | ./src/assets/ | Static resources |
@assets/audio | ./src/assets/audio/ | Audio files |
@assets/video | ./src/assets/video/ | Video files |
@stateless | ./src/components/stateless/ | Stateless components |
@stateful | ./src/components/stateful/ | Stateful components |
@hooks | ./src/components/hooks/ | Custom hooks |
@app-hooks | ./src/app-hooks/ | Application-level hooks |
@container | ./src/components/container/ | Container components |
@pages | ./src/pages/ | Page components |
@routers | ./src/routers/ | Routing configuration |
@utils | ./src/utils/ | Utility functions |
@theme | ./src/theme/ | Theme system |
Sources: webpack/webpack.common.js59-77
The src/routers/index.jsx140-235 file provides essential routing functions:
flattenRoutes(routes): Recursively flattens nested route arraysgetKeyName(path): Resolves pathname to tab key, handling dynamic params and wildcardsgetVisibleMenuRoutes(): Async function that filters routes by user permissionsThese are consumed by src/pages/layout/proSecNav/index.jsx1-467 for permission-aware menu generation.
Sources: src/routers/index.jsx140-260 src/utils/publicFn/index.jsx1-319
src/utils/publicFn/index.jsx1-319 and src/utils/aidFn.js provide 70+ helper functions including:
getType(), isEmptyArray(), isEqual()capitalizeWords(), toCamelCase(), toKebabCase()delay(), sleep(), asyncTo() (error-first tuples)exportFile(), exportJsonData(), readFromFile()oneApiChat(), oneApiImage() for streaming AI responsesSources: src/utils/publicFn/index.jsx1-319 README.md47
For local development:
The development server starts on port 3006 with HMR enabled via webpack/webpack.dev.js1-105
For building and publishing the component library:
Environment Requirements:
Sources: README.md103-115 package.json384-388
Complete Sources: README.md1-429 package.json1-421 webpack/webpack.common.js1-306 webpack/webpack.prod.js1-205 webpack/webpack.dev.js1-105 src/index.tsx1-110 src/routers/index.jsx1-260 src/routers/authRouter.jsx1-227 src/pages/layout/proSecNav/index.jsx1-467 src/utils/publicFn/index.jsx1-319 babel.config.js1-42
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.