TypeScript with React: complete developer guide (2026)

TypeScript and React work best when props describe the component's contract, state is modelled as a union and events use the right DOM types. The goal is fewer impossible states, not more type annotations.

What matters in practice

• Discriminated unions handle async UI states better than separate booleans.
• Server and client components have different constraints; do not pass functions across the boundary.

How to implement it

1. Type the component boundary. Props in, events out; keep internal state private.
2. Model async state. Use a union for loading, error and success.
3. Use native element props. Extend ComponentProps for buttons, inputs and links.
4. Type events correctly. Use React.ChangeEvent and friends.
5. Test the contract. Render the states and interactions that matter.
6. Review the boundary. Keep use client at the leaf and pass serialisable props.

A working example

type AsyncState<T> =
| { status: "loading" }
| { status: "error"; message: string }
| { status: "success"; data: T };
type ProfileProps = {
state: AsyncState<User>;
onRetry: () => void;
};
export function Profile({ state, onRetry }: ProfileProps) {
if (state.status === "loading") return <Spinner />;
if (state.status === "error") return <ErrorState message={state.message} onRetry={onRetry} />;
return <UserCard user={state.data} />;
}

Production checklist

Area	Check
Props	Explicit, narrow and documented
Events	Typed DOM events, not any
State	Discriminated unions for async states
Native elements	ComponentProps for extension
Boundaries	Serialisable props across server/client
Tests	Each visual state and the main interaction

Common mistakes

• Using React.FC and losing the ability to pass some props.
• Typing every event as any.
• Modelling loading and error as independent booleans.
• Passing a function from a server component to a client component.

When this is the wrong tool

Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.

Rollout plan

1. Prove one slice. Use TypeScript with React for one real route or feature, not the whole product.
2. Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
3. Add the safety net. Types, validation, tests and error handling around the new slice.
4. Measure. Check bundle size, latency, error rate and the developer experience before expanding.
5. Document and hand over. Record the pattern, the pitfalls and the version constraints.

Testing strategy

Layer	What to test	Why
Types	Strict compile and no unjustified any	Catches contract drift early
Unit	Pure logic, validation and state transitions	Fast feedback
Integration	API, database and auth boundaries	Most production failures live here
End-to-end	The critical user journey	Proves the wiring
Operations	Logs, errors, retries and rollback	A release is not finished at deploy

Operational checklist

• Pin the runtime and dependency versions; test upgrades in a branch.
• Keep secrets on the server and validate every external payload.
• Add structured logs with a request ID, but never log tokens or personal data.
• Set a performance or bundle budget and check it in CI.
• Write a short runbook for the most likely failure.

Sources and further reading

• React documentation (react.dev)
• TypeScript handbook (typescriptlang.org)
• Next.js server and client components (nextjs.org)

Related reading

• TypeScript best practices
• Next.js deployment guide
• Web application development