Building Scalable React Applications with TypeScript
Best practices for building large React apps with TypeScript: strict mode, feature-based folders, typed props, validating API data with Zod, TanStack Query, Zustand, generic components and type-safe routing.

TL;DR / Key Takeaway
- Best practices for building large React apps with TypeScript: strict mode, feature-based folders, typed props, validating API data with Zod, TanStack Query, Zustand, generic components and type-safe routing.
As a React project grows, components, state and data flow get harder to keep track of. TypeScript, combined with a few architecture decisions made early, keeps a growing codebase understandable for you and your team. This guide covers the practices that matter most, with examples you can copy.
Why TypeScript for React?
Fewer runtime bugs: typos, missing props and wrong data shapes are caught while you type
Better autocompletion and inline documentation in your editor
Safe refactoring: rename a prop and the compiler shows every place that needs updating
Self-documenting components: a component's props type tells teammates exactly how to use it
Turn on strict mode first
Most of TypeScript's value comes from strict mode. Enable it in tsconfig.json on day one; turning it on later in a large codebase means fixing hundreds of errors at once.
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"baseUrl": ".",
"paths": { "@/*": ["src/*"] }
}
}
noUncheckedIndexedAccess makes array and object lookups return T | undefined, which catches a whole class of "cannot read property of undefined" errors. The paths alias replaces long relative imports like ../../../components with @/components.
A folder structure that scales
Group code by feature rather than by file type. Everything for one feature lives together, so you can work on it without jumping across the whole project:
src/
features/
auth/
components/
hooks/
api.ts
types.ts
users/
components/
hooks/
api.ts
types.ts
components/ shared UI (Button, Modal)
lib/ shared utilities and clients
types/ global types
A good rule: a feature may import from components/ and lib/, but not from another feature's internals. That keeps features independent and easy to delete or rewrite.
Type your props directly
Type props on the function itself rather than using React.FC. It's simpler, handles generics better and is the more common pattern today:
type User = {
id: string;
name: string;
email: string;
};
type UserCardProps = {
user: User;
onSelect?: (id: string) => void;
};
export function UserCard({ user, onSelect }: UserCardProps) {
return (
<button onClick={() => onSelect?.(user.id)}>
{user.name} ({user.email})
</button>
);
}
For components with variants, use a discriminated union so invalid combinations of props can't compile:
type AlertProps =
| { kind: 'success'; message: string }
| { kind: 'error'; message: string; retry: () => void };
function Alert(props: AlertProps) {
if (props.kind === 'error') {
// TypeScript knows retry exists here
return <p>{props.message} <button onClick={props.retry}>Retry</button></p>;
}
return <p>{props.message}</p>;
}
Validate API data at the boundary
TypeScript types disappear at runtime, so a type on an API response is only a promise, not a guarantee. Validate external data where it enters your app with a schema library such as Zod, and derive the type from the schema so the two can't drift apart:
// features/users/api.ts
import { z } from 'zod';
const UserSchema = z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
});
export type User = z.infer<typeof UserSchema>;
export async function fetchUsers(): Promise<User[]> {
const res = await fetch('/api/users');
if (!res.ok) throw new Error(`Failed to fetch users (${res.status})`);
return z.array(UserSchema).parse(await res.json());
}
Typed data fetching with TanStack Query
TanStack Query infers types from your query function, so a well-typed fetcher is all you need; no generics required. Wrap each query in a small custom hook, and keep query keys in one place so they stay consistent:
// features/users/hooks.ts
import { useQuery } from '@tanstack/react-query';
import { fetchUsers } from './api';
export const userKeys = {
all: ['users'] as const,
detail: (id: string) => ['users', id] as const,
};
export function useUsers() {
return useQuery({ queryKey: userKeys.all, queryFn: fetchUsers });
}
Components now call useUsers() and get fully typed data, without knowing how or where the data is fetched. New to TanStack Query? Start with this beginner's guide.
State management
Server data (users, products, orders): TanStack Query, as above
Local UI state (an open menu, a form field):
useStateoruseReducerGlobal client state (the signed-in user, theme, cart): a small store such as Zustand, Redux Toolkit or Jotai, all of which support TypeScript well
Keeping server data out of global stores removes most of the state-management code large apps accumulate. A typed Zustand store looks like this:
import { create } from 'zustand';
import type { User } from '@/features/users/api';
type AuthState = {
user: User | null;
setUser: (user: User | null) => void;
};
export const useAuthStore = create<AuthState>()((set) => ({
user: null,
setUser: (user) => set({ user }),
}));
Reusable components with generics
Generics let one component work with any data type while staying type-safe. Ask callers for a key function instead of using array indexes as React keys, which break when items are reordered:
type SelectListProps<T> = {
items: T[];
getKey: (item: T) => string;
renderItem: (item: T) => React.ReactNode;
onSelect: (item: T) => void;
};
export function SelectList<T>({ items, getKey, renderItem, onSelect }: SelectListProps<T>) {
return (
<ul>
{items.map((item) => (
<li key={getKey(item)}>
<button onClick={() => onSelect(item)}>{renderItem(item)}</button>
</li>
))}
</ul>
);
}
// Usage: T is inferred as User, so renderItem knows about user.name
<SelectList items={users} getKey={(u) => u.id} renderItem={(u) => u.name} onSelect={openUser} />;
Type-safe routing
Route parameters are strings that come from the URL, so type and validate them. TanStack Router types routes and params end to end. With React Router you can type useParams, remembering the value may be missing:
import { useParams } from 'react-router-dom';
function UserDetails() {
const { id } = useParams<{ id: string }>();
if (!id) return <p>User not found</p>;
return <p>User ID: {id}</p>;
}
Tooling and habits that keep a codebase healthy
Run
tsc --noEmitin CI so type errors block mergesUse ESLint with the TypeScript and React Hooks rules, plus Prettier for formatting
Avoid
any; reach forunknownand narrow it when you genuinely don't know a typeMove logic out of components into hooks and plain functions, which are easier to test
Document shared components with Storybook or short JSDoc comments
Summary
Scalable React apps come from a few consistent habits: strict TypeScript from day one, feature-based folders, props typed directly, API data validated at the boundary, TanStack Query for server state and a small store only for true global state. Each one prevents a category of bugs, and together they keep a large codebase as easy to change as a small one.
For more detail, see the official React TypeScript guide and the TypeScript handbook. Planning a large React or Next.js app? See how I build custom web applications.
Frequently Asked Questions
Should I use React.FC to type components?
You don't need to. Typing props directly, as in function Button({ label }: ButtonProps), is simpler and is now the more common pattern.
What is the best folder structure for a large React app?
Group code by feature rather than by file type: each feature folder holds its components, hooks, API calls and types, with shared types in a global types folder.
Which state management library works best with TypeScript?
Zustand, Redux Toolkit and Jotai all have strong TypeScript support. Use useState and useReducer for local state, and reach for a library only for genuinely global state.
Tags
Get the latest articles and tutorials delivered to your inbox.
Subscribe Now

