Go from building components to shipping production front-ends: architecture, TypeScript, state, performance, testing, CI and code review.

Front-End Engineering

## Why it matters

A small React app can live in one `src/` folder with a handful of files. A real product cannot. After a year it has dozens of pages, hundreds of components, several API clients and a team of people changing it at the same time. When nobody can tell where a piece of code belongs, people copy it instead of reusing it, imports turn into a tangle, and every change risks breaking something far away.

Structure is not about a perfect folder tree. It is about making three questions easy to answer: where does this code live, what is it allowed to depend on, and what can I delete when a feature goes away?

## The core idea: group by feature, share deliberately

There are two common ways to organise a front-end.

**By type** puts all components in `components/`, all hooks in `hooks/`, all API calls in `api/`. It is fine for a tutorial, but a single feature such as "checkout" ends up spread across six folders.

**By feature** keeps everything one feature needs together, and only promotes code to a shared folder when a second feature actually needs it:

```text
src/
  app/                 # routing, providers, app-wide layout
  features/
    checkout/
      components/      # CheckoutForm.tsx, OrderSummary.tsx
      hooks/           # useCart.ts
      api.ts           # fetchCart, placeOrder
      types.ts         # Cart, LineItem
      index.ts         # the feature's public API
    courses/
      ...
  components/ui/       # Button, Modal, Input: no business logic
  lib/                 # apiClient.ts, formatDate.ts, logger.ts
  test/                # test helpers and fixtures
```

Most mid-size teams end up with a hybrid like this: features own their code, and a small shared layer holds design-system components (`components/ui`) and framework-free utilities (`lib`).

## Rules that keep it healthy

Folders alone do not stop the tangle. A few dependency rules do most of the work:

1. **Dependencies point inward.** `features/*` may import from `components/ui` and `lib`. `components/ui` and `lib` must never import from a feature. A Button that imports the cart is no longer reusable.
2. **Features talk through their public API.** Other code imports `features/checkout` (its `index.ts`), not `features/checkout/hooks/useCart`. That lets the checkout team move files without breaking everyone else.
3. **UI components do not fetch.** Keep data loading in hooks or page-level code and pass data down as props. Pure components are easier to test, reuse and show in a component library.
4. **Utilities are plain functions.** `formatPrice(cents, currency)` has no React, no fetch and no global state, so it can be unit tested in milliseconds.
5. **Colocate tests and styles** with the code they cover (or in a mirrored `test/` folder if your framework would treat test files as routes, as Next.js does under `pages/`).

You can enforce rule 1 with lint rules such as `import/no-restricted-paths` in ESLint, so a reviewer does not have to catch it by eye.

## Worked example: where does it go?

Your team adds a "Save for later" button to course cards.

- The heart icon button itself is generic. It goes in `components/ui/IconButton.tsx` (or reuses one that is there).
- The logic that calls `POST /api/bookmarks` and updates the list is bookmark-specific. It goes in `features/bookmarks/api.ts` and `features/bookmarks/useBookmark.ts`.
- The course card composes both. It lives in `features/courses/components/CourseCard.tsx` and imports `useBookmark` from `features/bookmarks` (the public API).
- A helper that pluralises "1 lesson / 3 lessons" is framework-free. It goes in `lib/pluralize.ts` with a test next to it.

Six months later the product team removes bookmarks. You delete `features/bookmarks/`, fix the one import in `CourseCard`, and you are done. That is the payoff.

## Naming and file size

- One component per file, named after the component: `OrderSummary.tsx` exports `OrderSummary`.
- Prefer named exports for components and utilities; they make renames and search easier.
- When a file passes a few hundred lines, look for a seam: a sub-component, a custom hook, or a pure helper you can pull out.
- Use path aliases (`@/lib/formatPrice`) instead of `../../../lib/formatPrice`, configured in `tsconfig.json` and your bundler.

## Common mistakes

- **A giant `utils.ts`.** Everything ends up there and everything imports it. Split by purpose: `formatDate.ts`, `currency.ts`, `url.ts`.
- **Premature sharing.** Moving code to `components/ui` after one use creates abstractions that fit nobody. Wait for the second real use.
- **Business logic in shared UI.** A `Button` that knows about user roles has quietly become a feature component.
- **Reorganising everything at once.** Restructure feature by feature in small pull requests, not in one rename that conflicts with every open branch.
- **Deep nesting.** Four levels of folders make paths long and imports fragile. Two or three levels are usually enough.

## Quick recap

- Group code by feature and promote it to a shared layer only when a second feature needs it.
- Keep dependencies pointing inward: features use `ui` and `lib`, never the other way round.
- Give each feature a small public API through an `index.ts`.
- Keep UI components presentational and utilities framework-free so both are easy to test.
- Enforce the rules with lint, and restructure in small steps.

## Try it

Open the Do tab and answer the quiz on where code belongs. Then look at a project you have built, sketch its current tree, and mark one file that is in the wrong place.


