The previous two lessons went after the work React does while the user is using the app: renders that shouldn't happen, calculations redone over and over, identities that change for no reason. What's left is the other problem, the one that shows up before the user can use anything at all. Today, when someone opens CicloUrbano to check whether there's a bike free at Main Square, the browser downloads and runs the code for the workshop panel, the station detail view with its tabs, the booking form, and the occupancy chart library, before it paints the first card. All of that code is correct, well memoized, and isn't going to be used on that visit. No memoization technique fixes this, because the problem isn't how many times something runs: it's how much what gets downloaded weighs. The solution is called code splitting: breaking the bundle into chunks that download when they're needed, and in React it's expressed with two pieces — React.lazy and <Suspense> — built on top of a mechanism from JavaScript itself: the dynamic import(). In this lesson you'll learn to measure the bundle, to split it by route and by component, to prefetch so the wait goes unnoticed, to design the wait without visual jumps, and to survive when a chunk doesn't arrive.

1. The problem with a single bundle
2. Measuring before splitting: inspecting the bundle
3. What code splitting is, and what chunks are
4. Dynamic import() as an automatic boundary
5. React.lazy and <Suspense fallback>
6. Route-based splitting: the biggest payoff
7. Why the catalogue isn't split
8. Component-based splitting
9. Prefetching: making the wait invisible
10. Designing the wait: skeletons instead of "Loading…"
11. When the chunk doesn't arrive
12. Other size levers
13. Suspense is much more than this

When you run npm run build, Vite walks the import graph starting at main.jsx, resolves every static import, and bundles it all together. One file, or a handful. The browser has to download it whole, parse it whole, and execute it whole before React paints anything.

These are CicloUrbano's real dependencies after Module 7, with rough sizes for the app's own minified, gzip-compressed code:

And now the uncomfortable part: of those 270 KB compressed, the entry route uses roughly half. The charts only show up on the station detail page, WorkshopPage is only seen by an operator, and NewBookingPage only opens when booking.

The cost isn't just the download. Parsing and executing JavaScript is CPU work, and on a mid-range phone it runs 3 to 5 times slower than on your laptop:

Three and a half seconds until a single bike shows up, half of it spent on code that visit isn't going to use. That's the exact problem this lesson solves.

Same as the rest of the module: measure first. Vite already gives you the first measurement without installing anything.

That Rollup warning isn't decorative: it's exactly this lesson's advice. But Vite's output says how much it weighs, not what weighs it. For that you need a map of the contents.

After npm run build, open dist/stats.html: a treemap where every rectangle is a module and its area is its weight. What to look for, in order:

Write down the starting figure — 271 KB compressed — because section 6 compares it against the one after. Without that before-and-after, this isn't optimization.

Code splitting means breaking the single bundle into several files, called chunks, so the browser only downloads the ones it needs for whatever the user is doing.

Splitting happens at two levels, and it's worth telling them apart:

• Automatic splitting by shared dependencies. Vite already separates node_modules into a vendor chunk, so library code, which changes rarely, caches better across deploys. This happens on its own, and it doesn't affect how much gets downloaded on the first visit.
• Splitting by load points, the one this lesson covers: you decide which parts of your application can wait, and mark them as such.

What's interesting is how you mark them: there's no configuration involved. The boundary between chunks is created by a syntax feature of JavaScript itself.

The essential differences:

And the effect on the module graph:

The dashed lines are network requests that happen when the user gets there, not before. And there's nothing to configure: writing import(...) is the whole instruction.

import() returns a promise, and JSX doesn't know what to do with a promise. React.lazy is the bridge.

lazy's signature and requirements:

• It takes a function that returns a promise for a module. Not the promise itself: the function lets React call it at the right moment.
• The module must expose the component as a default export. That's what React reads from the resolved promise. CicloUrbano's convention (export default for components) fits without any changes.
• lazy() must be called outside of any component, at module scope. Called from inside one, every render would create a new lazy component and unmount the previous one, and the screen would flicker forever.

If a module used a named export instead, the fix is one line:

Behavior the first time versus every time after:

<Suspense> has one relevant prop here, fallback, and one placement rule: it must sit above the lazy component in the tree, and its position decides which part of the interface gets replaced by the loading indicator. A Suspense at the root replaces the whole app; one around <Outlet /> replaces only the page content and leaves Header and Footer untouched. That difference is very noticeable.

Route-based splitting has the best effort-to-payoff ratio, and the reason is obvious once you say it out loud: the user is on one route at a time. Everything belonging to other routes is, by definition, code that isn't needed right now.

