In 09-01, when building the testing pyramid, static analysis was placed at its base and called "the cheapest level": checks that run without launching the application, without mounting components, and without waiting for anything. There it was covered by the linter, and it was announced that the other half — types — would be covered in this lesson. And module 10 has reinforced the argument without naming it: in 10-03 you saw contracts everywhere — which props can cross a boundary, what shape the object returned by a server action has, which fields a Bike carries — and all of them are, today, implicit: they live in the head of whoever wrote the component and are only discovered when something fails at runtime. This lesson makes them explicit and checks them as you type. You are going to set up TypeScript on the CicloUrbano Vite project incrementally, model the domain in a single types file, and type components, hooks, events, Redux Toolkit, TanStack Query, and API responses. The goal isn't to learn all of TypeScript, but the subset used every day in React, and why.

1. Static analysis as the cheapest layer
2. What TypeScript brings and what it costs
3. Setting up on the Vite project
4. tsconfig.json: the options that matter
5. Incremental migration strategy
6. Fundamentals used every day
7. interface vs type
8. unknown, any, assertions, and type guards
9. Modeling the domain: src/types/domain.ts
10. Typing components
11. Generic components and why React.FC is no longer used
12. Typing hooks
13. useReducer: where TypeScript shines
14. useContext and custom hooks
15. Typing events
16. Redux Toolkit and TanStack Query
17. External data: validating at the boundary with Zod
18. TypeScript and tests: what each one catches
19. How to read a long error message

Recall the pyramid from 09-01 and look at its base:

The property that makes static analysis special is when it warns. A test tells you something is wrong after you write it, run it, and wait. Typing tells you before you save the file, with the cursor still on the line of the error. That difference of seconds is huge in practice, because the context is still in your head.

A real example from CicloUrbano. This change would pass every unit test for validateBooking and still break the application:

Without types, bike.pricePerHour returns undefined in the twelve places where it's used, and the interface shows "NaN €/h". You find out when someone opens that screen. With types, the editor flags all twelve places the moment you rename the field, and tsc fails the build before you deploy.

Let's be concrete in both directions.

What it brings:

What it costs:

An important clarification on that last row, because it's surprising: Vite doesn't verify types. It strips the annotations with esbuild and moves on. The real checking is done by your editor and the tsc --noEmit command, which has to run in continuous integration. If you don't, TypeScript becomes decoration.

And the honest caveat: TypeScript doesn't replace tests. It guarantees that pricePerHour is a number, not that the price calculation is correct. They are different, complementary layers; section 18 covers this in detail.

On the existing CicloUrbano project, without touching anything else:

What each package is:

• typescript: the compiler and the language service your editor uses.
• @types/react and @types/react-dom: React's type definitions. React ships without built-in types, so they come separately. They must match React 19.

Add the check command to package.json:

tsc --noEmit means "check the types but don't generate JavaScript": Vite already handles compiling. Chaining it before vite build turns a type error into a build failure, exactly like the linter in 09-01.

At the project root:

The ones you really need to understand:

strict: true — turns on a group of checks. The most important is strictNullChecks: without it, null and undefined are assignable to any type, and TypeScript loses half its value.

That error is a TypeError: Cannot read properties of undefined that will never reach production. Starting without strict is the decision people regret the most later.

jsx: "react-jsx" — the modern transform. It lets you write JSX without importing React in every file. With "react" (the old one), import React from 'react' becomes mandatory again.

moduleResolution: "bundler" — tells TypeScript to resolve modules the way Vite does: without requiring the .js extension on imports, and respecting packages' exports field. It's the right choice in a bundler-based project.

allowJs: true — the key to the incremental migration. It lets .js/.jsx and .ts/.tsx coexist and import each other. With checkJs: false, JavaScript files aren't checked: you migrate one at a time, no big bang.

noUncheckedIndexedAccess: true — highly recommended and little known. It makes indexed access return T | undefined, which is the truth:

isolatedModules: true — mandatory with Vite. It requires every file to be transpilable on its own, which in exchange requires export type / import type for pure types.

skipLibCheck: true — skips checking dependencies' .d.ts files. It saves a lot of time and avoids errors in code you don't control.

