The layer users touch.

• Structure (HTML) — what content exists and how it's organized semantically.
• Presentation (CSS) — what it looks like.
• Behavior (JavaScript) — what happens when users interact.

Modern frameworks blur these boundaries (CSS-in-JS, JSX, server components), but the underlying separation is still how the browser thinks. Knowing it explains why some patterns are fast and others aren't.

The job is broader than HTML/CSS/JS now:

• UI components and design systems
• State management (server, client, URL, form)
• Routing and data fetching
• Build tooling (bundlers, transpilers)
• Performance (loading, rendering, interaction)
• Accessibility
• Testing (unit, integration, end-to-end, visual)
• Type safety (TypeScript)
• Mobile (responsive web, native apps via React Native)
• Server-side rendering and the seams between server and client

This guide covers each of those, with one canonical modern stack used as the worked example: Next.js + TypeScript + Tailwind + shadcn/ui + TanStack Query. Most concepts transfer to other frameworks; the canonical stack is just to make examples concrete.

Every HTML element has implicit meaning that browsers, search engines, and screen readers use. Using <div> for everything strips that meaning.

The most common semantic mistake. Both look similar when styled, but:

• If clicking it changes the URL, it's a link (<a>). Browsers know how to right-click, open in new tab, copy, bookmark.
• If clicking it triggers an action without navigating, it's a button (<button>). Submits forms, opens dialogs, toggles state.

"Click here to read more" is a link. "Save changes" is a button. Confusing them breaks keyboard navigation and screen readers.

button {
  background: none;
  border: none;
  padding: 0;
  cursor: pointer;
  font: inherit;
  color: inherit;
}

Native form elements are wildly underrated. They handle keyboard, accessibility, validation, and mobile keyboards correctly out of the box.

<form action="/signup" method="POST">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" required autocomplete="email">

  <label for="password">Password</label>
  <input type="password" id="password" name="password"
         required minlength="8" autocomplete="new-password">

  <button type="submit">Create account</button>
</form>

What this gets you for free:

• Mobile devices show the right keyboard (type="email" shows the @ key prominently)
• Browser-native validation (required, minlength, type="email" pattern)
• Password managers offer to save credentials (autocomplete="new-password")
• Submit on Enter key works automatically
• Screen readers announce labels via for / id
• Form submits even without JavaScript (progressive enhancement)

Headings (<h1> through <h6>) form a hierarchical outline. Screen reader users navigate by headings; search engines use them to understand content structure.

Rules:

• One <h1> per page (usually the page title).
• Don't skip levels — <h2> follows <h1>, <h3> follows <h2>.
• Headings describe content, not size. If you want a small font, use CSS, not <h6>.

<img
  src="/photo-800.jpg"
  srcset="/photo-400.jpg 400w, /photo-800.jpg 800w, /photo-1600.jpg 1600w"
  sizes="(max-width: 600px) 400px, 800px"
  alt="Person walking through a forest at sunset"
  width="800"
  height="600"
  loading="lazy"
/>

What each attribute does:

• srcset — multiple sizes; browser picks the best for device + viewport.
• sizes — tells the browser how big the image will display, so it can pick the right srcset entry.
• alt — text alternative for screen readers and broken image fallback. Required.
• width/height — reserves space before the image loads (prevents layout shift).
• loading="lazy" — defers loading until the image is near the viewport.

<picture>
  <source media="(max-width: 600px)" srcset="/hero-mobile.jpg">
  <source media="(max-width: 1200px)" srcset="/hero-tablet.jpg">
  <img src="/hero-desktop.jpg" alt="..." >
</picture>

<picture>
  <source srcset="/photo.avif" type="image/avif">
  <source srcset="/photo.webp" type="image/webp">
  <img src="/photo.jpg" alt="...">
</picture>

Every element is a box with four layers, from inside out: content → padding → border → margin.

The default box-sizing (content-box) computes width based on content only, with padding/border added on top. This is almost never what you want. Set box-sizing: border-box globally:

*, *::before, *::after {
  box-sizing: border-box;
}

Now width: 300px means the box is 300px including padding and border. Tailwind, every modern framework, every reset stylesheet does this. It's effectively the new default.

When items go in a row (or a column), Flexbox is right. Navbars, cards in a row, button groups, anything where you align items along a single axis.

.row {
  display: flex;
  gap: 16px;              /* space between children */
  align-items: center;    /* vertical alignment of items */
  justify-content: space-between;  /* horizontal distribution */
}

Key properties:

• flex-direction: row (default) or column.
• justify-content: aligns along the main axis (horizontal for row).
• align-items: aligns along the cross axis (vertical for row).
• gap: space between items. Replaces all the margin tricks.
• flex: 1 on a child: take up remaining space.
• flex-wrap: wrap: items wrap to new lines when they overflow.

When you need rows AND columns at the same time. Page layouts, dashboards, photo galleries.

.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
  gap: 16px;
}

That single line: as many columns as fit, each at least 240px wide, growing to fill the space equally. No media queries needed for responsive grids.

:root {
  --color-primary: #9C3D1F;
  --color-text: #1a1a1a;
  --space-md: 16px;
  --font-body: 'Inter', system-ui, sans-serif;
}

.button {
  background: var(--color-primary);
  padding: var(--space-md);
  font-family: var(--font-body);
}

Unlike Sass variables, CSS custom properties are runtime — they can change with media queries, with class changes, with JavaScript. This is how dark mode works:

:root {
  --bg: white;
  --text: black;
}
[data-theme="dark"] {
  --bg: #0e0f10;
  --text: #0E0E0E;
}
body {
  background: var(--bg);
  color: var(--text);
}

Toggle data-theme="dark" on the root element and every element using these variables updates instantly.

The new big thing. Style a component based on its container's size, not the viewport.

.card-container {
  container-type: inline-size;
}

.card {
  display: block;
}

@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }
}

Now the card layout responds to its parent container's width, not the window's width. A card in a sidebar stays narrow even on a wide screen. A card in a wide main area gets the wide layout. The component is truly self-contained.

RGB and HSL are the legacy color spaces. Modern CSS supports OKLCH, a perceptually uniform color space.

color: oklch(70% 0.15 30);  /* lightness, chroma, hue */

Why it matters: in HSL, two colors with the same "lightness" can look very different (yellow looks lighter than blue at the same HSL lightness). In OKLCH, equal lightness values produce equally light-looking colors. This makes generating accessible color palettes mathematical instead of artistic.

