El módulo 5 terminó con un diagnóstico incómodo: CicloUrbano funciona, pero es una sola pantalla. La Cabecera que escribiste en el módulo 2 lleva desde entonces un menú «Catálogo · Estaciones · Mis reservas» con tres enlaces que no llevan a ninguna parte —son <a href="#catalogo"> decorativos—, y esa deuda no se podía saldar porque faltaba la pieza que relaciona la URL del navegador con qué componente se pinta. Esa pieza no viene en React: hay que añadirla. En esta lección entenderás qué es el enrutamiento en el cliente, cómo funciona por dentro una aplicación de una sola página, qué gana CicloUrbano cuando cada pantalla tiene su propia dirección, y cuál de las tres formas de usar React Router v7 vas a emplear en el resto del curso. No escribirás todavía la configuración —eso es la próxima lección—; aquí construyes el modelo mental y el vocabulario que necesitarás para no perderte en él.

1. Qué problema resuelve un enrutador
2. Por qué React no trae enrutamiento
3. Cómo funciona una aplicación de una sola página
4. La API de historial del navegador: pushState y popstate
5. Qué gana la aplicación con URLs reales
6. Qué es React Router y su lugar en el ecosistema
7. Las tres formas de usar React Router v7
8. Vocabulario del módulo
9. Historial de navegador frente a historial de hash
10. El mapa de rutas de CicloUrbano

Empecemos por el estado actual del proyecto. Si quisieras hoy mostrar tres secciones distintas en CicloUrbano sin enrutador, harías algo así:

Funciona. Y sin embargo es una mala solución, por razones que no tienen que ver con el estilo del código:

• La URL nunca cambia. Un usuario que está viendo la ficha de bici-002 sigue teniendo https://ciclourbano.test/ en la barra de direcciones. No puede enviar ese enlace a nadie.
• El botón «atrás» sale de la aplicación. El navegador no tiene ni idea de que el usuario ha «navegado» tres veces; para él no ha pasado nada desde que cargó la página. Pulsar atrás lo devuelve a Google.
• Recargar (F5) devuelve al principio. El useState se reinicia y vuelve al catálogo, dando igual dónde estuviera.
• No hay marcadores. Guardar una pantalla en favoritos guarda siempre la portada.
• No hay historial interno. No puedes ir «atrás» dentro de la propia aplicación.
• Y escala fatal. Con nueve pantallas y parámetros (¿qué bicicleta? ¿qué estación? ¿qué pestaña?), ese useState se convierte en un objeto con cinco campos y una cadena de condicionales imposible de leer.

Un enrutador es la pieza que mantiene sincronizadas dos cosas: la URL que ve el usuario y el árbol de componentes que React pinta. En un sentido, al cambiar la URL cambia lo que se ve; en el otro, al navegar dentro de la aplicación cambia la URL.

Esa doble dirección es la clave. Un enrutador no es «un switch más elegante»: es la decisión de convertir la URL en estado de la aplicación, un estado que vive fuera de React, que el navegador ya sabe gestionar y que el usuario puede editar, copiar y compartir.

Es una pregunta legítima: Angular trae su enrutador de serie, Vue tiene uno oficial. ¿Por qué React no?

La respuesta está en lo que React dice de sí mismo desde la lección 01-01: es una biblioteca para construir interfaces de usuario, no un marco de trabajo de aplicaciones. Su ámbito termina en «dado un estado, produce un árbol de elementos y sincronízalo con el DOM». Todo lo demás —enrutamiento, peticiones HTTP, gestión de estado global, internacionalización— queda deliberadamente fuera.

Esa decisión tiene consecuencias prácticas:

La contrapartida es real: hay que elegir, y la elección se equivoca a menudo porque el código antiguo que encuentras por internet usa APIs de hace tres versiones. Por eso el apartado 7 de esta lección es tan importante.

Compara los dos modelos de navegación. En una web tradicional (multipágina), cada clic en un enlace es una petición completa al servidor:

En una aplicación de una sola página (SPA, single-page application) el servidor entrega un único index.html la primera vez, y a partir de ahí JavaScript se encarga de todo:

Las diferencias que importan:

Fíjate en el detalle que hace posible todo el truco: preventDefault(). Un <a href="/estaciones"> normal provoca que el navegador tire la aplicación entera y pida la página al servidor. Un <Link to="/estaciones"> de React Router renderiza un <a> de verdad —con su href, para que se pueda abrir en pestaña nueva y para que los buscadores lo sigan— pero intercepta el clic y lo convierte en un cambio de estado interno. Esta distinción volverá en 06-02 y es la causa del error más común del módulo.