Organise features, components and utilities so a growing app stays easy to change.

Structuring a front-end codebase

Junior vs Senior React Folder Structure - How To Organize React Projects

## Why it matters

Most front-end bugs are shape bugs: a prop that is sometimes `undefined`, an API field that was renamed, a status string with a typo. TypeScript catches these while you type. It is now the default on most professional front-end teams, and job descriptions for mid-level developers usually assume it.

TypeScript does not run in the browser. The compiler (`tsc`, or your bundler) checks the types and then strips them, leaving plain JavaScript. That has one big consequence you will meet below: **types are not checked at runtime**, so data from the network still has to be validated.

## Typing props

Describe a component's props with a `type` (or `interface`) and annotate the parameter:

```tsx
type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary";   // optional, one of two strings
  onClick: () => void;
  disabled?: boolean;
};

export function Button({ label, variant = "primary", onClick, disabled = false }: ButtonProps) {
  return (
    <button type="button" className={`btn btn--${variant}`} onClick={onClick} disabled={disabled}>
      {label}
    </button>
  );
}
```

Now `<Button label="Save" variant="danger" />` is an error twice: `"danger"` is not an allowed variant and `onClick` is missing. A **union of string literals** (`"primary" | "secondary"`) is one of the most useful tools in UI code: it turns typos into compile errors and gives you autocomplete.

For components that wrap a native element, extend its props instead of re-listing them: `type InputProps = React.ComponentProps<"input"> & { label: string }`.

## Typing state

`useState` infers the type from the initial value. Give it a type argument when the initial value does not tell the whole story:

```tsx
const [count, setCount] = useState(0);                  // number, inferred
const [user, setUser] = useState<User | null>(null);    // null until loaded
```

For anything with several related states, model them as a **discriminated union** instead of several booleans:

```ts
type LoadState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; data: T };
```

With separate `isLoading`, `error` and `data` variables, nothing stops you from being "loading" and "error" at the same time. With the union, the `status` field decides which other fields exist, and TypeScript **narrows** the type when you check it:

```tsx
if (state.status === "success") {
  return <CourseList courses={state.data} />;   // data exists here
}
if (state.status === "error") {
  return <Alert>{state.message}</Alert>;        // message exists here
}
```

## Typing API responses

Write the response type once, next to the API call, and reuse it:

```ts
type User = { id: string; name: string; role: "admin" | "member" };

async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();   // typed as User... but nobody checked!
}
```

`res.json()` returns `any`, and the annotation is a promise you made, not a fact. If the server sends `{ "id": 7 }`, TypeScript will not notice. At the boundary, validate the data at runtime and return a discriminated result:

```ts
type ParseResult = { ok: true; user: User } | { ok: false; error: string };

function parseUser(data: unknown): ParseResult {
  if (typeof data !== "object" || data === null) return { ok: false, error: "not an object" };
  const d = data as Record<string, unknown>;
  if (typeof d.id !== "string" || d.id === "") return { ok: false, error: "id" };
  // ...check the other fields...
  return { ok: true, user: { id: d.id, name: d.name as string, role: d.role as User["role"] } };
}
```

Teams often use a schema library such as zod or valibot for this, which writes the check and the type from one definition. The idea is the same: `unknown` comes in, a checked type goes out.

## Practical habits

- Turn on `"strict": true` in `tsconfig.json`. Without it, `null` and `undefined` slip through silently.
- Prefer `unknown` over `any` for data you have not checked. `unknown` forces you to narrow before use; `any` switches checking off.
- Avoid `as` casts except right after a real runtime check. A cast is you telling the compiler to trust you.
- Run `tsc --noEmit` (often `npm run typecheck`) in CI so type errors block a merge.
- Let inference work. You rarely need to annotate local variables or return values of small functions.

## Common mistakes

- **Typing the response and trusting it.** Annotations do not validate. Check data from the network, `localStorage` and URL params.
- **Optional everything.** Marking every prop `?` hides real bugs. Make a prop optional only when the component has a sensible default.
- **Boolean soup for async state.** Replace `isLoading`/`isError`/`data` with one discriminated union.
- **Fighting the compiler with `any`.** If a type is hard to write, the shape is often too loose; simplify it.

## Quick recap

- Type props with object types and string-literal unions for variants.
- Use discriminated unions for state with several modes; checking the tag narrows the type.
- Types disappear at runtime, so validate `unknown` API data at the boundary.
- Use `strict` mode, prefer `unknown` to `any`, and run the type checker in CI.

## Try it

The in-browser sandbox runs JavaScript, not TypeScript, so in the Do tab you will write the runtime half: a `parseUser` validator that returns the same `{ ok, user }` / `{ ok, error }` union you would declare in TypeScript.


Type props, state and API responses so mistakes show up in your editor instead of in production.

TypeScript for UI

How to use TypeScript with React... But should you?

