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.

Building Scalable React Applications with TypeScript
AK
Ashish Kamat
Full-Stack Developer & Digital Marketer
July 16, 2025
4
655
#Scalable React applications#React with TypeScript#TypeScript React best practices#React folder structure for large apps#Type-safe React app

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): useState or useReducer

  • Global 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 --noEmit in CI so type errors block merges

  • Use ESLint with the TypeScript and React Hooks rules, plus Prettier for formatting

  • Avoid any; reach for unknown and narrow it when you genuinely don't know a type

  • Move 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.

Share Article
Article Info
Published July 16, 2025
TypeScript
4

Tags

Scalable React applicationsReact with TypeScriptTypeScript React best practicesReact folder structure for large appsType-safe React app
About the Author
AK
Ashish Kamat

Full-Stack Developer & Digital Marketer

View Profile
Stay Updated

Get the latest articles and tutorials delivered to your inbox.

Subscribe Now

Related Articles

Continue your learning journey with these related articles

Digital Marketing Guide for Businesses in Biratnagar
Tips & Tricks
May 12, 2026
11
Digital Marketing Guide for Businesses in Biratnagar

Discover the complete digital marketing guide for businesses in Biratnagar. Learn local SEO, social media, content marketing, and paid ads strategies tailored for the Biratnagar market.

Digital Marketing BiratnagarLocal SEO Biratnagar+4
Read Article
Full Stack Interview Questions - Complete 2026 Guide
Career
February 5, 2026
33
Full Stack Interview Questions - Complete 2026 Guide

Master your next technical interview with this comprehensive guide covering 187 essential JavaScript, React, Node.js, and database questions. Includes real examples, explanations, and pro tips from industry experts.

React interview preparationNode.js interview guide+5
Read Article
Build an AI Powered Resume Builder with React and OpenAI API (Full Guide)
Web Development
November 20, 2025
5
Build an AI Powered Resume Builder with React and OpenAI API (Full Guide)

Build an AI resume builder with React and the OpenAI API, with your API key kept safely on a small server. Covers app structure, prompts for ATS-friendly content, JSON mode, live preview and PDF export.

reactopenai+7
Read Article

Need Help with Your Website?

I design and build fast, SEO-ready websites and apps for businesses across Nepal. Let's discuss your project.