Here's CicloUrbano's route map with splitting applied:

The six marked points:

1. CataloguePage stays static. It's the index route: making it lazy would add an extra network request right on the critical path. Explained in section 7.
2. SignInPage too. It's small, it's the destination of every ProtectedRoute redirect, and making it lazy would introduce a flicker at a sensitive moment.
3. RouteErrorPage must never be lazy. If the failure it has to display is precisely a network failure, loading the error's own chunk would fail too. Error components always ship in the main bundle.
4. One import() per page equals one chunk per page. No extra configuration.
5. The Lazy wrapper avoids repeating <Suspense fallback={...}> in nine places and guarantees the same loading experience everywhere. Placing Suspense inside each route, rather than around the <Outlet /> in Layout, means only the page content is replaced: the header, breadcrumbs, and footer don't flicker.
6. The existing errorElement catches errors thrown while rendering child routes, including import() rejections. Covered in detail in section 11.

And the result, which is the whole point of the lesson:

It's tempting to slap lazy on everything. That would be a mistake, and understanding why is what separates someone who optimizes from someone who copies recipes.

The entry route is the one the user sees first. Making it lazy stretches the sequence out instead of shortening it:

You add a round trip to the network in series, right on the critical path, and on top of that you make LCP worse by showing a skeleton first. The code saved is zero, because that code is needed anyway.

The general rule for deciding:

And a rule of thumb on size: under roughly 20 KB uncompressed, a chunk of its own rarely pays off. An HTTP request has its own latency cost, and ten tiny chunks are worse than one medium one.

Not everything splittable is a route. Within a single screen there are parts that only exist if the user does something.

Case 1: BookingDialog. It lives on the bike detail page but only mounts when you click "Book". It drags in BookingForm, its validation, and useBlockExit.

The detail that makes this work: lazy doesn't download anything until the component actually renders. With the conditional render {dialogOpen && ...}, the request fires the moment it opens, not when the page mounts.

Case 2: the occupancy chart library. It's the 95 KB compressed chunk, and it's only used in a station's fleet tab, inside a weekly-occupancy collapsible section.

The key technique is called module isolation: you create a wrapper component (OccupancyChart) that's the only place in the project importing the heavy library, and you load that wrapper lazily. That way the bundler can put the whole library into a separate chunk. If another module imported it statically, it would fall back into the main bundle and all that effort would be wasted.

Practical check: after npm run build, look in dist/assets/ for a chunk with the library's weight. If it isn't there and the main bundle is still heavy, someone is importing it statically somewhere else.

Code splitting trades "waiting up front" for "waiting when you navigate." Prefetching removes that second wait by using the time the user spends deciding: the hundreds of milliseconds between the mouse reaching a link and the finger clicking it.

Why this works so well: the browser caches the module, so when lazy requests the same import() on navigation, the promise resolves immediately and Suspense never even shows the fallback. The user perceives an instant navigation even though the code was downloaded half a second earlier.

Prefetch strategies, compared:

An example of the third one, for the route almost everyone visits after the catalogue:

A badly designed fallback makes performance feel worse even when the milliseconds are identical. Two reasons, and both are measurable:

• Layout shift (CLS). A <p>Loading…</p> takes up 20 pixels of height; the page that arrives takes up 900. When it's swapped in, everything jumps. If the user was already tapping something, they tap the wrong place.
• Breaking context. Centered text on an empty screen says "you've left where you were." A skeleton shaped like what's coming says "this is already on its way."

The design decisions and their reasons:

And two warnings that avoid the opposite of the intended effect:

• A fallback that appears and disappears within 80 ms is worse than none at all: it reads as a flicker. If the chunk is small and there's prefetching in place, consider delaying the skeleton's appearance (only showing it if the wait exceeds ~200 ms) or just trusting the prefetch.
• Don't put a Suspense at the root for routes. It would replace the header and footer, and every navigation would look like a full page reload.

This is the section that separates a toy code-splitting setup from a production one. An import() can fail, and it fails more often than it seems:

The second case deserves an explanation because it catches everyone off guard: Vite puts a content hash in every chunk's file name (WorkshopPage-Bq7Wm3.js). If you deploy a new version while someone has the app open, that tab keeps running the old routes.jsx, which requests a chunk with a hash that's no longer on the server. The app works perfectly… until the user navigates to a route they hadn't visited yet.

The solution combines Suspense (for the wait) with ErrorBoundary (for the failure), which is exactly the piece built in 04-05:

The nesting order is not negotiable:

If you flipped it — Suspense outside and ErrorBoundary inside — the boundary would get torn down when the tree suspends, and there'd be no one left to catch the failure.