Browsers ship with default styles that vary slightly. A reset normalizes them. Modern minimal reset:

*, *::before, *::after { box-sizing: border-box; }

* { margin: 0; }

html, body { height: 100%; }

body {
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

img, picture, video, canvas, svg {
  display: block;
  max-width: 100%;
}

input, button, textarea, select { font: inherit; }

p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; }

Tailwind ships its own reset (Preflight) which is similar.

Apply classes that map to single CSS properties. flex = display: flex. p-4 = padding: 16px. text-lg = font-size: 1.125rem.

<button class="rounded-md bg-orange-500 px-4 py-2 text-white hover:bg-orange-600">
  Save
</button>

Looks ugly. Reads great. The class name is the CSS, so you never context-switch between HTML and a stylesheet.

Wins:

• Constraints — no arbitrary values, no "is this color #9C3D1F or #d97743?"
• No naming things — no BEM, no CSS-in-JS API to learn.
• Dead-code elimination — utilities not used in your HTML get stripped from the final CSS.
• Fast iteration — change a class, see the result.
• Componentize when patterns emerge (extract a React component, not a CSS class).

Costs:

• HTML gets verbose. Long class lists are intimidating at first.
• Need to learn the utility shorthand (lots of it).
• Doesn't enforce design system the way a structured token system does.

Write regular CSS in a .module.css file. Import it as a JS object. Class names get auto-scoped.

/* Button.module.css */
.primary {
  background: orange;
  padding: 8px 16px;
}

/* Button.tsx */
import styles from './Button.module.css';
<button className={styles.primary}>Save</button>

The compiled output uses unique class names like Button_primary__a8f3b, so there's no global namespace conflict.

Right when: you want regular CSS with scoping, your team is more comfortable with traditional stylesheets than utility classes.

Write CSS as JavaScript template literals. Styles can use props/state.

const Button = styled.button`
  background: ${props => props.primary ? 'orange' : 'gray'};
  padding: 8px 16px;
`;

Wins: dynamic styles based on props, co-located with components.

Costs: runtime cost (CSS injected during render), no longer recommended for new projects in 2026 — the React Server Components model breaks most CSS-in-JS libraries' assumptions.

Not a library you install. A CLI that copies component code into your repo. You own the components, modify them freely, no version-pinning hell.

$ npx shadcn-ui@latest add button
# generates components/ui/button.tsx in your project

Built on Radix UI primitives (accessible, unstyled) + Tailwind for styling. Has become the default starting point for most modern apps.

The color/spacing/typography values that get reused across the system. In Tailwind, they live in tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3ee',
          500: '#9C3D1F',
          900: '#5a2810',
        },
      },
      spacing: {
        18: '4.5rem',
      },
    },
  },
};

Now bg-brand-500 works as a utility. The token system is enforced by the framework — no rogue hex colors.

• const — block-scoped, can't be reassigned. Default for almost everything.
• let — block-scoped, can be reassigned. Use when reassignment is the point (loop counters, mutating values).
• var — function-scoped, hoisted. Don't use. Legacy.

"Const" doesn't mean "immutable" — const arr = []; arr.push(1); works fine. It means "the binding can't be reassigned." For true immutability, use Object.freeze() or libraries like Immer.

// function declaration — hoisted, has its own `this`
function greet(name) { return `Hello, ${name}`; }

// arrow function — not hoisted, inherits `this` from enclosing scope
const greet = (name) => `Hello, ${name}`;

Use arrows for callbacks, inline functions, methods that need to capture this from outside. Use function declarations for top-level helpers and recursive functions.

const user = { name: 'Alex', email: 'a@b.com', age: 30 };

// extract into variables
const { name, email } = user;

// rename
const { name: userName } = user;

// defaults
const { phone = 'none' } = user;

// arrays
const [first, second, ...rest] = [1, 2, 3, 4, 5];

// in function parameters
function greet({ name, email }) { ... }

// spread (expand)
const newUser = { ...user, age: 31 };  // copy with override
const newArr = [...arr1, ...arr2];      // merge arrays

// rest (collect)
function sum(...nums) { return nums.reduce((a, b) => a + b, 0); }

The good way to handle promises. Replaces .then().catch() chains for most cases.

async function fetchUser(id) {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const user = await res.json();
    return user;
  } catch (err) {
    console.error('Failed to fetch user', err);
    throw err;
  }
}

// run multiple in parallel, wait for all
const [user, posts, comments] = await Promise.all([
  fetchUser(id),
  fetchPosts(id),
  fetchComments(id),
]);

// run multiple, get whichever finishes first
const result = await Promise.race([
  fetch(url),
  new Promise((_, reject) => setTimeout(() => reject('timeout'), 5000)),
]);

// run multiple, get all results (success or failure)
const results = await Promise.allSettled([fetchA(), fetchB(), fetchC()]);
results.forEach(r => {
  if (r.status === 'fulfilled') console.log(r.value);
  else console.error(r.reason);
});

// utils.js
export function add(a, b) { return a + b; }
export const PI = 3.14;
export default function multiply(a, b) { return a * b; }

// app.js
import multiply, { add, PI } from './utils.js';
import * as utils from './utils.js';

Browsers and Node both support ES modules natively now. CommonJS (require/module.exports) is legacy in new code.

class Counter {
  constructor() {
    this.count = 0;
    document.getElementById('btn').addEventListener('click', this.increment);
  }
  increment() {
    this.count++;  // ❌ `this` is the button, not the Counter
  }
}

// option 1: arrow function as class property
class Counter {
  count = 0;
  increment = () => { this.count++; };  // arrow inherits `this`
}

// option 2: bind in constructor
constructor() {
  this.increment = this.increment.bind(this);
}

// option 3: arrow in addEventListener call
btn.addEventListener('click', () => this.increment());

== does type coercion ('5' == 5 is true). Confusing and error-prone. Always use ===. The ESLint eqeqeq rule enforces this.

// optional chaining: ?. returns undefined if any step is null/undefined
const city = user?.address?.city;  // no error if address is missing

// nullish coalescing: ?? falls back only on null/undefined
const port = process.env.PORT ?? 3000;
// vs ||, which also falls back on '', 0, false

• Map — like an object, but keys can be anything (objects, functions). Maintains insertion order. Use when keys aren't strings.
• Set — collection of unique values. Use for deduplication.
• WeakMap/WeakSet — keys are objects, values are garbage-collected when the key has no other references. Useful for caches keyed on object identity.