React Router no inventa nada mágico: se apoya en una API estándar del navegador que existe desde HTML5. Merece la pena verla en crudo una vez, porque entenderla despeja casi todas las dudas posteriores.

Tres observaciones que conviene grabar:

• pushState cambia la URL pero no pinta nada. El navegador no dispara ninguna recarga ni ningún evento. Quien decide qué mostrar es tu código. Ese «tu código» es exactamente lo que React Router te ahorra escribir.
• popstate solo se dispara con atrás/adelante, no con pushState. Por eso un enrutador escrito a mano necesita interceptar los clics además de escuchar popstate.
• El estado que pasas a pushState se serializa y sobrevive a recargas dentro de la misma sesión. React Router lo aprovecha para la opción state de la navegación, que verás en 06-04.

Si tuvieras que escribir tu propio enrutador, necesitarías: interceptar clics, llamar a pushState, escuchar popstate, comparar la ruta con un conjunto de patrones, extraer los parámetros de los segmentos dinámicos, ordenar las coincidencias por especificidad, gestionar rutas anidadas, restaurar el desplazamiento… Es exactamente el trabajo que React Router lleva hecho desde 2014, y la razón de no hacerlo a mano.

Vale la pena enumerar las ganancias concretas, porque justifican la complejidad añadida:

• Enlaces compartibles. Un operario puede pasarle a otro https://ciclourbano.test/bicicletas/bici-003 y ambos ven la misma ficha. Sin URLs, la única instrucción posible es «entra y busca la Carga Max».
• Atrás y adelante funcionan. El botón atrás es, con diferencia, el control más usado de cualquier navegador. Que se salga de la aplicación es un fallo grave de experiencia de usuario.
• Recargar mantiene el sitio. F5 en /estaciones/est-02 vuelve a /estaciones/est-02. Sin URLs, vuelve a la portada.
• Marcadores. El usuario puede guardar «Mis reservas» en favoritos.
• Indexación por buscadores. Cada pantalla es un documento distinto con su dirección, y eso es condición necesaria (aunque no suficiente: hace falta que el contenido esté en el HTML, y ahí entra el SSR de 10-01) para que un buscador la muestre.
• Analítica útil. Las herramientas de medición cuentan páginas vistas por URL. Con una sola URL, todos tus datos dicen «portada».
• Estado depurable. Cuando un compañero te dice «me falla», la URL es la mitad del informe de error.
• División de código por pantalla. Si /taller es una ruta propia, su JavaScript puede descargarse solo cuando alguien entra ahí. Esto es la carga perezosa que verás en 08-04, y sin rutas no hay dónde cortar.

React Router es la biblioteca de enrutamiento para React más veterana y más usada. Traduce la URL actual a un árbol de componentes según un mapa de rutas que tú declaras, y ofrece los componentes y hooks para navegar, leer parámetros y componer pantallas anidadas.

Su historia explica gran parte de la confusión que encontrarás:

Y no está solo. Conviene saber qué hay alrededor, aunque en este curso uses React Router:

• TanStack Router. Alternativa moderna cuyo argumento fuerte es la seguridad de tipos: rutas, parámetros y parámetros de consulta tipados de extremo a extremo con TypeScript (10-04), con validación de los parámetros incluida. Si trabajas en un proyecto TypeScript grande y estricto, merece una mirada.
• Enrutadores integrados en los marcos de trabajo. Next.js (10-01 y 10-02) trae su enrutador basado en el sistema de ficheros: la ruta /estaciones/est-02 sale de la existencia de un fichero app/estaciones/[estacionId]/page.jsx, sin que declares un mapa. Lo mismo hace Remix (hoy fundido con React Router v7) y Astro. Cuando adoptas uno de esos marcos, no instalas React Router: usas el suyo.
• Enrutadores minimalistas como wouter, de unos pocos kilobytes, para aplicaciones pequeñas donde React Router resulta excesivo.

La conclusión práctica: React Router es la opción por defecto sensata para una SPA construida con Vite, que es exactamente el caso de CicloUrbano, y los conceptos que aprendas aquí (segmentos dinámicos, anidamiento, outlet, rutas índice) son los mismos en todos los enrutadores del ecosistema, con otros nombres.