And the Vite environment types file, at src/vite-env.d.ts:

Without it, import.meta.env.VITE_URL_API isn't typed.

There's one rule: from the leaves to the root. You start with code that has no dependencies and work your way up.

Why that order: a typed component that imports an untyped utility receives any, and the typing is worthless. If the utility is already typed, the component inherits useful information from the very first moment.

The per-file procedure, mechanically:

1. Rename: .js → .ts, .jsx → .tsx. A file with JSX must be .tsx, no exceptions.
2. Run npm run types and read the errors.
3. Annotate the minimum: function parameters and component props. Return types are almost always inferred.
4. Update the imports in the files that use it (with moduleResolution: "bundler" you usually don't need to touch anything).
5. Run module 9's tests: they are the safety net that makes the migration safe.

Three field tips:

• Migrate in small branches. One file, or a small group, per change. An 80-file migration all at once is unreviewable.
• Ban any from day one, with the @typescript-eslint/no-explicit-any rule. An any isn't a type: it's a hole that voids the checks on everything it touches.
• If you get stuck, use unknown and narrow it afterward. It's the honest way out; any is the dishonest one.

The subset of TypeScript that shows up in a real React project is surprisingly small.

Primitives and inference. You almost never need to annotate a variable:

Literal unions, the domain's most cost-effective tool:

Compare that with status: string, which accepts 'DISPONIBLE', 'disponible ' with a trailing space, and 'plátano'. The literal union turns a data error into a compile-time error, and it also makes the editor autocomplete the three valid values.

Arrays and optionals:

Functions:

Basic generics. A generic is a type that gets decided at the point of use:

T isn't magic: it's a type parameter, just like list is a value parameter.

Both declare the shape of an object, and in 90% of cases they're interchangeable.

Real differences:

Declaration merging is the deciding factor: two interfaces with the same name merge silently. It's essential for extending library types, and dangerous for your own types, because a repeated name doesn't produce an error.

This course's practical convention:

• interface for the shape of domain entities, which can grow.
• type for unions, aliases, component props, and everything else.

any turns TypeScript off in everything it touches:

unknown is the honest unknown value: it can't be used without checking it first.

Assertions (as) are a promise, not a check:

Nothing happens at runtime: if data doesn't actually have that shape, the error will show up later, and farther from its source. Using as on an API response is the most common antipattern, and section 17 fixes it.

Type guards are the correct alternative: functions that actually check, and teach TypeScript the result with x is T.

Now if (isBike(data)) narrows the type inside the block, and the check also exists at runtime.

This is the file everything else anchors to. A single place where the shape of CicloUrbano's domain lives.

The derived types are worth pausing on, because that's where TypeScript stops being bureaucracy:

• Omit<Booking, 'id' | 'status'> builds the form's type from the entity's. If tomorrow Booking gains a discountCode field, NewBooking gains it automatically. Writing both types by hand guarantees they'll drift apart.
• Partial<Record<keyof NewBooking | 'general', string>> says BookingErrors can have one key per form field, plus 'general', and that all of them are optional. With this, errors.huors is a compile-time error: module 3's error object is now verified.
• Branded identifiers are an advanced pattern that keeps you from passing a stationId where a bicicletaId is expected. Useful in large domains; optional here.

The canonical form in React 19:

Points worth calling out:

• import type for anything that's only a type: it makes clear that import disappears at compile time, which isolatedModules appreciates.
• Record<BikeStatus, string> forces LABELS to have exactly the three keys. If you add 'reserved' to the union, this object errors out until you fill it in. That cascading effect is typing's biggest win in a domain.
• Default values go in the destructuring, and compact?: boolean is inferred as boolean inside the body.

children is typed with ReactNode, which is "anything renderable":

Extending DOM attributes with ComponentProps avoids rewriting the attribute list of a <button>:

With this, <ActionButton onClick={...} type="submit" aria-label="Book" /> is fully typed, including onClick with its correct event type, without you having written any of those props.

A generic component is one that preserves the type of the data it receives. List is the classic example:

Used with two different types, both checked:

TypeScript infers T = Bike in the first case and T = Station in the second. Inside the child function, bike. autocompletes the six fields, and bike.name errors out because bikes don't have a name. Without generics you'd have to choose between any — no checking — or duplicating the component for every type.

For years the convention was:

Reasons to abandon it:

The current convention, and this course's: a normal function with annotated props.

useState infers the type from the initial value and almost never needs help:

The generic is needed in two situations:

useRef has two uses with different typings:

You have to get the element type right: HTMLInputElement for <input>, HTMLDivElement for <div>, HTMLButtonElement for <button>. If you don't know it, write useRef<HTMLElement>(null) and the editor will tell you the correct one as soon as you assign it to a specific element.

useMemo and useCallback infer from the body and rarely need an annotation:

Notice that the useCallback parameter does need annotating: there's no context to infer it from.

This is the case that wins over skeptics. A reducer whose actions form a discriminated union lets TypeScript know, inside each case, exactly which fields that action carries.

The never trick deserves an explanation, because it's the most useful pattern in this lesson. Inside the default, TypeScript has ruled out every member of the union already handled in the preceding cases. If they're all covered, what's left is never, and the assignment const unhandled: never = action compiles. If you add { type: 'fieldTouched'; field: keyof NewBooking } to the union and don't write its case, that member is left unhandled in the default, it isn't assignable to never, and compilation fails, pointing straight at the reducer.

In other words: the type system forces you to keep the reducer complete. No unit test does that unless someone writes it.

And in the component:

All three errors are caught in the editor. In JavaScript, all three would pass silently and produce a corrupted state.

The classic problem with typed context: the default value. Setting createContext<Session | null>(null) forces every consumer to check for null, even though the provider is always present.

The solution is an access hook that narrows the type and fails loudly if the provider is missing:

Double benefit: consumers write const { user } = useSession() without checking anything, and whoever forgets the provider gets an explicit message instead of a Cannot read properties of undefined. This pattern was already recommended in 05-04; with types, it's now verified too.

Custom hooks that return tuples need as const:

Without as const, TypeScript infers an array whose elements are the union of every type involved, and destructuring const [open, toggle] = useToggle() would give open the type boolean | (() => void): unusable. With as const it infers a tuple with the exact position and type.

For more than three values, returning an object is usually more readable and doesn't need the trick:

React's event types are generic over the element that originates them.

How to find the type without memorizing it, which is what you actually need. Write the handler inline and let TypeScript infer it; then hover over the parameter and the editor will tell you the exact type:

You copy that type over to the named function. That's the real workflow: nobody memorizes these names.

The as in handleTypeChange deserves a comment: event.target.value is always string, because the DOM doesn't know about our union. Here the assertion is acceptable because we control the <option>s ourselves; in a stricter case we'd use the isBikeType guard from section 8.

Redux Toolkit is designed for TypeScript and only asks for two derived types and two typed hooks:

From here on, all the global state is typed with no extra effort:

And the slice gets typed by annotating the initial state:

PayloadAction<T> is the only thing you need to annotate: the action creators and their types are generated on their own.

TanStack Query infers the type of data from the return type of queryFn:

In the component, data is Bike[] | undefined — undefined while it's loading — and TypeScript forces you to handle that case. That's exactly the check that used to get forgotten in JavaScript and produced Cannot read properties of undefined (reading 'map').

And now the most important point in the lesson, the one that separates someone who uses TypeScript from someone who understands it.

An API response isn't typed. response.json() returns any. Writing Promise<Bike[]> in the signature checks nothing: it's a promise you make to the compiler, not a verification.

If json-server returns pricePerHour as a string, or the field gets renamed on the server, TypeScript won't say a word, and the failure will show up far away, in the component that does pricePerHour.toFixed(2).

The solution is to validate at the boundary: check the shape of the data once, at the point where it enters the application, and trust the types from then on.

z.infer is the key piece: the type is derived from the schema, not written separately. They can't drift apart.

And the query starts validating for real:

Comparing the two approaches:

When validation fails, the message pinpoints the problem precisely:

"Element 1 has pricePerHour as a string instead of a number." That's diagnosis, not guesswork.

Where it makes sense to apply this validation in CicloUrbano:

Zod is also useful, with the same schema, for validating forms: module 3's validateBooking can be rewritten as a schema and share its rules between the client and the server — including the server actions from 10-03.

Back to the pyramid, now comparing the two layers.

The conclusion is right there in the two columns: TypeScript checks the shape; tests check the behavior. Substituting one for the other doesn't work in either direction.

What TypeScript does do is eliminate an entire category of trivial tests. You no longer need to check "that the component doesn't blow up if bikes is undefined": with strict, that doesn't compile. That time gets reinvested in testing behavior, which is what matters.

And tests get typed too. With .test.tsx, Testing Library and MSW gain type checking:

Concrete benefit: if Bike gains a required field, the test fixture stops compiling. Stale mock data — a classic plague in large suites — becomes impossible.

TypeScript errors are intimidating because of their length. The technique for reading them is always the same.

Read it from the bottom up. The last line is the cause; the ones above are the path that leads to it.

• Last line: 'string' is not assignable to 'BikeType'. That's where the real problem is.
• Second-to-last: it happens on the type property.
• The ones before that: inside the object passed to the bike prop.

Diagnosis: somewhere a bike was created whose type is string instead of the union. Common cause: an unannotated object literal, or data from the API that wasn't validated.

Common beginner errors, with what they actually mean:

• Starting without strict. Without strictNullChecks, TypeScript misses most of the real bugs. Turn it on from day one; adding it to a large project later is painful.
• Using any to get past a problem. It voids checks in cascade. If you don't know the type, use unknown and narrow it.
• Trusting as with API data. It checks nothing at runtime. Validate at the boundary with Zod and derive the type from the schema.
• Believing Vite checks types. It doesn't. tsc --noEmit in the build and in CI, or typing is purely decorative.
• Writing Bike and bikeSchema separately. They drift apart. z.infer derives one from the other.
• Writing RootState by hand. It's derived with ReturnType<typeof store.getState>. Written by hand, it goes stale the moment you add a slice.
• Forgetting as const in a hook that returns a tuple. The type becomes an array of unions and destructuring stops working.
• Using React.FC. An outdated convention: adds nothing and gets in the way of generics.
• Renaming a file with JSX to .ts. It must be .tsx, or the compiler reads <Component> as a type assertion and produces baffling errors.
• Migrating from the root toward the leaves. The other way around: domain types first, then utilities and hooks, then components. Otherwise everything you import arrives as any.
• Tip: hover over things. The editor tells you the inferred type of any expression. It's faster and more reliable than searching the docs.
• Tip: turn on noUncheckedIndexedAccess. It's annoying for the first two weeks and prevents an entire family of production errors.

Exercise 1. Type this CicloUrbano component, which is currently in JavaScript. Define the props type, use the domain types, and fix the two type problems that will show up when you do.

Exercise 2. Write the typed reducer for BookingsPanel, which manages the user's list of bookings. It must support: loading the list, marking a booking as cancelled, filtering by status, and recording an error. Define BookingsState and the discriminated union BookingsAction, include the exhaustiveness never case, and demonstrate with an example what happens when you add a new action without handling it.

Exercise 3. CicloUrbano's API has started returning docks as a string on some stations, and district is sometimes missing. Write the Zod schema for Station that: validates the fields, converts docks to a number even when it arrives as a string, gives district the value 'Unassigned' when it's absent, and derives the Station type. Also write the query function that uses it, and explain exactly what happens when invalid data comes in.

Solution 1.

The two problems that surface when typing this:

1. discount might not be passed. In JavaScript, omitting it made 1 - undefined = NaN and the total displayed as "NaN €", a silent failure. When typing it, you either declare it required or give it a default value. Here the right call is discount = 0.
2. onConfirm needs an explicit signature. Without one it would be Function, and any call with the wrong arguments would compile. With (bicicletaId: string, hours: number) => void, swapping the argument order becomes a compile error.

As a bonus, bike.status === 'disponible' is now checked against the union: writing 'Disponible' would error out, because it isn't a valid value of BikeStatus.

Solution 2.

What happens when you add an action without handling it. If you extend the union:

and you don't write its case, in the default the type of action is no longer narrowed to never, but to { type: 'bookingExtended'; ... }, and compilation fails:

The error points at the exact line in the reducer. It's a free completeness check that no test provides unless you write one explicitly. Also notice { ...booking, status: 'cancelada' }: if you wrote 'cancelado', TypeScript would reject it for not belonging to BookingStatus.

Solution 3.

What happens when invalid data comes in — for example, docks: "twenty":

1. parse throws a ZodError with the exact path: [1, "docks"], i.e., the second station.
2. Since it's thrown inside queryFn, TanStack Query treats it as a query error: isError becomes true and data stays undefined.
3. The component shows its error UI — or the ErrorBoundary if useSuspenseQuery is used, per 10-03 — instead of rendering NaN.
4. The error gets logged with the offending field, so the diagnosis is immediate.

Two nuances about this schema's design. default('Unassigned') makes the derived type have district: string not optional, so components don't need to check for undefined: the uncertainty has been resolved at the boundary, which is exactly the goal. And if you'd rather tolerate partial errors instead of failing the whole query, safeParse returns { success, data, error } without throwing, which lets you discard the invalid stations and show the rest.

This lesson has completed the base of the pyramid that 09-01 left half-finished. The linter covered style and shape errors in the code; TypeScript covers the contracts, and it does so at the cheapest possible moment: while you type, with the cursor on the line of the error.

From the setup, the essential point is that TypeScript enters an existing project without rewriting it: typescript plus @types/react and @types/react-dom, a tsconfig.json with strict: true — non-negotiable —, jsx: "react-jsx", moduleResolution: "bundler", allowJs: true for coexistence, and noUncheckedIndexedAccess so indexed access tells the truth. And one warning that decides whether any of this is worth anything: Vite doesn't check types, so tsc --noEmit has to be in the build and in continuous integration. The migration goes from the leaves to the root — domain, utilities, hooks, leaf components, composite components, global state, pages — in small branches, with module 9's tests acting as a safety net.

From the language, the subset used every day is short: primitives with inference, literal unions — the domain's most cost-effective tool —, optionals, arrays, basic generics, interface for entities and type for everything else, and unknown instead of any with x is T type guards to actually narrow. src/types/domain.ts is now fixed, with Bike, Station, User, Booking, BikeType, BikeStatus, UserRole, and BookingStatus, plus the derived types NewBooking with Omit and BookingErrors with Partial<Record<...>>, which make extending an entity propagate the change to everything that depends on it.

In React, the pieces fall into place like this: props with type and default values in the destructuring; children with ReactNode; inherited DOM attributes with ComponentProps<'button'>; generic components like List<T> that preserve the element's type; and no React.FC. In hooks, useState infers except when it starts at null or []; useRef<HTMLInputElement>(null) for the DOM and useRef<number>(0) for mutable values; useContext with no default value plus an access hook that narrows the type and fails loudly if the provider is missing; and as const in custom hooks that return tuples. The case where TypeScript truly shines is useReducer with actions as a discriminated union: inside each case the exact fields are known, and the never trick in the default turns "I forgot to handle an action" into a compile error. Events aren't memorized: you write them inline, read the type the editor shows, and copy it.

With the libraries, Redux Toolkit only asks you to derive RootState and AppDispatch from the store and create typed useAppSelector/useAppDispatch; TanStack Query infers data from queryFn and forces you to handle the loading undefined. And the point that changes the way you work the most: an API response isn't typed, so you validate at the boundary with Zod and derive the type from the schema with z.infer, in a single source of truth. Everything that comes in from outside — API, localStorage, URL parameters, environment variables — goes through that filter; whatever flows between your own components is already checked by TypeScript.

And the final balance, which answers the implicit question from 09-01: TypeScript checks the shape; tests check the behavior. Types catch the misspelled prop, the field renamed across its twelve usages, and the missing case; they don't catch a wrong price calculation, a button that isn't disabled during maintenance, or an incomprehensible error message. What they do is eliminate an entire category of trivial tests, freeing up that time to test what actually matters.