const seen = new Set();
arr.filter(item => {
  if (seen.has(item.id)) return false;
  seen.add(item.id);
  return true;
});  // dedupe by id

// forEach — side effects, no return
arr.forEach(item => console.log(item));

// map — transform each, returns new array
const doubled = arr.map(x => x * 2);

// filter — keep matching, returns new array
const evens = arr.filter(x => x % 2 === 0);

// reduce — fold to single value
const sum = arr.reduce((acc, x) => acc + x, 0);

// find — first match, returns single item or undefined
const first = arr.find(x => x.id === 5);

// some / every — boolean checks
const hasAdult = users.some(u => u.age >= 18);
const allAdults = users.every(u => u.age >= 18);

// for...of — works on any iterable, can use await/break
for (const item of arr) { ... }

// Object.entries for iterating objects
for (const [key, value] of Object.entries(obj)) { ... }

The shift happened around 2020-2022. Today, almost every major framework, library, and SDK ships with TypeScript types. Writing JavaScript without types in 2026 is like writing Python without type hints — possible, but you give up tooling.

// primitives
const name: string = 'Alex';
const age: number = 30;
const active: boolean = true;

// arrays
const ids: number[] = [1, 2, 3];
const names: Array<string> = ['a', 'b'];

// objects (interfaces or types)
interface User {
  id: number;
  name: string;
  email: string;
  age?: number;  // optional
}

type User = {
  id: number;
  name: string;
};
// interface vs type — mostly interchangeable; interface for objects, type for unions/aliases

// functions
function greet(name: string): string {
  return `Hello, ${name}`;
}

const greet = (name: string): string => `Hello, ${name}`;

// union — value can be any of these
type Status = 'pending' | 'active' | 'banned';
type ID = string | number;

// intersection — value must satisfy all
type EmployeeUser = User & { employeeId: string };

TypeScript follows your control flow. Inside an if that checks a type, the variable is narrowed.

function format(value: string | number): string {
  if (typeof value === 'string') {
    return value.toUpperCase();  // TS knows it's a string here
  }
  return value.toFixed(2);  // TS knows it's a number here
}

Functions and types that work with multiple types while preserving type information.

function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

const num = first([1, 2, 3]);   // typed as number | undefined
const str = first(['a', 'b']);  // typed as string | undefined

Common in API client code:

async function fetchJSON<T>(url: string): Promise<T> {
  const res = await fetch(url);
  return res.json();
}

const user = await fetchJSON<User>('/api/users/1');
// user is typed as User

type User = { id: number; name: string; email: string; age?: number; };

// Partial — all fields optional
type UserUpdate = Partial<User>;  // { id?: number; name?: string; ... }

// Required — all fields required
type CompleteUser = Required<User>;

// Pick — select specific fields
type UserSummary = Pick<User, 'id' | 'name'>;

// Omit — exclude specific fields
type UserPublic = Omit<User, 'email'>;

// Record — object with specific keys/values
type UsersById = Record<number, User>;

// ReturnType — extract function's return type
type Fetched = ReturnType<typeof fetchUser>;

The pattern that makes TypeScript click. A field tags which variant of a union you have.

type State =
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; error: string };

function render(state: State) {
  switch (state.status) {
    case 'loading':
      return <Spinner />;
    case 'success':
      return <UserCard user={state.data} />;  // TS knows data is here
    case 'error':
      return <Error message={state.error} />;
  }
}

TypeScript has two parallel namespaces. User can be a type AND a value (a class or const). They're separate.

// declaring both:
class User {
  constructor(public name: string) {}
}
// `User` is now both a type (the instance shape) and a value (the constructor)

// usually you want just the type:
type User = { name: string };  // type only, no runtime presence

TypeScript types vanish at runtime. They don't validate API responses or user input. Zod fills that gap:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().optional(),
});

type User = z.infer<typeof UserSchema>;
// type derived from schema — no duplication

// validate at runtime:
const user = UserSchema.parse(jsonResponse);
// throws if invalid; user is fully typed

// safe parse:
const result = UserSchema.safeParse(input);
if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
}

The pattern: define a schema, derive the type, validate at trust boundaries (API responses, form input, env vars).

function Greeting({ name }) {
  return <h1>Hello, {name}</h1>;
}

// usage
<Greeting name="Alex" />

That's the entire model: a function that takes props (input) and returns JSX (output). Composed by writing one component inside another.

JSX looks like HTML but compiles to function calls. <div className="x">hi</div> becomes React.createElement('div', { className: 'x' }, 'hi'). You can put any JavaScript expression in { }.

function UserList({ users }) {
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          {user.name} ({user.age >= 18 ? 'adult' : 'minor'})
        </li>
      ))}
    </ul>
  );
}

When rendering lists, every item needs a stable, unique key prop. React uses keys to match elements between renders.

• Use IDs from your data — user.id.
• Don't use array index if items can reorder/insert/delete (causes bugs).
• Don't use Math.random() — defeats the purpose; React thinks every render is a different list.

import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  );
}

Calling setCount tells React "the state changed, re-run this component." React calls the function again with the new state.

The mental model: your component is a function from state to UI. State changes → function runs again → new UI.

For side effects: data fetching, subscriptions, manual DOM manipulation, anything that interacts with the world outside React.

useEffect(() => {
  // runs after the component renders
  const subscription = subscribe(data => setItems(data));

  return () => {
    // cleanup function — runs before re-running effect or unmount
    subscription.unsubscribe();
  };
}, [/* dependencies */]);

The dependency array controls when the effect re-runs:

• [] — run once on mount.
• [someValue] — re-run when someValue changes.
• No array — run after every render (rarely what you want).

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    setLoading(true);
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(data => { setUser(data); setLoading(false); });
  }, [userId]);

  // ...
}

const { data: user, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
});

• useRef — mutable value that persists across renders without triggering re-renders. For DOM refs, timers, and instance values.
• useMemo — caches an expensive computation between renders.
• useCallback — caches a function reference between renders (rare; usually unnecessary).
• useContext — read a value from a parent Context provider without prop drilling.
• useReducer — useState's bigger sibling for complex state logic.

The composition mechanism. Any function starting with use that calls other hooks is a custom hook. Lets you extract logic for reuse.

function useLocalStorage(key, initialValue) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key);
    return stored ? JSON.parse(stored) : initialValue;
  });

  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue];
}

// use it like a regular hook:
const [theme, setTheme] = useLocalStorage('theme', 'light');

The biggest React change in years. With React 18+ and frameworks like Next.js App Router:

• Server Components (default) — run on the server, can read databases directly, return rendered output. Don't ship JS to client. No state, no hooks like useState/useEffect.
• Client Components — marked with "use client" directive. Run in the browser. Can have state, effects, event handlers.

// server component (default)
async function UserList() {
  const users = await db.query("SELECT * FROM users");
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// client component
'use client';
import { useState } from 'react';
function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>{n}</button>;
}

Mental model: server by default, client when interactivity demands it. The bundle ships only client components and their dependencies.

File-based routing where folders are URL segments and special filenames have meaning.

app/
  layout.tsx              → wraps all routes
  page.tsx                → /
  about/
    page.tsx              → /about
  blog/
    [slug]/
      page.tsx            → /blog/:slug
  (auth)/                 → grouping, doesn't appear in URL
    login/page.tsx        → /login
    signup/page.tsx       → /signup
  api/
    users/
      route.ts            → /api/users (API endpoint)

Special files:

• page.tsx — the route's UI.
• layout.tsx — wraps children, persists across navigation.
• loading.tsx — shown while the page is loading.
• error.tsx — error boundary.
• not-found.tsx — 404 UI.
• route.ts — API endpoint (replaces pages/api).

// app/users/page.tsx — server component
async function UsersPage() {
  const users = await db.query("SELECT * FROM users");
  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users.map(u => <li key={u.id}>{u.name}</li>)}
      </ul>
    </div>
  );
}
export default UsersPage;

This component:

• Runs on the server only.
• Direct database access — no API layer needed.
• Ships zero JS to the client.
• Renders to HTML; client gets the rendered output.

Functions marked with "use server" run on the server but can be called from client components.

// app/users/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createUser(formData: FormData) {
  const name = formData.get('name');
  await db.execute("INSERT INTO users (name) VALUES (?)", [name]);
  revalidatePath('/users');
}

// app/users/new/page.tsx
import { createUser } from '../actions';

export default function NewUserPage() {
  return (
    <form action={createUser}>
      <input name="name" />
      <button type="submit">Create</button>
    </form>
  );
}

The form posts directly to the server function. No API endpoint, no JSON, no manual fetch. Next.js handles serialization, the network call, and cache invalidation.

Next.js supports multiple rendering modes per route:

// static (default for server components without dynamic data)
export default async function Page() {
  const data = await fetch('https://...').then(r => r.json());
  return ...;
}

// ISR — revalidate every 60 seconds
export const revalidate = 60;

// force dynamic (always SSR)
export const dynamic = 'force-dynamic';

// streaming — wrap slow parts in Suspense
import { Suspense } from 'react';
<Suspense fallback={<Loading />}>
  <SlowComponent />
</Suspense>

app/
  layout.tsx                    # Root: html, body, providers
  page.tsx                      # / (landing)
  (marketing)/                  # group with shared layout
    layout.tsx
    pricing/page.tsx
    about/page.tsx
  (app)/                        # authenticated app
    layout.tsx                  # checks auth, renders shell
    dashboard/
      page.tsx                  # /dashboard
      loading.tsx               # skeleton while loading
    settings/
      page.tsx
      profile/page.tsx
  api/
    webhooks/
      stripe/route.ts           # POST /api/webhooks/stripe
  components/
    ui/                         # shadcn primitives
    nav/                        # nav components
  lib/
    db.ts                       # database client
    auth.ts                     # auth helpers
    actions/                    # server actions

Next.js caches aggressively. Understanding the layers:

• Request memoization — same fetch in one request returns cached result.
• Data cache — fetch results cached across requests, configurable TTL.
• Full route cache — rendered route HTML cached.
• Router cache — client-side cache of visited routes.

// fetch with caching control
fetch(url);                          // cached forever (until revalidated)
fetch(url, { cache: 'no-store' });   // never cache
fetch(url, { next: { revalidate: 60 } });  // cache for 60s

// invalidate by tag
fetch(url, { next: { tags: ['users'] } });
// later:
import { revalidateTag } from 'next/cache';
revalidateTag('users');

// invalidate by path
import { revalidatePath } from 'next/cache';
revalidatePath('/users');

import Image from 'next/image';
import { Inter } from 'next/font/google';

const inter = Inter({ subsets: ['latin'] });

export default function Page() {
  return (
    <div className={inter.className}>
      <Image src="/photo.jpg" width={800} height={600} alt="..." />
    </div>
  );
}

next/image automatically: lazy-loads, generates responsive srcsets, serves modern formats (WebP/AVIF), preserves aspect ratio.

next/font downloads fonts at build time, self-hosts them (no CLS, no third-party request), generates fallback metrics.

Most state belongs in one of the first three categories. Global client state is rare in well-designed apps.

The single biggest improvement to React data fetching in years. Covered in detail in the API clients section, but the model:

const { data, isLoading, error } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

const mutation = useMutation({
  mutationFn: updateUser,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  },
});

You declare what data you want; the library handles caching, deduplication, retries, refetch-on-focus, optimistic updates.

Filters, search queries, current tab, pagination — these belong in the URL. The URL is shareable; the back button works; it survives refresh.

// Next.js App Router
'use client';
import { useSearchParams, useRouter } from 'next/navigation';

function Filters() {
  const params = useSearchParams();
  const router = useRouter();
  const status = params.get('status') ?? 'all';

  return (
    <select
      value={status}
      onChange={(e) => {
        const next = new URLSearchParams(params);
        next.set('status', e.target.value);
        router.push(`?${next}`);
      }}
    >
      <option value="all">All</option>
      ...
    </select>
  );
}

Or use nuqs for typed URL state with a hook-like API.

The 2026 default for forms.

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const Schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});
type FormData = z.infer<typeof Schema>;

function SignupForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(Schema),
  });

  return (
    <form onSubmit={handleSubmit(async (data) => { ... })}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}

      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}

      <button type="submit">Sign up</button>
    </form>
  );
}

The schema is the source of truth — validation, types, and the form structure all derive from it.

If state belongs to one component, useState is the answer. Modal open state, hover state, expanded panel — all useState.

For state that's truly global (theme, sidebar collapsed, auth user) and not server data. Zustand is the modern choice — small, no boilerplate, no providers.

import { create } from 'zustand';

const useAuthStore = create<AuthState>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
  logout: () => set({ user: null }),
}));

// in any component:
function Header() {
  const { user, logout } = useAuthStore();
  return user ? <UserMenu user={user} onLogout={logout} /> : <LoginButton />;
}

