React + TypeScript 项目架构最佳实践

Why Talk About Architecture?

Front-end developers have probably all had this experience: when a project starts, the code is nice and clean. But as requirements pile up and people come and go, the code slowly turns into a “shit mountain” —

• Directory structure is a mess, finding a file takes forever.
• Components are copy-pasted, changing one place means changing N places.
• State is everywhere, you don’t know where data comes from or where it goes.
• TypeScript becomes AnyScript, types exist in name only.
• New people joining the project stare at the code for a week and dare not change anything.

These problems are essentially architecture design problems. You don’t notice them in small projects. But when the project grows and the team grows, good or bad architecture directly determines development efficiency and code quality.

Our front-end team has built quite a few medium-to-large React projects over the years. We stepped in many pitfalls, and gradually summarized a relatively mature set of architecture standards. Today let’s talk about how a React + TypeScript project should be structured.

Directory Structure: Tidy Up First

How do many projects end up with their directory structure? You create directories as you think of them, add things as you need them. The result: more and more directories, increasingly chaotic.

Our principle: organize by feature, not by technical type.

What does that mean? Many people like to organize like this:

src/
  components/    # all components
  pages/         # all pages
  hooks/         # all hooks
  utils/         # all utility functions
  types/         # all type definitions
  api/           # all APIs

This structure works for small projects, but for large projects it’s troublesome — to work on one feature, you have to jump between 7-8 directories.

We recommend organizing by domain/feature:

src/
  assets/              # static assets
  components/          # common components (reused across business)
  hooks/               # common hooks
  utils/               # common utilities
  types/               # global types
  services/            # API service layer
  store/               # global state
  layouts/             # layout components
  pages/               # pages
    user/              # user module
      components/      # user module specific components
      hooks/           # user module specific hooks
      types.ts         # user module types
      api.ts           # user module APIs
      index.tsx        # user page
    order/             # order module
      components/
      hooks/
      types.ts
      api.ts
      index.tsx
  App.tsx
  main.tsx

Core idea: code strongly related to a feature goes in that feature’s directory. Only truly generic code used by multiple modules gets promoted to the outer level.

Benefits of this approach:

• High cohesion: code for one feature is all together — changing a feature doesn’t require searching everywhere for files.
• Low coupling: clear boundaries between modules, less messy cross-references.
• Splittable: when a module gets too big and needs to be split out, just move the whole directory.

Tech Stack Selection: What to Use, What Not to Use

There’s no standard answer for tech stack selection, but here’s some of our experience:

Build Tool: Vite

Needless to say, Vite is already the de facto standard. Development experience is so much better than Webpack — fast startup, fast HMR.

Routing: React Router v6

React Router is still the most mature, best ecosystem routing solution. v6’s hooks approach is also pretty comfortable.

State Management: Depends on the Scenario

State management is what people agonize over the most. Our experience: don’t reach for Redux right away — most projects don’t need it.

Our selection strategy:

• Small projects: React’s built-in useState + useContext is enough.
• Medium projects: Use Zustand or Jotai — lightweight, simple, easy to use.
• Large projects, complex state: Use Redux Toolkit — way cleaner than vanilla Redux.

We use Zustand for most projects now — it’s great. Simple API, less code, good TS support, good performance.

Styling: CSS Modules +少量 Global Styles

We’ve tried many approaches: styled-components, emotion, Tailwind, CSS Modules… In the end we feel CSS Modules is the best balance:

• Styles and components are separate, code doesn’t get messy.
• Natural scope isolation, no worry about class name conflicts.
• Low learning curve — just write normal CSS.
• Good performance, no runtime overhead.

We also use Tailwind, but generally for rapid prototyping or admin systems — not ideal for projects with high styling customization requirements.

Data Fetching: Axios + React Query / SWR

For data fetching, we strongly recommend React Query (now called TanStack Query) or SWR.

Don’t write your own useEffect to make requests, manage loading, manage caching — React Query does all that for you, and does it better than what you’d write yourself.