Aquí está la principal fuente de desconcierto para quien empieza hoy. React Router v7 se puede usar de tres maneras distintas, y la documentación las llama modos:

En este curso usamos el modo de datos: createBrowserRouter + RouterProvider. Las razones:

• Es el que recomienda la documentación oficial para una SPA nueva, y el camino de migración natural hacia el modo de framework si algún día hace falta.
• Desbloquea APIs que necesitamos. errorElement para manejar errores por rama de ruta (06-03), useBlocker para impedir salir de un formulario a medias y ScrollRestoration (06-04) solo existen en el modo de datos. Con el modo declarativo te quedarías sin ellas.
• El mapa de rutas es un dato, no marcado. Un array de objetos se puede recorrer, transformar y usar para generar el menú o las migas de pan automáticamente. En 06-03 lo aprovechas con handle y useMatches.
• Separa la configuración de la interfaz. El mapa vive en src/rutas.jsx y no se mezcla con la pantalla.

Muy importante para leer código ajeno: la forma antigua sigue siendo válida y es la que verás en la inmensa mayoría del código existente, tutoriales y respuestas de foros:

Y este es el equivalente en el modo que sí usarás, para que veas desde ya el parecido:

Los conceptos se trasladan uno a uno. path, element, el anidamiento, <Link>, useParams, useNavigate, <Outlet />: son idénticos en ambos modos. Lo único que cambia es dónde declaras el mapa y cómo se monta en la raíz. Si mañana caes en un proyecto v6, sabrás leerlo sin esfuerzo. La regla es la que ya aplicaste con CSS Modules en 02-05: elige una forma y sé coherente en todo el proyecto; mezclar <BrowserRouter> con <RouterProvider> en la misma aplicación es un error garantizado.

Una nota más sobre nombres de paquete, porque desconcierta a todo el mundo: en v6 se instalaba react-router-dom; en v7 el paquete es react-router y de él sale todo. react-router-dom sigue publicándose como reexportación por compatibilidad, así que verás ambos importes en la red. Lo detallamos en 06-02, donde instalarás.

Fija estos términos ahora; el resto del módulo los usa sin volver a definirlos.

Un detalle de criterio que se olvida a menudo, y que gobierna una decisión de diseño en 06-02: un segmento dinámico identifica un recurso; un parámetro de consulta modifica una vista. La ficha de una bicicleta concreta es /bicicletas/bici-003 (identidad); un catálogo filtrado por tipo eléctrico es /?tipo=electrica (modificación). Si dudas, pregúntate si sin ese dato la pantalla sigue teniendo sentido: sin bicicletaId no hay ficha que enseñar (dinámico); sin tipo el catálogo se ve entero (consulta).

React Router puede gestionar la URL de dos maneras, y la elección tiene una consecuencia en el servidor que sorprende al desplegar por primera vez.

El requisito del servidor es la clave. Imagina que el usuario está en /estaciones/est-02 y pulsa F5. Esta vez el navegador sí pide /estaciones/est-02 al servidor de verdad, porque una recarga no la controla JavaScript. Si el servidor tiene un fichero por ruta, no encontrará nada y devolverá un 404, aunque en la aplicación la ruta funcionase perfectamente al navegar con enlaces.

La solución es configurar el servidor para que cualquier ruta desconocida devuelva index.html y deje que el enrutador del cliente resuelva. Es una línea de configuración en cualquier alojamiento moderno (Netlify, Vercel, Nginx, Apache), y el servidor de desarrollo de Vite ya lo hace por defecto, razón por la que este problema no aparece hasta el día del despliegue. Lo trataremos con detalle en 11-05.

Cuándo usar createHashRouter, entonces:

• Publicas en un alojamiento estático que no permite configurar reescrituras (el caso clásico: GitHub Pages sin trucos).
• Entregas la aplicación como fichero suelto, un CD-ROM interno o un file://.
• La incrustas en un sistema heredado cuyo servidor no controlas.

En cualquier otro caso, createBrowserRouter, que es el que usa CicloUrbano. La API es idéntica salvo el nombre de la función, así que cambiar de uno a otro es cuestión de una línea.

Este es el destino del módulo. Lo implementarás en 06-02 y 06-03, y lo respetarás durante el resto del curso:

Y así queda el árbol, ya con el anidamiento que construirás en 06-03:

Observa tres decisiones que se justificarán en su momento:

• Diseno es la ruta raíz, no un componente que envuelve a App. Así Cabecera y PieDePagina no se desmontan ni se vuelven a montar al cambiar de pantalla (06-03).
• El catálogo es una ruta índice, no path: '/' repetido. Es la pantalla que se ve cuando la URL coincide con el padre y nada más.
• La rama protegida es una ruta sin path: agrupa pantallas bajo un guardián sin añadir ningún segmento a la URL. /taller sigue siendo /taller, no /protegido/taller (06-05).

Creer que React Router hace peticiones al servidor. No las hace. Cambiar de ruta con <Link> es una operación puramente de cliente: se actualiza la URL y React repinta. Los datos siguen viniendo de donde vinieran (tu dominio.js, un fetch, un loader). Si al pasar de / a /estaciones esperas que el servidor te mande HTML nuevo, tienes el modelo mental equivocado.

Confundir el modo declarativo con el de datos y mezclar sus APIs. Es el error número uno hoy. Copias un ejemplo con <BrowserRouter>, otro con createBrowserRouter, y acabas con useNavigate lanzando «useNavigate() may be used only in the context of a component». Decide el modo al empezar el proyecto y no lo mezcles. En este curso: modo de datos, siempre.

Buscar en la documentación de React lo que está en la de React Router. No hay una sola mención a <Link> en react.dev, y no es un olvido: son proyectos distintos, con versiones y calendarios distintos. Ten a mano las dos referencias.

Instalar react-router-dom en v7 por costumbre. Funciona por compatibilidad, pero el paquete correcto es react-router. Si mezclas los dos importes en el mismo proyecto puedes acabar con dos copias del enrutador y errores de contexto incomprensibles.

Meter en la URL cosas que no deben estar ahí. La URL es pública, se comparte y se guarda en el historial. Un filtro de catálogo o el número de página sí van ahí; un token de sesión, un correo electrónico o el contenido de un formulario a medias, no.

Consejo: piensa el mapa de rutas antes de escribirlo. Dibujar en papel las pantallas y sus direcciones, como la tabla del apartado 10, ahorra reestructuraciones caras. La URL es una interfaz pública de tu aplicación: si mañana cambias /bicis/:id por /bicicletas/:bicicletaId, rompes los enlaces que la gente ya guardó.

Consejo: usa nombres de parámetro descriptivos. :bicicletaId y :estacionId en lugar de :id y :id. Cuando en 06-03 leas los parámetros de una ruta anidada tendrás varios a la vez, y dos id distintos son un problema; además el código se lee solo.

Repasa el componente App del apartado 1, el que usa useState para elegir sección. Un compañero propone «mejorarlo» leyendo el hash de la URL al arrancar:

Responde razonadamente:

1. ¿Qué problema de la lista del apartado 1 resuelve este cambio?
2. ¿Cuáles siguen sin resolverse?
3. ¿Qué le falta como mínimo para que el botón «atrás» funcione?

Para cada una de estas necesidades de CicloUrbano, decide si corresponde a un segmento dinámico, un parámetro de consulta, una ruta anidada o una ruta comodín, y escribe la URL resultante:

1. Ver la ficha de la bicicleta bici-005.
2. Ver solo las bicicletas de tipo carga en el catálogo.
3. Ver las incidencias de la estación est-02, dentro de su pantalla de detalle.
4. Mostrar «Página no encontrada» cuando alguien escribe /estacionez.
5. Ordenar el listado de estaciones por número de plazas, de mayor a menor.

Para cada escenario, di qué modo de React Router v7 (declarativo, de datos, de framework) y qué creador de enrutador (createBrowserRouter o createHashRouter) usarías, y por qué:

1. CicloUrbano tal como lo vas a construir: SPA con Vite, desplegada en Netlify.
2. Un panel interno que se distribuye como una carpeta de ficheros que los operarios abren desde el disco de red, con doble clic sobre index.html.
3. Una aplicación existente en React Router v6 con 40 rutas, a la que hay que añadir dos pantallas nuevas la semana que viene.
4. Una web pública nueva de CicloUrbano, con catálogo indexable por buscadores y renderizado en servidor.

Solución 1