In routes.jsx, all it takes is swapping the Lazy wrapper for LoadBoundary:

With this, the root route's errorElement: <RouteErrorPage /> remains the last safety net, and LoadBoundary offers a specific, actionable message — reload — right where the failure happens, without tearing down the whole navigation. Remember why both exist: errorElement catches errors from routes and their loaders; ErrorBoundary catches errors from rendering components. An import() failure happens during render, so it's the second one's job.

Why "reload" is the right action. In the most common case — a new deploy — retrying the same import() would request the old chunk again and fail again. Reloading the page brings in the new index.html, with the correct references, and the problem goes away. That's why the primary button reloads and the secondary one retries.

Code splitting is the big lever, but not the only one. These complement it, and some are cheaper to apply:

An example of loading on demand inside a handler, a very useful and often overlooked pattern:

No lazy or Suspense needed here: you're not loading a component, you're loading a function. A plain import() inside an async function is exactly the right tool, and the try/catch covers network failures.

And a warning about compression that's often misunderstood: gzip and Brotli reduce the transfer, not the CPU work. A 900 KB bundle that transfers as 270 KB still has to be parsed and executed as 900 KB. On mobile, that usually weighs more than the download.

<Suspense> has shown up here as "what gets displayed while a chunk arrives," and that's only its simplest application. Its real role in React is more general: it's the mechanism by which a component declares it can't render yet and delegates the wait to an ancestor.

Built on top of that idea are things that don't fit in this module:

• Components that suspend waiting for data, not code: TanStack Query's useSuspenseQuery, or React 19's use() hook.
• Streaming SSR: the server sends the HTML in pieces and fills in Suspense's gaps as the data arrives.
• React Server Components, where Suspense marks the boundaries between what renders on the server and what arrives afterward.
• Coordination with useTransition (08-03) so a navigation doesn't show a fallback if the new screen arrives fast enough.

All of that is the content of 10-03. For now, it's enough to have internalized the mechanism: a component suspends, the nearest Suspense above it shows its fallback, and when the wait ends the tree completes.

Calling lazy() inside a component. Every render would create a different component type, React would unmount the previous one and mount a new one, and the screen would flicker forever. lazy() always goes at module scope.

Forgetting the Suspense. A lazy component with no Suspense above it throws an explicit runtime error. It's not optional.

Putting a single Suspense at the root. Every navigation would replace the whole app, header included, and it would look like a reload. Place suspense boundaries where you actually want the swap to happen.

Making the entry route lazy. It adds a serial request on the critical path and makes LCP worse without saving a single byte.

Making error components lazy. If the network is what's failing, the error's chunk won't arrive either. RouteErrorPage and ErrorBoundary always go in the main bundle.

Splitting too much. Twenty 3 KB chunks are worse than two 30 KB ones: every request carries its own latency. Split along meaningful units — a route, a dialog, a heavy library — not file by file.

Assuming the module has a default export. If it's a named export, lazy will fail with a confusing error. Adapt it with .then((m) => ({ default: m.WhateverItIs })).

Tip: always measure before and after. npm run build before touching anything, write down the compressed figure, split, build again, and compare. Without that pair of numbers you don't know if you've improved anything.

Tip: test with a throttled network. In the browser's dev tools, set the network to "Slow 3G" and navigate around. That's where you really see whether the skeletons work, whether the prefetch arrives in time, and whether chunk failures are handled properly.

Tip: test the deploy scenario. Open the app, build again with a change (the hashes will change), and, in the old tab, navigate to a route you hadn't visited. Your "new version available" message should appear, not a blank screen.

Tip: check the bundle map every once in a while. A heavy dependency sneaks into the main bundle with a single careless static import, and nothing warns you about it.

Exercise 1. Classify each CicloUrbano element as static, lazy by route, or lazy by component, and justify each decision in one sentence.

Exercise 2. This code has four errors related to lazy loading. Find them, explain what each one causes, and write the fixed version.

Exercise 3. The CicloUrbano team deploys three times a day. Users who leave the tab open for hours report blank screens when navigating to the workshop in the afternoon. Explain the exact cause, describe the complete solution — including the components' nesting order — and say why the primary button must reload the page instead of retrying the import.

Solution 1.

Solution 2. The four errors:

1. lazy() inside the component. Every render creates a new lazy component, React unmounts the previous one and mounts another: infinite flicker and repeated downloads. It must go at module scope.
2. Missing Suspense. DetailPanel is lazy and has no suspense boundary above it: React will throw an error trying to render it.
3. RouteErrorPage is lazy. It's the component meant to show when something fails, including a network failure; if its own chunk doesn't arrive, there's nothing to show. It always goes in the main bundle.
4. Missing the useState import. A trivial error, but a real one: the file only imports lazy and Suspense.