After using it, you’ll find that half the state management code in your project is unnecessary.

Component Design: Principles for Writing Good Components

Components are the core of React. How well you write components directly determines code quality.

We’ve summarized several principles:

1. Components Should Be Small, Single Responsibility

One component does one thing. If a component is over 300 lines or has more than 10 props, it can probably be split.

Signals it’s time to split a component:

• There are several unrelated large JSX blocks in the component.
• There are multiple independent states with no relation to each other.
• Some logic block has its own state and effects and can stand alone.

After splitting, each component is small, logic is clear, easier to test, easier to reuse.

2. Props Design Should Be Reasonable

Props are a component’s “interface.” Well designed, the component is comfortable to use; poorly designed, it’s a pain.

Key points:

• Clear naming: No abbreviations, no vague names. onUserClick is better than onClick, isLoading is better than loading.
• Clear types: Use union types instead of booleans when possible. For example, variant: 'primary' | 'secondary' | 'danger' is way better than isPrimary: boolean, isDanger: boolean.
• Don’t pass too many props: Too many props means the component has too many responsibilities — time to split.
• Provide reasonable defaults: Give common props default values to reduce usage cost.

3. Distinguish Presentational and Container Components

This concept is a bit old, but still useful.

• Presentational components: Only responsible for rendering, don’t care where data comes from or what the business logic is. Props in, JSX out. Pure, easy to test, easy to reuse.
• Container components: Responsible for data fetching, state management, business logic — then pass data to presentational components.

Of course you don’t have to strictly separate them, but keep this in mind — try to separate business logic from rendering logic. This way presentational components can be reused, and when business logic changes it doesn’t affect rendering.

4. Composition Over Inheritance

Don’t do component inheritance in React — that’s an anti-pattern. Use composition: pass props, nest children, reuse logic with custom hooks.

State Management: Where to Put State?

State management is the most easily messed up part of React projects. Many people stuff everything into the global store, and the global state gets more and more bloated, too scary to change.

Our principle: keep state as low as possible. If it can live in a component, keep it in the component. Only lift it up when you really need to share it.

Specifically:

1. Component Local State

State only used by this component — keep it in the component with useState/useReducer. Don’t stuff everything into global.

2. Parent-Child Shared State

State shared between parent and child — lift it up to the common parent component, pass via props.

3. Cross-Multi-Level Shared State

When it crosses multiple levels and props drilling is too painful — use Context.

4. Global State

Truly global state, like user info, theme, permissions — only then put it in the global store.

5. Server State

Data from the backend — don’t put it in the global store! Use React Query / SWR to manage it. They come with caching, auto-refresh, retries, loading states — way better than anything you’d write yourself.

Many projects’ global stores are stuffed with data from the backend, but it’s completely unnecessary. Use React Query and you can reduce half your state management code.

TypeScript: Don’t Write AnyScript

Using TypeScript without types is a waste. But in many projects, TypeScript becomes AnyScript — any everywhere, types exist in name only.

A few of our practices:

1. Always Enable Strict Mode

In tsconfig.json, strict: true must be enabled. Without strict mode, TypeScript loses half its power.

At first it might feel annoying, errors everywhere. But once you get used to it, you’ll find that many bugs are caught at compile time — saving tons of debugging time.

2. Use any Sparingly, Prefer unknown

any is the escape hatch of the type system. Use it too much and you might as well not have types.

If you really don’t know the type, use unknown instead of any. unknown is safer — you can’t just operate on it arbitrarily, you have to do type checking first.

3. Make Good Use of Union Types and Type Guards

Union types are a very powerful feature of TypeScript. For example:

type ButtonProps = {
  variant: 'primary' | 'secondary' | 'danger';
  size: 'sm' | 'md' | 'lg';
};

Way clearer than using a bunch of booleans, and you get type hints — hard to make mistakes.

Combined with type guards, you can write very safe code:

type Fish = { swim: () => void };
type Bird = { fly: () => void };

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

4. Interface Definitions Should Be Standardized

Types for API response data must have interfaces defined. Don’t be lazy and write any.

And interface definitions should align with the backend — ideally maintained in a unified place, not each file writing its own set. We generally have one types.ts per module, centrally defining types for that module.

5. Make Good Use of Utility Types

TypeScript has many built-in utility types: Partial, Pick, Omit, Record, ReturnType… These utility types help you write cleaner, more flexible type definitions.

For example, you have a User type and want an update form that only needs some fields:

interface User {
  id: number;
  name: string;
  email: string;
  age: number;
}

type UpdateUserDto = Partial<Pick<User, 'name' | 'email' | 'age'>>;

One line, no need to rewrite everything.

Performance Optimization: Don’t Optimize Prematurely, But Know How

Performance optimization — don’t optimize prematurely, but know how to optimize when you need to.

Most of the time, React’s default performance is good enough — no need for special optimization. But when you encounter performance issues, you need to know where to start.

Several common optimization points:

1. Avoid Unnecessary Re-renders

This is the most common performance problem. When a parent component renders, all child components re-render too — even if their props haven’t changed.

Optimization tools:

• React.memo: Wrap a component — if props haven’t changed, don’t re-render.
• useMemo: Cache computation results — if dependencies haven’t changed, don’t recalculate.
• useCallback: Cache function references — prevent child components from re-rendering because function reference changed.

But note: these optimizations themselves have costs. Don’t memo everything — most of the time you don’t need to. Profile first, find the real bottleneck, then optimize.

2. List Optimization

Long lists are performance killers. Hundreds or thousands of items, all rendered at once — super laggy.

Optimization tools:

• Virtual scrolling: Only render elements in the visible area. We recommend react-window or react-virtuoso.
• Correct keys: Don’t use index as key — use a unique id. Otherwise when list order changes, you get all kinds of weird issues.

3. Lazy Loading

Codebase too big, first screen slow? Use lazy loading:

• Route lazy loading: React.lazy + Suspense — each route’s code is split into separate chunks, loaded when visited.
• Component lazy loading: Large components can also be lazy loaded.

4. Avoid Heavy Computation During Render

Don’t do heavy computation inside the component render function — it runs every render, very slow.

Use useMemo to cache it — if dependencies haven’t changed, no need to recalculate.

Engineering: Standards and Tools

Finally, engineering. When projects get big, relying on people’s self-discipline doesn’t work — you need tools and standards to ensure quality.

1. ESLint + Prettier

Code style and code quality — don’t argue about it during review, use tools to automatically check and fix.

ESLint handles code quality checks, Prettier handles code formatting. Auto-fix on save — ensures consistent code style and saves time arguing about format during reviews.

2. Husky + lint-staged

Only check code on commit:

• Husky: Git hooks — automatically run checks before commit.
• lint-staged: Only check staged files — fast.

This ensures committed code quality without slowing down development with slow checks.

3. Unit Testing

Important utility functions, complex business logic, common components — write unit tests.

No need to chase 100% coverage, but core logic must have tests. With tests, you have confidence when refactoring.

We generally use Vitest + React Testing Library — great experience.

4. Commit Standards

Use Conventional Commits: feat, fix, docs, style, refactor, test, chore…

This keeps commit history clean, and you can auto-generate changelogs.

Use commitlint to check commit messages — ensure everyone follows the standard.

Closing Thoughts

When it comes to architecture, there’s no “best” — only what’s most suitable.

For small projects, use a simple architecture. Don’t overcomplicate it — architecture itself has costs. As projects and teams grow, gradually refine the architecture.

The most important thing isn’t how many advanced technologies you use — it’s code that’s clear, maintainable, and extensible. New people can get up to speed quickly, requirements can change fast, problems can be diagnosed quickly.

That’s the standard for good architecture.

Hope this article gives you some reference. If your team also has its own best practices, feel free to share.