Common mistakes:

• Server data in Zustand/Redux. You end up reimplementing caching, refetching, and invalidation. Use TanStack Query.
• URL state in component state. Filters that don't survive refresh, can't be shared. Move to URL.
• Global state for things that should be local. Modal open state in Redux is a code smell.
• Form state in component useState. Reinventing validation, dirty-checking, error display. Use React Hook Form.

• Submit on Enter from any input.
• Tab order follows visual order.
• Disabled submit button while submitting (prevents double-submit).
• Error messages tied to the field they describe (with aria-describedby).
• Loading state while submitting.
• Success state after submit (toast, redirect, or inline confirmation).
• Mobile keyboards match input type.
• Autocomplete attributes for browser autofill.

React Hook Form's mode: 'onTouched' implements the last pattern.

const Schema = z.object({
  email: z
    .string()
    .min(1, 'Email is required')
    .email('Must be a valid email'),

  password: z
    .string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Must contain an uppercase letter')
    .regex(/[0-9]/, 'Must contain a number'),

  age: z.coerce.number().min(13, 'Must be 13 or older'),

  terms: z.literal(true, { errorMap: () => ({ message: 'You must accept the terms' }) }),
});

Client-side validation is a UX feature. Server-side validation is a security requirement. Always validate on the server too — clients can be bypassed.

// app/users/actions.ts
'use server';

import { z } from 'zod';

const SignupSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

export async function signup(formData: FormData) {
  const result = SignupSchema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
  });

  if (!result.success) {
    return { error: result.error.flatten().fieldErrors };
  }

  // safe to use result.data
  await createUser(result.data);
}

The same Zod schema can be used on client and server — Single source of truth for validation.

function ContactForm() {
  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm();
  const [submitted, setSubmitted] = useState(false);

  const onSubmit = async (data) => {
    try {
      await sendContact(data);
      setSubmitted(true);
    } catch (err) {
      toast.error('Something went wrong. Please try again.');
    }
  };

  if (submitted) return <SuccessMessage />;

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('name')} disabled={isSubmitting} />
      <input {...register('email')} disabled={isSubmitting} />
      <textarea {...register('message')} disabled={isSubmitting} />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Sending...' : 'Send message'}
      </button>
    </form>
  );
}

The new pattern progressively enhances forms. Forms work without JavaScript and get richer with it.

// no JavaScript needed for the basic case
<form action={signup}>
  <input name="email" />
  <input name="password" type="password" />
  <button type="submit">Sign up</button>
</form>

// add useActionState for client-side feedback
'use client';
import { useActionState } from 'react';
import { signup } from './actions';

function SignupForm() {
  const [state, action, pending] = useActionState(signup, { error: null });

  return (
    <form action={action}>
      <input name="email" />
      {state.error?.email && <span>{state.error.email[0]}</span>}
      ...
      <button disabled={pending}>{pending ? 'Signing up...' : 'Sign up'}</button>
    </form>
  );
}

Form posts to the server action; result comes back; UI updates. Works with JS off (just no inline error display).

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function UserProfile({ userId }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
    staleTime: 5 * 60 * 1000,    // 5 min
    refetchOnWindowFocus: true,   // default
  });

  if (isLoading) return <Skeleton />;
  if (error) return <ErrorState />;
  return <Profile user={user} />;
}

• Deduplication — two components with the same query key share one network request and cache entry.
• Caching — data lives in memory, configurable freshness (staleTime).
• Background refetch — refetch when window regains focus or network reconnects.
• Retry logic — exponential backoff on errors, configurable.
• Pagination — built-in helpers for offset and cursor pagination.
• Infinite scroll — useInfiniteQuery composes pages.
• Optimistic updates — apply changes immediately, roll back on error.
• Stale-while-revalidate — show cached data instantly, refresh in background.

function useCreatePost() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (post) => fetch('/api/posts', {
      method: 'POST',
      body: JSON.stringify(post),
    }).then(r => r.json()),

    onSuccess: () => {
      // refetch the posts list after creating a new one
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },
  });
}

// usage
const createPost = useCreatePost();
<button onClick={() => createPost.mutate({ title, body })}>Create</button>

const likeMutation = useMutation({
  mutationFn: (postId) => fetch(`/api/posts/${postId}/like`, { method: 'POST' }),

  onMutate: async (postId) => {
    // cancel in-flight refetches
    await queryClient.cancelQueries({ queryKey: ['post', postId] });

    // snapshot previous state for rollback
    const previous = queryClient.getQueryData(['post', postId]);

    // optimistically update
    queryClient.setQueryData(['post', postId], old => ({
      ...old,
      liked: true,
      likeCount: old.likeCount + 1,
    }));

    return { previous };
  },

  onError: (err, postId, ctx) => {
    // rollback on failure
    queryClient.setQueryData(['post', postId], ctx.previous);
  },

  onSettled: (data, err, postId) => {
    // refetch canonical state after success or failure
    queryClient.invalidateQueries({ queryKey: ['post', postId] });
  },
});

The user sees instant feedback. The network call is invisible unless it fails.

For cleaner code, use the Suspense version:

const { data: user } = useSuspenseQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
});
// data is never undefined; component suspends while loading

function UserPage() {
  return (
    <Suspense fallback={<Skeleton />}>
      <UserProfile userId={123} />
    </Suspense>
  );
}

With Server Components, a lot of data fetching moves to the server:

// server component — no useQuery needed
async function UserList() {
  const users = await db.query("SELECT * FROM users");
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

The rule: fetch on the server when possible, on the client when interactivity demands it. Initial data loads should be server-rendered. Refetches, mutations, real-time updates happen on the client with TanStack Query.

The dominant framework. JSX-based. Component-as-function model. Re-renders on state changes; reconciler diffs the virtual DOM.

Strengths: ecosystem (every library has React bindings), hiring (most engineers know it), Next.js, React Native for mobile.

Weaknesses: performance requires care (everything re-renders by default), bundle size, the hooks rules learning curve.

Single-file components (.vue files with template, script, style). Templates use directives like v-if, v-for. Reactive system is fine-grained (only changed parts re-render).

<template>
  <button @click="count++">Count: {{ count }}</button>
</template>
<script setup>
import { ref } from 'vue';
const count = ref(0);
</script>

Strengths: gentler learning curve, fine-grained reactivity, official tooling (Vue Router, Pinia, Nuxt), great docs.

Weaknesses: smaller ecosystem than React, less common in US/EU job market.

A compiler, not a runtime framework. Compiles components to vanilla JS. No virtual DOM; updates the actual DOM directly.

<script>
  let count = 0;
</script>
<button on:click={() => count++}>Count: {count}</button>

Strengths: tiny bundles (often 5-10x smaller than React equivalents), beautifully simple syntax, fast.

Weaknesses: smaller ecosystem, fewer libraries, smaller talent pool.

JSX syntax like React, fine-grained reactivity like Vue/Svelte. Components only run once; reactivity happens at the signal level.

function Counter() {
  const [count, setCount] = createSignal(0);
  return <button onClick={() => setCount(count() + 1)}>
    Count: {count()}
  </button>;
}

Strengths: fastest framework in benchmarks, JSX familiarity, no re-render performance traps.

Weaknesses: small ecosystem, signals require a different mental model, less mature than React.

Multi-page-app framework with islands of interactivity. Renders mostly static HTML, hydrates only the components that need it.

Right for: content sites, blogs, marketing pages, docs. Anywhere most of the page is static.

Wrong for: heavily interactive apps. Astro's strength is shipping less JS, which conflicts with app-like interactivity.

Resumability, not hydration. Apps work immediately on load — JS is lazy-loaded only when interaction needs it.

Right for: sites where time-to-interactive matters more than developer ergonomics. Marketing pages, e-commerce.

Wrong for: apps where the developer experience compromises hurt productivity more than the perf gains help.

Same React knowledge, native mobile output. <View> instead of <div>, <Text> instead of <p>, native components instead of HTML.

import { View, Text, Pressable } from 'react-native';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <View>
      <Text>Count: {count}</Text>
      <Pressable onPress={() => setCount(c => c + 1)}>
        <Text>Increment</Text>
      </Pressable>
    </View>
  );
}

Expo is the typical starting point — handles the build pipeline, native modules, OTA updates. Supports the new architecture (Fabric + TurboModules) which closes the perf gap with native code substantially.

Trade-off: code reuse with web is partial, not total. Layout (Flexbox), state management, business logic transfer cleanly. Components, navigation, and styling are platform-specific.

These directly affect SEO ranking. They also correlate with conversion and engagement.

The LCP element is usually a hero image, a headline, or a large block of text. Make sure it's:

• Server-rendered — don't block on JS to show critical content.
• Preloaded — <link rel="preload" as="image" href="/hero.jpg"> for hero images.
• Optimized format — AVIF or WebP, with JPEG fallback.
• Right-sized — don't ship a 4000px image to a 600px container.
• Not lazy-loaded — lazy-loading the LCP image delays it. Use loading="eager" for above-the-fold images.

INP measures the latency from user input to the next paint. Common causes of bad INP:

• Long JavaScript tasks blocking the main thread.
• Large component re-renders on every keystroke.
• Synchronous work in event handlers (parsing, sorting, filtering big lists).

The fixes:

• Debounce rapid events (search input).
• Defer non-critical work with requestIdleCallback or scheduler.yield().
• Use React's useDeferredValue for expensive renders that depend on fast-changing input.
• Virtualize long lists (react-window, react-virtuoso) — render only visible items.

The killers:

• Images without dimensions. Always specify width and height, or use aspect-ratio CSS.
• Late-loading fonts. Causes FOUT (flash of unstyled text). Use font-display: optional or preload fonts.
• Ads and embeds without reserved space. Reserve space with min-height or aspect-ratio containers.
• Late-injected banners. Cookie banners that push content down. Reserve their space ahead of time.

Don't ship one 5MB JS file. Split by route, lazy-load heavy components, defer third-party scripts.

// route-based splitting (automatic in Next.js)
// each route has its own bundle

// dynamic import for heavy components
import dynamic from 'next/dynamic';
const Chart = dynamic(() => import('./Chart'), {
  loading: () => <Skeleton />,
  ssr: false,  // skip server rendering for this component
});

// React.lazy with Suspense (without Next.js)
const Chart = React.lazy(() => import('./Chart'));
<Suspense fallback={<Skeleton />}>
  <Chart />
</Suspense>

// Next.js
import Image from 'next/image';

<Image
  src="/photo.jpg"
  alt="..."
  width={800}
  height={600}
  priority   // for above-the-fold; sets loading=eager and fetchpriority=high
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."  // tiny preview
/>

next/image handles: format negotiation (WebP/AVIF), responsive srcset, lazy-loading, blur-up placeholders.

// next/font — handles everything correctly
import { Inter } from 'next/font/google';
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',  // show fallback then swap when font loads
});

The display options matter:

• swap — show fallback immediately, swap when font loads. Causes FOUT but text is visible.
• optional — show fallback; only swap if font loads quickly (otherwise stick with fallback). No layout shift.
• block — invisible text until font loads. Hurts LCP.

Set targets and measure against them:

• Initial JS: < 100KB compressed
• Initial CSS: < 50KB compressed
• Total page weight: < 1MB
• LCP: < 2.5s on slow 4G
• INP: < 200ms p75
• CLS: < 0.1

Tools to measure: Lighthouse (built into Chrome DevTools), PageSpeed Insights, WebPageTest, Vercel Analytics.

Web Content Accessibility Guidelines. Three conformance levels: A (basic), AA (target for most apps), AAA (extra strict). Most legal compliance regimes (ADA, EAA, AODA) align with WCAG 2.1 or 2.2 Level AA.

• Perceivable — users can perceive the content (alt text, captions, contrast).
• Operable — users can operate the interface (keyboard, no time traps).
• Understandable — content and operation are clear (labels, error messages).
• Robust — works with assistive technologies (screen readers, voice).

ARIA (Accessible Rich Internet Applications) attributes provide info that HTML can't express. Use only when needed; bad ARIA is worse than no ARIA.

Common patterns:

• aria-label — labels an element when there's no visible label.
• aria-describedby — points to an element that describes this one (error messages, hints).
• aria-live — announces dynamic content changes ("polite" or "assertive").
• aria-expanded — indicates collapsed/expanded state.
• aria-current — marks the current item in a set (current page in nav).
• aria-hidden — hides decorative content from screen readers.

<button aria-expanded={open} aria-controls="menu">
  Menu
</button>
<ul id="menu" hidden={!open}>
  <li>...</li>
</ul>

<input aria-describedby="email-error" type="email" />
<span id="email-error" role="alert">Email is required</span>

The only way to know if your app works for screen reader users is to use a screen reader.

