React Seed

An out-of-the-box React frontend template

🔗 Demo

PC: react-seed
Mobile: react-template-mobile

🪅 Related Versions

📱 Mobile version: react-template-mobile

✨ Features

📦 Out of the box, no extra configuration required
📝 Key modules are well-commented for low learning cost
🚀 Fast startup and compilation
🌱 Easy to customize and extend
🛡️ Strict code conventions

🚀 Tech Stack

Category	Stack	Version
Framework	React + ReactDOM	19.x
Language	TypeScript	5.x
Build	Vite + `@vitejs/plugin-react`	8.x
Routing	`react-router`	7.x
State	MobX + `mobx-react-lite`	6.x / 4.x
Request	axios + axios-retry	1.x
Style	Less + CSS Modules + PostCSS	—
Icon	`@phosphor-icons/react` + local svg as React component (`vite-plugin-svgr`)	—
Convention	ESLint 9 (flat config) + Prettier + Stylelint + husky + lint-staged + commitlint	—

⌛️ Requirements

Node ≥ 22.22.1 (CI pinned to 22.22.3 via volta)
npm ≥ 7.0.0 / yarn ≥ 1.22.4 / pnpm — pick one

🏃 Quick Start

# 1. Install dependencies (pick one)
npm install
# or
yarn install

# 2. Start dev server
npm run start

📦 Build

npm run build:qa     # build for testing environment
npm run build:prod   # build for production
npm run deploy       # build and publish via gh-pages
npm run clean        # clean node_modules

📂 Project Structure

react-seed/
├── vite.config.ts           # Vite build config (alias / plugins / build / server)
├── index.html               # HTML entry template (Vite root)
├── public/
│   └── favicon.ico          # Static assets (copied as-is to build output)
├── src/
│   ├── index.tsx            # App mount entry
│   ├── App.tsx              # Root component + useRoutes
│   ├── vite-env.d.ts        # Vite types & import.meta.env declarations
│   ├── router/              # Centralized routes (React.lazy + SuspenseLazy)
│   ├── api/                 # API layer (axios wrapper, grouped by page)
│   ├── store/               # MobX stores
│   ├── components/          # Common components (barrel exports)
│   ├── view/                # Page-level components
│   ├── constants/           # Constants / enums
│   ├── interface/           # Business type definitions
│   ├── types/               # Global .d.ts
│   ├── utils/               # Utilities + custom hooks
│   ├── assets/              # Static assets (incl. svg sprite)
│   └── styles/index.less    # Global styles
├── docs/                    # Design materials, UI references, English README
├── .env.development         # Development env variables
├── .env.qa                  # QA env variables
├── .env.production          # Production env variables
├── eslint.config.mjs        # ESLint 9 flat config
├── tsconfig.json            # TS config (with path alias)
├── AGENTS.md                # Project guide for AI coding assistants
└── package.json

🛠 Development Guide

Path Alias

Defined in both tsconfig.json and vite.config.ts — prefer alias over relative paths:

import {Button} from '@/components';
import {useStores} from '@/store';

Add a Page

Create index.tsx + index.less under src/view/XxxPage/
Register a lazy-loaded route via SuspenseLazy in src/router/index.tsx
Edit src/view/Tab/index.tsx if a top-nav entry is needed

Add an API

Create index.ts and types/<page-name>.ts under src/api/<page-name>/
Import the wrapped request from ../request, call request<ResponseT>({url, method, data})
Keep request/response types co-located in the same types/

State Management (MobX)

Call makeAutoObservable(this) in store constructors; wrap async assignments with runInAction(...)
Register new stores in stores of src/store/index.ts
Components reading observables must be wrapped with observer

For more conventions and AI collaboration notes, see AGENTS.md.

📝 Commit Convention

Commit messages follow commitlint:

git commit -m "<type>: <emoji> <subject>"
# example
git commit -m "feat: ✨ Add order query page"

Common types:

type	emoji	description
feat	✨	New feature
fix	🐛	Bug fix
docs	📝	Documentation changes
style	💄	Style adjustments (no logic impact)
refactor	🔨	Refactor (no new feature, no bug fix)
perf	⚡	Performance optimization
build	📦	Build system or dependency changes
config	🔧	Configuration changes
chore	🔥	Miscellaneous
release	🔖	Release a version

🏷 Branches

Branch	Description
main	Main branch
dev	Development branch
deploy	Demo deploy branch

📚 References

Project tutorial: Building a React Project Development Template from 0 to 1
Development reference: docs/data.md

🤝 Contributing

📬 Feel free to open Issues
🧙‍♀️ Pull Requests are welcome — see how to contribute
🐱 If this project helps you, why not treat the developer's cat to a can of food — cats are the real fuel that keeps this project running: Sponsor the project

💡 License

The code and documentation of this project are released under the MIT License.

FilesExpand file tree

README.en.md

Latest commit

History