React TypeScript Tutorial - 1 - Introduction

## Why it matters

"Which state management library should we use?" is one of the most argued questions in front-end work. The better question is: **what kind of state is this?** Once you sort state into a few kinds, most of the decision makes itself, and a lot of complicated global stores turn out to be unnecessary.

## Four kinds of state

1. **Local UI state.** Belongs to one component: is this dropdown open, what has the user typed in this field, which tab is selected. Use `useState` or `useReducer` in the component that owns it.
2. **Shared client state.** Lives only in the browser but is needed in several places: the current theme, a multi-step form's draft, items in a cart before checkout. Lift it to the closest common parent, or put it in React context or a small store (Zustand, Redux Toolkit, Jotai) if many distant components need it.
3. **Server state.** Data whose source of truth is the server: the course list, the signed-in user's profile, notifications. You only hold a **cached copy** of it, which can go stale when someone else changes it.
4. **URL state.** Anything that should survive a reload or be shareable: the current page, search query, filters, the open tab (`?tab=security`). The URL is the store; read it with your router.

Two extra rules: derived values (a total computed from cart items, a filtered list) are not state at all, so compute them during render. And form state that is only read on submit can live in the DOM (uncontrolled inputs read through `FormData`).

## Server state is different

Server state has problems client state does not:

- It is **asynchronous**: you must handle loading and error.
- It can be **stale**: another tab, user or job may have changed it.
- It is **shared**: three components showing the user's name should not make three requests.
- It needs **invalidation**: after you post a comment, the comment list must refresh.

Developers often copy server data into a global store with `useEffect` and then hand-write caching, deduplication and refetching. Libraries such as **TanStack Query** (React Query), **SWR**, or a framework's data loaders do this for you:

```tsx
function useCourses() {
  return useQuery({
    queryKey: ["courses"],
    queryFn: () => fetch("/api/courses").then((r) => r.json()),
    staleTime: 60_000,          // treat data as fresh for a minute
  });
}

function CourseList() {
  const { data, isPending, isError } = useCourses();
  if (isPending) return <SkeletonList />;
  if (isError) return <Alert>Could not load courses.</Alert>;
  return data.map((c) => <CourseCard key={c.slug} course={c} />);
}
```

Every component that calls `useCourses()` shares one cached request. After a mutation you **invalidate** the key (`queryClient.invalidateQueries({ queryKey: ["courses"] })`) and the library refetches. Many apps that adopt a server-state library find their global store shrinks to a theme toggle and a few UI flags.

## A decision guide

Ask these in order:

1. Can it be **computed** from other state or props? Then compute it.
2. Should it survive a **reload or be shareable** by link? Put it in the URL.
3. Does it **come from the server**? Use your server-state tool (or framework loader).
4. Is it used by **one component** (or one small subtree)? Keep it local, lifting it up only as far as needed.
5. Is it **client-only and used far apart**? Context for rarely changing values (theme, locale, signed-in user), a small store for frequently changing ones.

## Worked example

A course catalog page has a search box, a level filter, the list of courses, a "dark mode" toggle in the header and a "compare" tray where learners pin up to three courses.

- Search text and level filter: **URL state** (`/courses?q=react&level=mid-level`), so the results can be shared.
- Course list: **server state**, keyed by the filters: `queryKey: ["courses", { q, level }]`.
- Number of results: **derived** from the list; never stored.
- Dark mode: **shared client state** in context (rarely changes, read everywhere), persisted to `localStorage` as a convenience.
- Compare tray: **shared client state** used by the card buttons and the tray; a tiny store or context with a reducer.
- Whether the filter drawer is open on mobile: **local state** in the drawer component.

## Performance notes

Context re-renders every consumer when its value changes. That is fine for a theme, but a context holding a fast-changing value (a text field, a timer) can re-render half the app. Split contexts by how often they change, or use a store with selectors so components subscribe only to the slice they read.

## Common mistakes

- **Mirroring props into state** with `useEffect`. It creates two sources of truth that drift. Use the prop, or compute from it.
- **Putting server data in a global store** and hand-writing refetch logic.
- **Storing derived data**, such as `filteredCourses`, which goes stale when the filter changes.
- **Global by default.** A modal's open flag in Redux makes every change harder to trace.
- **Forgetting invalidation** after a mutation, so the UI shows old data.

## Quick recap

- Sort state into local, shared client, server and URL state; compute derived values.
- Use a server-state library or framework loaders for remote data: caching, deduping and invalidation come for free.
- Keep state as local as possible and lift it only as far as needed.
- Use context for slow-changing global values and a store with selectors for fast-changing ones.

## Try it

Open the Do tab and classify the state in a few real scenarios.


Choose between local, global and server state, and pick the simplest tool for each.

Server and client state

React Query in 100 Seconds

React Query Makes Writing React Code 200% Better

Structure a growing codebase by feature, type props, state and API responses with TypeScript, and choose the right home for each kind of state.