In the previous lesson it became clear what client-side routing is, why React doesn't ship with it, and which of the three ways of using React Router v7 this course uses: data mode, with createBrowserRouter and RouterProvider. Now it's time to write it. In this lesson you'll turn CicloUrbano from a single-screen application into a routed one: you'll install the package, create the route map in src/routes.jsx, mount the router provider in main.jsx without breaking the existing provider order, reorganise the project with a src/pages/ folder, replace the Header's <a href="#…"> links with real ones — finally settling module 2's debt — read the detail page's identifier with useParams, and move the TypeSelector filter from useState into the URL itself with useSearchParams. By the end, every CicloUrbano screen will have its own address.

1. Starting point and reorganisation plan
2. Installing the package
3. The src/pages/ folder and what stays in src/components/
4. The route map: src/routes.jsx
5. Mounting the router in main.jsx
6. Why the providers go outside the router
7. Links: <Link> vs. <a href>
8. <NavLink> and the active class: the Header's nav
9. Dynamic segments and useParams
10. What to do when the identifier doesn't exist
11. Query parameters with useSearchParams
12. The wildcard route and the not-found page
13. How React Router picks the best match

This is how App.jsx looks today, at the end of module 5: a single screen that shows the catalogue with its search box, its filter and its booking form, all wrapped in Layout.

The plan for this lesson, in order:

By the end, App.jsx disappears as a screen: its content moves into CataloguePage, and the router takes over the root's role. It's the biggest restructuring of the course so far, so it's worth doing it step by step and checking that the application still starts at each one.

That's it. No Vite plugins, no extra configuration: in data mode, React Router is a regular dependency.

About the package name, because it's the first point of confusion you'll run into:

Practical consequence: every example you find online with from 'react-router-dom' works the same way once you change the import to from 'react-router'. Pick one and be consistent; having both installed is a source of context errors that are very hard to diagnose, because you can end up with two copies of the router in memory.

Check the installed version:

Before writing the map you need to decide where everything lives. We're introducing a new folder:

The rule that separates the two folders:

That last point is more than an ordering convention: a page can depend on the router; a reusable component, the less the better. If BikeCard calls useParams() internally, it can no longer be used on a screen that doesn't have that parameter, and testing it in module 9 will force you to wrap it in a fake router. The page reads the parameter and passes it down via props: the component remains a function of its props, as in 02-03.

These are CicloUrbano's pages. We'll start with minimal versions and fill them in as we go:

You'll build out SignInPage in 06-05 (it needs signIn and the return to the original destination), so a skeleton is enough for now. And there's one more, the most important for this lesson:

Here's the heart of data mode: the map is an array of JavaScript objects, not JSX markup.

Let's unpack the decisions:

• The file is .jsx, not .js. It contains JSX in the element property, so the extension has to allow it or Vite will complain.
• path is the URL pattern, with a leading / on top-level routes. Segments starting with : are dynamic.
• element receives an already-created React element (<CataloguePage />), not the component (CataloguePage). It's a subtle but strict difference: passing the un-instantiated component is a classic mistake and produces a blank screen.
• router is exported by name, following the project's convention: export default for components, named exports for everything else.
• createBrowserRouter is called exactly once, outside any component. If you called it inside a component, every render would create a new router and you'd lose all navigation state.
• The * route goes last for readability, not out of necessity: order no longer decides anything (section 13).

There's no nesting yet. Layout isn't in the map yet, so screens are painted on their own, without a header or footer. It's a deliberate intermediate state: you'll fix it in 06-03, which is exactly the nested-routes lesson.

Remember how the entry point looked at the end of module 5:

The change consists of replacing <App /> with <RouterProvider router={router} />:

Points worth a comment:

• RouterProvider doesn't accept children. Everything painted below comes out of the route map. If you write <RouterProvider router={router}><Something /></RouterProvider>, that <Something /> will never show up.
• App.jsx is no longer imported. You can delete it or leave it empty; its role is now filled by routes.jsx (what gets painted) and Layout (how it's framed, from 06-03 on).
• StrictMode stays at the root, as it has since 01-03. It will keep causing the double mount in development, and that includes the pages' effects: nothing new compared with 05-02.
• BookingsProvider and NoticesProvider don't appear here. In 06-03 you'll place them inside Layout, the root route, alongside the rest of the application's frame. You could also lift them up into main.jsx; the decision is justified in the next lesson.

With this you can already run npm run dev, type http://localhost:5173/estaciones into the address bar, and see the station list. It's the first moment in the course where the URL means something.

The order StrictMode > ErrorBoundary > ThemeProvider > UserProvider > RouterProvider isn't arbitrary. Each layer wraps the next for a specific reason:

The key argument: whatever is above the router doesn't get unmounted when navigating. If UserProvider were inside a route, moving from / to /estaciones would unmount the provider, its useState would reset, and the user would lose their session on every menu click. The same goes for the theme: you'd flip from dark to light every time you changed screens.

As a table, the criterion for deciding where each provider goes:

And the global ErrorBoundary above everything has an extra reason: if the router itself throws an error — a misconfigured route, an element that isn't an element — someone has to catch it. In 06-03 you'll see there's also errorElement, which works inside the router, per route branch; the two mechanisms coexist and split the work.

Time to settle module 2's debt. Let's recall how Header has read ever since:

The temptation is to replace #catalogo with /:

And it's a mistake, even though it "works." Compare what happens with each one:

That detail in the last two rows matters, and it usually surprises people: <Link> renders a real <a> with its href. It isn't a <div> with an onClick, a common mistake when someone builds their own links from scratch. That's why it keeps everything good about an HTML link — opening in a new tab, copying the address, indexing, keyboard navigation, being announced correctly by a screen reader, as 03-06 required — and only changes the behaviour of a plain click, which it intercepts with preventDefault().

The rule is simple:

• Navigation inside the application → <Link to="…">.
• A link to another website, a PDF, or mailto: → a plain old <a href="…">. React Router shouldn't intercept it.

A tip that saves hours of debugging: if you ever notice that clicking a link loses the session or makes the whole screen flicker, it's almost certainly an internal <a href> you forgot to convert. It's the most repeated mistake when routing an existing application.

A navigation menu needs something more: visually marking which screen is current. <NavLink> is a <Link> that knows whether its destination matches the active URL.

Three things worth explaining:

className can be a function. NavLink calls it with an object { isActive, isPending, isTransitioning } and uses whatever it returns. It's the only prop in the whole project that behaves like this, and it's worth remembering why: the component doesn't know what class names your CSS Module uses, so it lets you decide. The same goes for style and for children:

The end prop isn't optional on the catalogue link. By default, a NavLink is considered active if the URL starts with its destination. Since every route starts with /, the "Catalogue" link would always show as marked, even while on /estaciones. end requires an exact match and solves the problem:

Notice the last row: for the "Stations" link we do want the default behaviour, because while viewing a station's detail page it makes sense for the section to stay marked. That's why end is only on the first one.

Accessibility. Marking the active link with colour alone isn't enough (03-06). NavLink automatically adds aria-current="page" to the active element, which a screen reader announces as "current page." Take advantage of that attribute in the CSS too, so you don't depend on a class:

The route /bicicletas/:bicicletaId has a dynamic segment: the colon signals that this piece is variable and its value has to be captured.

This is how it's read on the page:

And the link that leads here, from BikeCard:

Type conversion is your responsibility. This is the point that causes the most silent failures:

Every route parameter is a string. Always. The URL is text; React Router has no way of knowing whether 42 is a number, a postal code, or an identifier.

It doesn't cause trouble in CicloUrbano, because the identifiers are already strings (bici-003). But if your API used numeric identifiers, this would fail in a baffling way:

Convert it as early as possible, in a single place, and validate the result:

Anyone can type /bicicletas/bici-999 into the address bar, or arrive from an old link to a bike that's been decommissioned. You have three strategies, and choosing well matters:

Expand NotFoundPage so it serves both uses — a nonexistent URL and a nonexistent resource — with a tailored message:

An honest caveat worth knowing: this screen doesn't return an HTTP 404 status code. The server delivered index.html with a 200 status, and the 404 is purely visual. For a search engine to receive the correct code you need server-side rendering (10-01). In an internal application like CicloUrbano's panel that's not a problem; on a public website, it is.

Back to CataloguePage. The type filter currently lives in a useState, and that has the same flaw we called out in 06-01: if an operator filters by electrica and sends the address to a colleague, the colleague sees the catalogue unfiltered. The filter is information about what the user is looking at: it belongs in the URL.

useSearchParams is to query parameters what useState is to local state, with a deliberately similar signature:

With the difference that searchParams is a standard browser URLSearchParams object, not a plain object. Its methods:

Here's how the catalogue ends up:

The essentials of this code:

• TypeSelector hasn't been touched. It's still the controlled component from 03-04, with its chosenType and onTypeChange props. The only thing that changed is where the value comes from and where the change goes. That's exactly what we were after by keeping components decoupled from the router (section 3).
• It's copied before being modified: new URLSearchParams(searchParams). Mutating the object the hook returns doesn't repaint anything and can cause inconsistencies, for the same immutability reason as 05-01.
• ?tipo=todos gets removed instead of written. A default value shouldn't clutter the URL; / and /?tipo=todos would show the same thing yet be two different addresses, bad for sharing and for analytics.
• { replace: true } stops every click on the filter from adding a history entry. If a user tries five types, they won't want to press "back" five times to leave the catalogue. It's a design judgement call: for pagination, leaving a trail is usually preferred.
• The search term stays in useState. A deliberate decision: it's typed letter by letter, and moving it into the URL would generate dozens of entries or require combining it with the useDebounce from 05-06. Once the search box needs to be shareable, the pattern will be useSearchParams + useDebounce.

What's gained exactly by turning React state into URL state:

And the honest trade-off: the URL is public and shareable, so only things that are fine to be seen and saved should go there. Filters, sort orders, page numbers, the active tab: yes. Personal data, form contents, or any secret: never.

The last entry in the map is:

The asterisk is the wildcard route (splat route): it matches any URL that no other route has claimed. Its job is to turn a typo into a useful screen instead of a void. Without it, /estacionez would render absolutely nothing: a blank screen, with no error in the console. It's a baffling failure, and forgetting that line is very common.

The value captured by the wildcard is read with the key '*', useful if you want to show it or log it:

A wildcard is also useful at an intermediate point, not just at the root. { path: '/documentacion/*' } captures any depth under that prefix, a common pattern when integrating external content. CicloUrbano doesn't need it.

A natural question: if the URL is /reservas/nueva, why doesn't it match /reservas or *? The answer is one of React Router's best design decisions since v6:

React Router scores every route and picks the most specific one, no matter what order you wrote them in the array.

The scoring criteria, simplified:

Applied to /estaciones/est-02, with the full map:

Compare that with React Router v5 and earlier, where <Switch> took the first route that matched in the order it was written. That forced you to sort the array from most to least specific, to use exact everywhere, and it produced errors that were very hard to spot: a route placed two lines too high up would "eat" all the others. Today you can write the map in whatever order reads best to you.

Two nuances worth keeping in mind:

• The match has to be complete. /estaciones does not match the URL /estaciones/est-02 unless it has child routes that absorb the rest (06-03) or it ends in *.
• end on NavLink is a different thing. It only governs the link's active class, not which route gets painted. It's normal to mix them up at first.

Passing the component instead of the element. { path: '/', element: CataloguePage } instead of element: <CataloguePage />. It doesn't throw a clear error: it simply paints nothing. Remember element receives already-created JSX.

Leaving internal <a href> tags unconverted. The symptom is unmistakable: clicking a link makes the screen flicker, and the session, the theme and the bookings get lost. Search your project for href="/ and convert everything internal to <Link>.

Forgetting end on the home NavLink. The "Catalogue" link stays marked as active on every screen. The same happens with any NavLink whose destination is a prefix of other routes.

Calling createBrowserRouter inside a component. Every render would create a new router, and the application would jump back to the initial route as soon as anything repainted. The map is created once, at module scope.

Mutating the useSearchParams object. searchParams.set('tipo', 'carga') on the object the hook returns doesn't trigger any repaint. Always copy: new URLSearchParams(searchParams).

Adding an extra ? when building the URL. setSearchParams('?tipo=carga') produces ??tipo=carga. Pass a URLSearchParams or a plain object and let React Router add the separator.

Expecting a number from useParams. Everything is a string. Convert and validate, in a single place, as early as possible.

Forgetting the * route. Any typo produces a silent blank screen, with no console error. It's one of the first bugs a user reports.

Tip: name the parameters the same way in the route and in the code. path: '/bicicletas/:bicicletaId' and const { bicicletaId } = useParams(). If the route says :id and you destructure bicicletaId, you'll get undefined with no warning at all.

Tip: keep a single source of truth per piece of data. If the chosen type lives in the URL, don't duplicate it in a useState "to have it handy." Duplicating it guarantees the two will fall out of sync sooner or later, exactly as 05-01 warned about derived state.

Tip: test a reload on every new route. Navigating with links always works; reloading is what uncovers server configuration problems. With Vite in development you won't see the failure, but it's worth keeping in mind what 06-01 covered about rewriting to index.html.

Add the station detail screen to CicloUrbano, /estaciones/:estacionId. It should:

1. Read the parameter and look up the station in stations.
2. Show its name, district and docks.
3. List the bikes whose stationId matches, each linking to its detail page.
4. Show the "not found" screen if the identifier doesn't exist.
5. Include a link back to /estaciones.

Also add the link from StationCard to get there.

In StationsPage, add a dropdown that lets you sort stations by name or by docks, saving the choice in a sort query parameter. Requirements:

• The URL should end up as /estaciones?sort=docks.
• The default value (name) shouldn't appear in the URL.
• Any other query parameters that might exist shouldn't be lost.
• An invalid value typed by hand (?sort=made-up) shouldn't break the screen.

This route map and this header have five bugs. Find them and fix them.

Solution 1

With the route already present in routes.jsx, there's nothing else to register. And notice that /estaciones and /estaciones/est-02 coexist without a problem thanks to the scoring from section 13: the order in the array is irrelevant.

Solution 2

The four requirements are covered by: the VALID_SORTS allowlist (validation), the delete when the value is the default one (clean URL), the new URLSearchParams(searchParams) copy (not losing other parameters), and the [...stations] before sort (not mutating the original data). The <select> is a controlled component from 03-04, with the particularity that its value comes from the URL rather than a useState.

Solution 3

The five bugs:

1. element: CataloguePage passes the component, not the element. It should be element: <CataloguePage />. Symptom: a blank screen with no clear error.
2. createBrowserRouter inside a function exported as createRouter. If main.jsx calls it on every render, a new router gets created each time. It must be created once, at module scope, and exported by name: export const router = createBrowserRouter([...]);.
3. The wildcard route { path: '*', element: <NotFoundPage /> } is missing. Any unknown URL leaves the screen silently blank.
4. Name mismatch: the route declares :id, but the page destructures bicicletaId, which will be undefined. They have to match; the correct choice, per the module's map, is :bicicletaId in both places.
5. In Header, <a href="/estaciones"> causes a full reload and loses all React state. It should be <NavLink to="/estaciones">.

And a sixth bug, latent, worth pointing out: in BikeDetailPage there's no check for whether bike exists, so /bicicletas/bici-999 will blow up with "Cannot read properties of undefined (reading 'model')." Add the guard from section 10. Also note that this error would indeed be caught by the global ErrorBoundary from 04-05, but it would bring down the entire application for something that's simply a mistyped URL: handling it in place is a much better experience.

CicloUrbano is now routed. You've installed react-router — the v7 package, knowing that react-router-dom is what you'll see in v6 projects — you've created src/routes.jsx with the full map as an array of objects, and you've mounted <RouterProvider router={router} /> in main.jsx, keeping the order StrictMode > ErrorBoundary > ThemeProvider > UserProvider, because whatever is above the router doesn't get unmounted when navigating, which is why the session and the theme survive screen changes. The project has a src/pages/ folder with one screen per route and a clear rule: pages can depend on the router; reusable components receive their data via props and remain independently testable.

Along the way you settled the debt Header had been carrying since module 2: the three <a href="#…"> tags are now <NavLink> elements with an active class, aria-current="page" for free, and the end prop on the catalogue link so it doesn't show as marked on every screen. You know that <Link> produces a real <a> — with everything good about an HTML link — and only intercepts the plain click, whereas an internal <a href> destroys the application and takes the session, theme and bookings down with it. You've read the detail page's identifier with useParams, remembering that every route parameter is a string and that converting and validating it is your job, and you've decided what to do when the resource doesn't exist. And you've turned the TypeSelector filter from React state into URL state with useSearchParams, gaining shareable links, reloads that keep the filter, and useful analytics, without touching a single line of the controlled component. Rounding out the picture are the wildcard route * — whose absence produces silent blank screens — and the scoring system that picks the most specific match without depending on the array's order.

One visible problem remains: screens are painted on their own, with no header or footer, because Layout was left out of the map. Reintroducing it as a component that wraps each page would work, but it would remount the header on every navigation and wouldn't let frame and screen share data. The correct fix is to make Layout the parent route of everything else and open a slot in it where the active child gets painted; you'll use the same idea to build the flota and incidencias tabs inside the station detail page, the breadcrumbs, and per-branch error handling. The next lesson is Nested Routes.