1. Resuelve la recarga y, en parte, los marcadores: si el usuario está en #estaciones y pulsa F5, la aplicación arranca en la sección correcta, porque el hash sí se conserva y el estado inicial se calcula a partir de él. También podría guardar la URL en favoritos.
2. Siguen sin resolverse: el botón atrás (nadie escucha popstate, así que al retroceder cambia el hash pero React no se entera y la pantalla no cambia); los enlaces compartibles con parámetros (¿qué bicicleta? no cabe en un solo hash sin inventarse un formato); el crecimiento del condicional; y la indexación por buscadores, porque el hash no llega al servidor.
3. Como mínimo hacen falta dos cosas: un useEffect que suscriba un manejador a window.addEventListener('popstate', …) —con su limpieza correspondiente, como en 05-02— para sincronizar el estado cuando el usuario navega hacia atrás, y que todos los cambios de sección pasen por history.pushState en vez de por setSeccion a secas. En cuanto escribas esas dos piezas habrás empezado a construir tu propio enrutador, que es justo lo que conviene no hacer.

Solución 2

El criterio en los casos 2 y 5 es el del apartado 8: el filtro y la ordenación modifican una vista que existe igual sin ellos, así que van en la consulta. En el caso 1, sin bici-005 no hay ficha posible: es identidad, y va en el camino.

Solución 3

1. CicloUrbano en Netlify: modo de datos con createBrowserRouter. Es una SPA nueva sin necesidades de servidor, quiere URLs limpias y va a usar errorElement, useBlocker y ScrollRestoration. Netlify permite configurar la reescritura a index.html con un fichero _redirects de una línea.
2. Carpeta abierta desde el disco (file://): createHashRouter, sin discusión. No hay servidor que pueda reescribir nada, y con createBrowserRouter la primera recarga rompería la aplicación. El modo puede seguir siendo el de datos: createHashRouter también lo es.
3. Aplicación v6 con 40 rutas: mantener el modo declarativo que ya tiene y añadir las dos pantallas nuevas como dos <Route> más. Reescribir 40 rutas para ganar useBlocker no compensa; si el equipo decide migrar, que sea un proyecto propio y no un efecto colateral de una entrega. Coherencia por encima de modernidad.
4. Web pública con SEO y renderizado en servidor: el modo de framework de React Router v7 o directamente Next.js (10-01). En cuanto necesitas HTML generado en el servidor, el enrutamiento deja de ser solo cliente y el marco de trabajo debe encargarse de ambos lados. Aquí ni siquiera eliges entre historial de navegador y de hash: el hash queda descartado porque nunca llega al servidor.

El enrutamiento en el cliente resuelve el problema con el que se cerró el módulo 5: hacer que la URL y la interfaz se correspondan. Has visto que una aplicación de una sola página entrega un único index.html y que, a partir de ahí, la navegación consiste en interceptar los clics, llamar a history.pushState para cambiar la dirección sin recargar y dejar que el enrutador decida qué componente pintar, con la reconciliación de 01-05 encargándose de tocar solo lo que cambia. A cambio de esa complejidad, CicloUrbano gana enlaces compartibles, botones de atrás y adelante que funcionan, recarga en el punto correcto, marcadores, analítica por pantalla, indexación y la posibilidad de cargar el código de cada sección solo cuando hace falta.

También has fijado las decisiones que gobiernan el resto del módulo. React no trae enrutador porque es una biblioteca de interfaces, no un marco de trabajo, y el ecosistema ofrece React Router, TanStack Router y los enrutadores integrados de Next.js o Remix. De las tres formas de usar React Router v7 —declarativa, de datos y de framework— el curso emplea la de datos, con createBrowserRouter y RouterProvider, porque es la recomendada para una SPA con Vite y la única que habilita errorElement, useBlocker y ScrollRestoration; el clásico <BrowserRouter><Routes><Route> de v6 sigue siendo válido, es lo que verás en muchísimo código existente, y todos los conceptos se trasladan tal cual. Tienes el vocabulario del módulo —ruta, segmento dinámico, ruta anidada, outlet, ruta índice, enlace, navegación programática, parámetros de consulta—, sabes por qué createBrowserRouter exige que el servidor reescriba a index.html y en qué casos raros hace falta createHashRouter, y tienes delante el mapa completo de rutas de CicloUrbano.

Toca construirlo. En la próxima lección instalarás React Router, crearás src/rutas.jsx con el mapa, montarás <RouterProvider /> en main.jsx respetando el orden de proveedores que ya existe, reorganizarás el proyecto con una carpeta src/paginas/, sustituirás por fin los <a href="#…"> de la Cabecera por <NavLink> con clase activa, leerás el identificador de la bicicleta con useParams y pondrás el filtro del SelectorTipo en la URL con useSearchParams. La próxima lección es Configuración de React Router.