Fixed version:

Solution 3. Exact cause: Vite puts a content hash in every chunk's file name (WorkshopPage-Bq7Wm3.js). The tab open since morning keeps running that version's routes.jsx, which points to the old hashes. When the afternoon deploy happens, the server serves chunks with new hashes and deletes — or stops referencing — the old ones. When the user navigates to the workshop, a route they hadn't visited yet, import() requests a file that returns 404, the promise rejects, nobody catches the error, and the screen stays blank (or stuck on the skeleton forever, if the fallback is still mounted).

Complete solution: wrap every lazy route in a LoadBoundary with this nesting order, the only one that works:

If it were flipped, the error boundary would get torn down when the tree suspends, leaving nobody to catch the failure. The boundary's fallback must tell dynamic-import errors (Failed to fetch dynamically imported module) apart from the rest, give an understandable message — "a new version might be available" — and offer an action.

Why reload and not retry: retrying runs the same import(), which points to the same nonexistent hash, so it would fail the exact same way no matter how many times it's clicked. Reloading the page requests index.html again, which brings in the references to the new chunks, and from that point everything works. Retrying without reloading only makes sense in the other scenario — a momentary network hiccup with the same deploy still live — which is why it's offered as the secondary action.

As a further improvement, the team could publish a version file and poll it periodically to warn the user ("a new version is available, reload whenever you like") before they run into the error, and keep old chunks on the server for a few days instead of deleting them on every deploy.

Memoizing reduces the work React does while the user is interacting; code splitting reduces what the browser has to download and execute before the user can interact at all. They're different problems, and neither technique replaces the other: CicloUrbano's single bundle weighed 271 KB compressed — 910 KB of JavaScript to parse and execute — with half of it dedicated to screens most visits never open.

The method has been the same one running through the whole module: measure first. npm run build gives you the figure and Rollup's warning about the 500 KB; rollup-plugin-visualizer tells you what takes up that space, which is what the figure alone doesn't say. On top of that measurement, the mechanism: dynamic import() is the automatic boundary between chunks — a JavaScript syntax feature, no configuration involved — and React.lazy is the bridge between that promise and JSX, with two clear requirements (a default export, and being called at module scope) and a behavior worth keeping in mind: the first time it suspends and shows the fallback, every time after that it's instant.

Route-based splitting is the biggest payoff, and in CicloUrbano it's brought the initial JavaScript down to 128 KB compressed, a 53% cut, finally meeting 08-01's budget. Just as important is what hasn't been split: the entry route, because making it lazy adds a serial request on the critical path without saving a byte; the frame components; and above all the error components, because an error chunk that doesn't arrive because of the network is worthless. On top of that comes component-based splitting — BookingDialog, which only loads once it opens, and OccupancyChart, isolated as the sole importer of a 95 KB library — and loading libraries inside a handler with a plain import(), no lazy or Suspense needed.

After that comes everything that turns correct splitting into a good experience: prefetching on hover, on keyboard focus, and on mobile touch, which uses the user's decision-making milliseconds so the fallback never gets seen; skeletons with the height and shape of the real content, with role="status", hidden accessible text, and respect for prefers-reduced-motion, instead of a "Loading…" that causes layout shift and breaks context; and handling load failures, with ErrorBoundary outside and Suspense inside — the reverse order catches nothing — a message that tells chunk failures apart from everything else, and a button that reloads, because after a new deploy, retrying the same import() would forever request a hash that no longer exists. And the complementary levers: importing selectively, choosing lighter libraries, import() for data, Brotli on the server, and a modern browser target, with the reminder that compression reduces the transfer but not the CPU work.

It's also worth noting that Suspense is much more than a lazy-loading fallback — it's the general mechanism by which a component declares it can't render yet — and that its full story, along with Server Components, is 10-03.

With this, CicloUrbano has every tool the module set out to deliver: it knows which renders to avoid, how to stabilize identities, how to make computations cheaper, and how to spread its code out over time. What it still doesn't have is proof that any of it actually helps. Every figure in this lesson — 271 KB, 128 KB, 53% — comes from a measurement, and every memo and every useMemo from the previous lessons should come from one too. What's missing is the tool that produces them, the one that says which component repainted, how long it took, and why, turning a suspicion into a diagnosis. The next lesson is Measuring Performance with React DevTools Profiler.