• VoiceOver (Mac) — Cmd+F5 to toggle. Built in.
• NVDA (Windows) — free download, the most-used screen reader.
• TalkBack (Android), VoiceOver (iOS) — for mobile testing.

The 2026 way: use a library that gives you accessible behavior without imposing styling.

• Radix UI — fully unstyled, fully accessible primitives. shadcn/ui is built on top.
• React Aria (Adobe) — even more granular, hooks-based. Powers Adobe's apps.
• Headless UI (Tailwind Labs) — for Tailwind-flavored projects.

Don't roll your own modal/dropdown/tooltip/combobox. The accessibility requirements are vast and these libraries have spent years getting them right.

• axe DevTools — browser extension, runs WCAG checks, finds 30-50% of issues automatically.
• eslint-plugin-jsx-a11y — catches issues at write time.
• Playwright + axe-core — automated checks in CI.
• Lighthouse — accessibility score in Chrome DevTools.

Automated tools catch ~30% of issues. The rest requires manual testing — keyboard, screen reader, contrast, real users with disabilities.

Replaces Jest for new projects. Faster, better TypeScript support, native ESM, Vite-native.

// math.ts
export function add(a: number, b: number) { return a + b; }

// math.test.ts
import { describe, it, expect } from 'vitest';
import { add } from './math';

describe('add', () => {
  it('sums two numbers', () => {
    expect(add(2, 3)).toBe(5);
  });

  it('handles negatives', () => {
    expect(add(-1, 1)).toBe(0);
  });
});

The principle: test what the user sees and does, not internal state. Find elements by their visible text or accessibility role, not by class name or test ID.

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

it('shows error when submitting empty form', async () => {
  const user = userEvent.setup();
  render(<LoginForm />);

  await user.click(screen.getByRole('button', { name: /sign in/i }));

  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
});

it('submits when filled out correctly', async () => {
  const onSubmit = vi.fn();
  const user = userEvent.setup();
  render(<LoginForm onSubmit={onSubmit} />);

  await user.type(screen.getByLabelText(/email/i), 'a@b.com');
  await user.type(screen.getByLabelText(/password/i), 'password123');
  await user.click(screen.getByRole('button', { name: /sign in/i }));

  expect(onSubmit).toHaveBeenCalledWith({
    email: 'a@b.com',
    password: 'password123',
  });
});

Notice: no class names, no implementation details. Just "find the button labeled Sign In, click it." This makes tests resilient to refactoring — if you change the implementation but the user-visible behavior stays the same, the test still passes.

RTL has a recommended priority for finding elements:

1. getByRole — buttons, links, headings, etc. Mirrors how screen readers find things.
2. getByLabelText — form inputs by their label.
3. getByPlaceholderText — inputs by placeholder.
4. getByText — by visible text.
5. getByDisplayValue — current input value.
6. getByAltText — images by alt.
7. getByTitle — by title attribute.
8. getByTestId — last resort, when nothing else works.

If you can't find an element by role or label, that's often a sign the element isn't accessible. Tests double as accessibility checks.

// mock a module
vi.mock('./api', () => ({
  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'Test' }),
}));

// mock fetch globally
global.fetch = vi.fn().mockResolvedValue({
  ok: true,
  json: async () => ({ users: [...] }),
});

// MSW (Mock Service Worker) — better for component tests
import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

const server = setupServer(
  http.get('/api/users', () => {
    return HttpResponse.json([{ id: 1, name: 'Alex' }]);
  })
);
beforeAll(() => server.listen());
afterAll(() => server.close());

MSW is the modern way — intercepts at the network layer, so your components actually exercise their fetch code.

// e2e/login.spec.ts
import { test, expect } from '@playwright/test';

test('user can sign in', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('alex@example.com');
  await page.getByLabel('Password').fill('correctpassword');
  await page.getByRole('button', { name: 'Sign in' }).click();

  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByText(/welcome, alex/i)).toBeVisible();
});

Runs against real Chromium, Firefox, and WebKit. Catches issues that component tests miss: real network, real navigation, real focus management, real CSS rendering.

Take screenshots, compare them against approved baselines, flag differences for human review.

• Chromatic — built on Storybook, tests every component variant.
• Percy — cross-browser, integrates with E2E.
• Playwright has built-in screenshot comparison.

Catches CSS regressions that functional tests miss.

• Critical user flows (signup, checkout, primary feature).
• Components with non-trivial logic.
• Edge cases that broke before.
• Anything that's been a regression source.

• Trivial components (a div with text).
• Third-party library behavior.
• Implementation details (state shape, internal callbacks).
• Things that change every sprint and provide no signal.

1. Reads your entry file (e.g., app/page.tsx).
2. Follows imports to build a dependency graph.
3. Transpiles each file (TypeScript → JS, JSX → JS, modern syntax → compatible syntax).
4. Bundles related files together, splits at code-splitting boundaries.
5. Minifies (removes whitespace, shortens names, eliminates dead code).
6. Outputs files for the browser, with hashed names for cache-busting.

Uses native ES modules during development. No bundling needed for dev — the browser fetches modules directly. Production build uses Rollup.

Why it's fast: in dev, only the files you're actively editing get processed. No full-project rebuild on every save.

# scaffold a new Vite project
npm create vite@latest my-app -- --template react-ts

# config in vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: { port: 3000 },
  build: { outDir: 'dist' },
});

Most established projects still use Webpack. Slower than Vite for development but extremely flexible. Next.js 14 and earlier shipped with Webpack.

Rust-based bundler from the Next.js team. Replaces Webpack incrementally in newer Next.js versions. Significantly faster than Webpack, comparable to Vite.

Underneath the bundlers, the actual compilation is done by:

• esbuild — Go-based, extremely fast. Used by Vite for transpilation.
• SWC — Rust-based. Used by Next.js for transpilation. Has Babel-compatible plugins.

Both are 10-100x faster than Babel. You usually don't choose them directly; your framework picks one.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),  // import from '@/components/...'
    },
  },
  server: {
    port: 3000,
    proxy: {
      '/api': 'http://localhost:8000',  // proxy API to backend during dev
    },
  },
  build: {
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          // split big libraries into separate chunks
          react: ['react', 'react-dom'],
          ui: ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
  },
});

# .env (committed, defaults)
VITE_API_URL=http://localhost:8000

# .env.local (gitignored, secrets)
VITE_API_KEY=secret_key_here

# .env.production (production values)
VITE_API_URL=https://api.example.com

In Vite, only variables prefixed with VITE_ are exposed to client code. In Next.js, the prefix is NEXT_PUBLIC_. Variables without the prefix stay server-only — important for secrets.

// access in code
const apiUrl = import.meta.env.VITE_API_URL;  // Vite
const apiUrl = process.env.NEXT_PUBLIC_API_URL;  // Next.js

// tsconfig.json — modern web app baseline
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "jsx": "preserve",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

• ESLint for code quality (catching bugs, enforcing patterns).
• Prettier for formatting (no debate about indentation).
• Biome — newer, replaces both. Fast (Rust-based). Growing adoption.

// .eslintrc.json
{
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended",
    "plugin:jsx-a11y/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "warn"
  }
}

app/
  page.tsx                → /
  about/page.tsx          → /about
  blog/
    page.tsx              → /blog (list)
    [slug]/page.tsx       → /blog/:slug
  shop/
    [...all]/page.tsx     → /shop/* (catch-all)
    [[...slug]]/page.tsx  → /shop and /shop/* (optional catch-all)

The folder is the URL; the page.tsx is what renders.

// app/blog/[slug]/page.tsx
export default function BlogPost({ params }: { params: { slug: string } }) {
  return <article>Slug: {params.slug}</article>;
}

A layout.tsx wraps all pages in its folder and below. Persists across navigation (doesn't unmount when you navigate to a sibling).

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="dashboard">
      <Sidebar />
      <main>{children}</main>
    </div>
  );
}

The sidebar persists when navigating between dashboard sub-pages. Faster transitions, no flashing.

// app/dashboard/loading.tsx — shown while page loads
export default function Loading() {
  return <Skeleton />;
}

// app/dashboard/error.tsx — shown if page throws
'use client';
export default function Error({ error, reset }: ...) {
  return (
    <div>
      <p>Something went wrong: {error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

import Link from 'next/link';
import { useRouter } from 'next/navigation';

// declarative
<Link href="/blog/my-post">Read more</Link>
<Link href="/blog" prefetch={false}>Blog</Link>

// programmatic
'use client';
const router = useRouter();
router.push('/dashboard');
router.replace('/login');  // doesn't add to history
router.back();
router.refresh();  // refetch server components

Next.js prefetches links in the viewport — navigation feels instant because the next page is often already loaded.

// in a server component
export default function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string; page?: string };
}) {
  const query = searchParams.q ?? '';
  return <Results query={query} />;
}

// in a client component
'use client';
import { useSearchParams, usePathname } from 'next/navigation';

function Filters() {
  const params = useSearchParams();
  const pathname = usePathname();
  const status = params.get('status');
  // ...
}

// route groups — wrap with parens, don't appear in URL
app/
  (marketing)/        # group with shared layout
    layout.tsx
    pricing/page.tsx  → /pricing
    about/page.tsx    → /about
  (app)/              # different group, different layout
    layout.tsx        # checks auth
    dashboard/page.tsx → /dashboard

// parallel routes — render multiple pages in one layout
app/
  layout.tsx          # uses both children and modal
  @modal/
    (..)photos/[id]/page.tsx  # interceptor: shows photo as modal over the list page
  page.tsx
  photos/[id]/page.tsx  # full-page version

Parallel routes enable patterns like Instagram-style modals — same URL renders one way from a list, another way from a direct visit.

Modern routing isn't just "URL → component." It's:

• URL → layout(s) → page
• Page can fetch data on the server
• Loading/error/not-found states are co-located
• Navigation is prefetched and feels instant
• URL is the source of truth for shareable state

Default styles are mobile; add desktop styles via media queries that scale UP, not down.

/* mobile by default */
.card {
  padding: 16px;
  font-size: 14px;
}

/* tablet and up */
@media (min-width: 768px) {
  .card {
    padding: 24px;
    font-size: 16px;
  }
}

/* desktop */
@media (min-width: 1024px) {
  .card {
    padding: 32px;
  }
}

In Tailwind: p-4 md:p-6 lg:p-8 text-sm md:text-base. Same idea, utility classes.

Touch targets need to be at least 44×44 CSS pixels (Apple's HIG) or 48×48 (Material Design). Smaller and users miss-tap, especially with thumbs.

button {
  min-width: 44px;
  min-height: 44px;
  padding: 12px 16px;
}

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Without this, mobile browsers pretend to be 980px wide and shrink the page. viewport-fit=cover handles iPhone notch areas.

.fixed-header {
  padding-top: env(safe-area-inset-top);
}

.fixed-bottom-bar {
  padding-bottom: env(safe-area-inset-bottom);
}

The env() CSS function exposes platform-defined safe areas.

• 100vh is wrong on mobile — counts the address bar. Use 100dvh (dynamic viewport height) instead.
• iOS bounces past the page edges — by design. Use overscroll-behavior: contain on scrollable containers to prevent it.
• Hover states don't work on touch — use @media (hover: hover) to apply hover styles only on devices with real hover.
• Touch delays — modern browsers eliminated the 300ms tap delay, but touch-action: manipulation on buttons confirms it for older browsers.
• Pull-to-refresh interferes — overscroll-behavior-y: contain on the body if you have a custom refresh implementation.

A PWA is a website that can:

• Be installed to the home screen (acts like a native app).
• Work offline (via service workers).
• Send push notifications (with user permission).
• Access device features (camera, geolocation, etc., via web APIs).

JavaScript that runs separately from your page, intercepts network requests, can cache responses for offline use.

// register the service worker
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

// sw.js — minimal example
self.addEventListener('install', (e) => {
  e.waitUntil(
    caches.open('v1').then(cache => cache.addAll([
      '/',
      '/styles.css',
      '/app.js',
    ]))
  );
});

self.addEventListener('fetch', (e) => {
  e.respondWith(
    caches.match(e.request).then(cached => cached || fetch(e.request))
  );
});

For most apps, use Workbox (Google's library) or your framework's built-in PWA support rather than writing service workers by hand.

// public/manifest.json
{
  "name": "My App",
  "short_name": "MyApp",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "start_url": "/",
  "display": "standalone",
  "background_color": "#0e0f10",
  "theme_color": "#9C3D1F"
}

Linked from your HTML: <link rel="manifest" href="/manifest.json">. Lets users install the app to their home screen.

When you need true native: store distribution, native UI, deeper device access. React Native + Expo is the React-native (lowercase) path.

Capacitor (from the Ionic team) wraps your web app in a native container. Less code reuse than React Native but easier transition from a web codebase. Used by major brands when they want app store presence without rewriting in native or RN.