Cómo escribir su propio enrutador Typesafe React en 500 líneas

Cuando estaba aprendiendo React hace unos 6 años, reaccionar-router fue una de las primeras bibliotecas de terceros que adquirí. Quiero decir, tiene sentido: el enrutamiento es uno de los aspectos clave de las aplicaciones de página única modernas. Lo di por sentado. Para mí, reaccionar-router era una caja mágica, no tenía idea de cómo funciona internamente. Entonces, cuando después de un tiempo descubrí naturalmente cómo funciona el enrutamiento en general, fue un poco triste. No más magia, eh :( Pero me alegro de haber dejado atrás ese concepto de "cajas negras mágicas". Creo que es una idea realmente dañina. Comprender que pieza de tecnología ha sido construida por ingenieros, como tú y como yo, me inspira mucho y espero que haga lo mismo por ti. cada Entonces, únete a mí en esta publicación donde construiremos nuestro propio enrutador con seguridad tipográfica desde cero para abrir esa caja negra y comprender su funcionamiento interno. Este artículo asume que ya conoces React y te sientes cómodo con TypeScript. Características y limitaciones Permítanme resumir qué características de nuestro enrutador se tratarán en este artículo. Nuestra característica principal será la seguridad de tipos. Esto significa que deberá definir sus rutas con anticipación y TypeScript verificará que no pase ninguna tontería en lugar de la URL o intente obtener parámetros que faltan en la ruta actual. Esto requerirá algún tipo de gimnasia, pero no te preocupes, te guiaré. Además de eso, nuestro enrutador admitirá todo lo que esperarías de un enrutador promedio: navegación a URL, coincidencia de rutas, análisis de parámetros de ruta, navegación hacia atrás/adelante y bloqueo de navegación. Ahora, sobre las limitaciones. Nuestro enrutador funcionará solo en el navegador (¡lo siento, React Native!) y no admitirá SRR. El soporte de SSR debería ser relativamente fácil, pero esta publicación ya es enorme, por lo que no la cubriré. Terminología Ahora que tenemos una visión de lo que nos gustaría hacer, necesitamos hablar sobre estructura y terminología. Habrá muchos conceptos similares, por lo que definirlos de antemano es fundamental. Habrá dos tipos de rutas en nuestra biblioteca: rutas sin procesar y rutas analizadas. es solo una cadena que se parece a o ; es una plantilla para URL. La ruta sin formato puede contener parámetros, que son secciones que comienzan con dos puntos, como . La ruta sin formato /user/:id/info /login :id Este formato es fácil de usar para los desarrolladores, pero no tanto para un programa; Transformaremos esas rutas a un formato más amigable para las máquinas y las llamaremos . ruta analizada Pero los usuarios no abren rutas, abren URL. Y la URL es un identificador del recurso (página dentro de la aplicación en nuestro caso); podría verse así . Nuestro enrutador se preocupa principalmente por la segunda parte de la URL ( ), que llamaremos . http://example.app/user/42/info?anonymous=1#bio /user/42/info?anonymous=1#bio ruta La ruta consta de ( ), ( ) y ( ). El objeto que almacena esos componentes como campos separados se llamará . nombre de ruta /user/42/info parámetros de búsqueda ?anonymous=1 hash #bio ubicación Descripción general de alto nivel de la API Al crear bibliotecas de React, me gusta seguir tres pasos. En primer lugar, API imperativa. Sus funciones se pueden llamar desde cualquier lugar y, por lo general, no están vinculadas en absoluto a React. En el caso de un enrutador, serán funciones como , o . navigate getLocation subscribe Luego, en base a esas funciones, se crean enlaces como o . Y luego esas funciones y ganchos se utilizan como base para los componentes de construcción. En mi experiencia, esto funciona excepcionalmente bien y permite crear una biblioteca versátil y fácilmente ampliable. useLocation useCurrentRoute La API del enrutador comienza con la función . Se supone que el usuario debe pasar un mapa de todas las rutas sin procesar a la función, que analiza las rutas y devuelve un mapeo con la misma forma. Todas las API orientadas al desarrollador, como la generación de URL o la coincidencia de rutas, aceptarán rutas analizadas y no sin formato. defineRoutes const routes = defineRoutes({ login: '/login', user: { me: '/user/me', byId: '/user/:id/info', } }); El siguiente paso es pasar rutas analizadas a la función . Esta es la carne de nuestro enrutador. Esta función creará todas las funciones, enlaces y componentes. Esto puede parecer inusual, pero dicha estructura nos permite adaptar los tipos de argumentos y accesorios aceptados a un conjunto específico de rutas definidas en , garantizando la seguridad de tipos (y mejorando DX). createRouter routes const { Link, Route, useCurrentRoute, navigate, /* etc... */ } = createRouter(routes); devolverá funciones que se pueden usar en cualquier lugar de su aplicación (API imperativa), enlaces que permiten que sus componentes reaccionen a los cambios de ubicación y tres componentes: , y . Esto será suficiente para cubrir la mayoría de los casos de uso y podrá crear sus propios componentes basados en esas API. createRouter Link Route NotFound Programación a nivel de tipo para diversión y ganancias Comenzamos abordando la parte de seguridad tipográfica de nuestro discurso. Como mencioné antes, con un enrutador con seguridad de tipos, TypeScript le advertirá con anticipación sobre una situación como esta: O así: const { userld } = useRoute(routes.user.byId); Y si no puedes ver de inmediato qué está mal con estos, definitivamente necesitas un enrutador con seguridad de tipos :) El sistema de tipos en TypeScript es muy poderoso. Quiero decir, puedes crear un , un o incluso una usando programación de nivel de tipo. motor de ajedrez juego de aventuras base de datos SQL Ya está familiarizado con la 'programación a nivel de valores' donde manipula valores, por ejemplo, concatenando dos cadenas: function concat(a, b) { return a + b; } concat('Hello, ', 'World!'); // 'Hello, World!' ¡Pero también puedes hacerlo con tipos! type Concat = `${A}${B}`; type X = Concat ; // ^? type X = "Hello, World!" Sí, no es tan potente como las funciones habituales y tiene un aspecto diferente. Pero te permite hacer algunas cosas interesantes y útiles. Usaremos programación de nivel de tipo para extraer parámetros de rutas sin procesar y crear nuevos tipos que puedan verificar que el desarrollador no intente pasar valores incorrectos a o a la función que está construyendo la URL. Link La programación a nivel de tipo con TS podría convertirse rápidamente en un desastre ilegible. Afortunadamente para nosotros, ya existen varios proyectos que ocultan toda esta complejidad y nos permiten escribir código limpio como este: export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; Bastante bonito, ¿eh? Eso, por cierto, es todo el código que necesita para analizar los parámetros de la ruta sin formato. En este proyecto, usaremos la biblioteca ; nos ayudará a reducir la complejidad y la cantidad de código de nivel de tipo. hotscript Pero no es obligatorio: si te sientes aventurero, puedes intentar implementar todos estos tipos tú mismo. Puede encontrar algo de inspiración en el , que implementa funciones similares sin utilizar bibliotecas de tipos de terceros. enrutador Chicane Si vas a seguirlo, te recomiendo que crees un nuevo proyecto de React usando tu iniciador favorito (yo uso ) y comiences a codificar allí. De esta manera, podrás probar tu enrutador de inmediato. Vite Tenga en cuenta que los marcos como Next.js proporcionan su propio enrutamiento que puede interferir con este proyecto y, en su lugar, utilice React 'vainilla'. Si tiene alguna dificultad, puede encontrar el código completo . aquí Comience instalando paquetes de terceros: para utilidades de nivel de tipo y para analizar parámetros desde URL/ruta sin formato. hotscript regexparam npm install hotscript regexparam El primer ladrillo de construcción de nuestro tipo es el en bruto. La ruta sin formato debe comenzar con ; ¿Cómo codificarías eso en TS? Como esto: / export type RawRoute = `/${string}`; Fácil, ¿verdad? Pero no acepta una única ruta sin formato, acepta mapeo, posiblemente anidado, así que codifiquemos eso. Quizás tengas la tentación de escribir algo como esto: defineRoutes export type RawRoutesMap = { [key: string]: RawRoute | RawRoutesMap }; Esto funcionará. Sin embargo, este tipo puede ser infinitamente profundo y TS tendrá dificultades para calcularlo en algunos casos. Para facilitarle la vida a TS, limitaremos el nivel de anidamiento permitido. 20 niveles de anidamiento deberían ser suficientes para todas las aplicaciones y TS puede manejarlo fácilmente. Pero, ¿cómo se limita la profundidad de los tipos recursivos? Aprendí este truco de esta ; Aquí hay una versión modificada para nuestros requisitos: respuesta SO export type RecursiveMap = { [key: string]: RecursiveMap_ ; }; type RecursiveMap_ = MaxDepth extends Stack["length"] ? T : T | { [key: string]: RecursiveMap_ }; Este es nuestro primer tipo complejo, así que déjame explicarlo. Aquí tenemos dos tipos: funciona como un punto de entrada y llama pasándole un parámetro de tupla adicional. Esta tupla se usa para rastrear la profundidad del mapeo; con cada llamada agregamos un elemento a esta matriz. RecursiveMap RecursiveMap_ Y continuamos llamándolo hasta que la longitud de esta tupla sea igual a . En TS, cuando se usa con valores , también llamados literales (por ejemplo, específicamente , no ), significa "igual". MaxDepth extends específicos 42 number Y dado que tanto como son números específicos, este código se puede leer como . Verás que esta construcción se utiliza mucho. MaxDepth Stack["length"] MaxDepth === Stack["length"] ¿Por qué utilizar tuplas en lugar de simplemente sumar números? Bueno, ¡no es tan fácil sumar dos números en TypeScript! Hay para eso, y Hotscript también puede agregar números, pero requiere mucho código (incluso si no lo ve), lo que puede ralentizar su servidor TS y su editor de código si se usa excesivamente. una biblioteca completa Por lo tanto, mi regla general es evitar los tipos complejos tanto como sea razonablemente posible. Con este tipo de utilidad, podemos definir nuestro mapeo tan simple como: export type RawRoutesMap = RecursiveMap ; Eso es todo para los tipos de rutas sin formato. El siguiente en la cola es la ruta analizada. La ruta analizada es sólo un objeto JavaScript con algunos campos adicionales y una función; así es como se ve: export type ParsedRoute = { keys: RouteParam []; build(...params: PathConstructorParams ): Path ; raw: R; ambiguousness: number, pattern: RegExp; }; Comencemos a descomprimir esto desde el campo . Es simplemente una serie de parámetros necesarios para esta ruta. Así es como se hace: keys import { Pipe, Strings, Tuples } from "hotscript"; export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; En Hotscript, hay dos formas de llamar a una función: o . es útil cuando necesitas llamar a una sola función, pero en nuestro caso, ¡tenemos 4 de ellas! acepta entradas y, bueno, las canaliza a la primera función de una tupla proporcionada. Call Pipe Call Pipe El valor devuelto se pasa como entrada a la segunda función y así sucesivamente. En nuestro caso, si tuviéramos, por ejemplo, la ruta sin formato , se transformaría así: /user/:userId/posts/:postId export type Beep = Pipe , // ["user", ":userId", "posts", ":postId"] Tuples.Filter >, // [":userId", ":postId"] Tuples.Map >, // ["userId", "postId"] Tuples.ToUnion // "userId" | "postId" ] >; ¿Ver? ¡Ésta es la magia de la programación a nivel de tipo! Ahora, abordemos esa función . Acepta parámetros de ruta (como y ) y parámetros de búsqueda/hash opcionales, y los combina en una ruta. Eche un vistazo a una implementación : build userId postId PathConstructorParams // Allows us to also accept number and // any other type which can be converted into string export type StringLike = { toString: () => string }; export type SearchAndHashPathConstructorParams = { hash?: string, search?: string | { [key: string]: string, } }; export type RouteParamsMap = { [key in RouteParam ]: Val }; export type PathConstructorParams = | [RouteParamsMap ] | [RouteParamsMap , SearchAndHashPathConstructorParams]; Los parámetros de la función se definen como una matriz (que luego se distribuye en la definición de la función). función ), donde el primer elemento es y el segundo es opcional. ¿Qué pasa con la devolución del valor de ? Ya establecimos su camino, pero ¿cómo lo describe con TypeScript? build RouteParamsMap SearchAndHashPathConstructorParams build Bueno, este es bastante similar a , ¡pero requiere un poco más de gimnasia! RouteParam import { Fn } from "hotscript"; interface ReplaceParam extends Fn { return: this["arg0"] extends `:${string}` ? string : this["arg0"]; } // Leading slashes will be removed by Split , so we need to // add them back after our manipulations type Pathname = `/${Pipe , Tuples.Map , Tuples.Join ] >}${Route extends `${string}/` ? '/' : ''}`; export type Path = Pathname | `${Pathname }?${string}` | `${Pathname }#${string}`; Lo que hacemos aquí es dividir nuestra ruta en segmentos, mapear cada segmento y llamar a nuestra función personalizada en cada uno. Comprueba si el segmento actual es un parámetro y lo reemplaza con o devuelve el segmento tal como está. La 'función' puede parecer un poco extraña, pero así es como se definen funciones personalizadas con Hotscript. ReplaceParam string ReplaceParam Indicamos explícitamente que la ruta consta solo de una ruta, una ruta seguida de un signo de interrogación (esto cubre las URL con parámetros de búsqueda y hash) o un símbolo de almohadilla (esto cubre las URL sin parámetros de búsqueda pero con hash). También necesitaremos un tipo para describir la ruta coincidente, es decir, ruta analizada con parámetros capturados de la URL: // Interface (and not type) because we need to use `this` export interface RouteWithParams { route: ParsedRoute , params: RouteParamsMap , // TS can't properly infer type of route object with simple // check like currentRoute.route === routes.user.byId, so we // need our custom type guard matches: (route: ParsedRoute ) => this is RouteWithParams , } El último tipo es ; Es similar a , pero para rutas analizadas. ParsedRoutesMap RawRoutesMap // This accepts RawRoutesMap and transforms it into // mapping of parsed routes of same shape export type ParsedRoutesMap = { [Key in keyof RM]: RM[Key] extends RawRoute ? ParsedRoute : RM[Key] extends RawRoutesMap ? ParsedRoutesMap : never; }; Y ya dicho, terminamos con los tipos. Habrá algunos más, pero son más simples y los cubriremos a medida que avancemos en la implementación. Si la programación a nivel de tipo es algo que le gustaría probar más, puede consultar para obtener más información e intentar resolver (también tienen una buena ). Type-level Typescript desafíos de tipo lista de recursos Analizador de rutas Finalmente, volvemos a la codificación de nivel de valor normal. Pongamos manos a la obra implementando . defineRoutes export const typedKeys = (obj: T) => { return Object.keys(obj) as Array ; }; export const defineRoutes = (routesMap: T): ParsedRoutesMap => { const entries = typedKeys(routesMap).map((key) => { const entry = routesMap[key]; if (typeof entry === 'string') { return [key, parseRoute(entry)] as const; } else { // Nested map return [key, defineRoutes(entry)] as const; } }); return Object.fromEntries(entries); }; Nada complejo aquí; Profundicemos en la función . parseRoute import { parse, inject, type RouteParams as RegexRouteParams } from "regexparam"; export class InvalidRoute extends Error { }; export class InvalidRouteParams extends Error { }; const parseRoute = (route: R): ParsedRoute => { if (!route.startsWith('/')) { throw new InvalidRoute('route should start with slash (/)') } const { keys, pattern } = parse(route); const hasRequiredParams = keys.length > 0; const parsedRoute: ParsedRoute = { build(...args) { const params = ( hasRequiredParams ? args[0] : undefined ) as RouteParamsMap | undefined; const searchAndHash = ( hasRequiredParams ? args[1] : args[0] ) as SearchAndHashPathConstructorParams | undefined; if (hasRequiredParams) { if (!params) { throw new InvalidRouteParams( `Parameters for route ${route} weren't provided` ); } const missingKeys = keys.filter(k => !(k in params)); if (missingKeys.length) { throw new InvalidRouteParams( `Missing parameters for route ${route}: ${missingKeys.join(', ')}` ); } } else if (args.length > 1) { throw new InvalidRouteParams( `Route ${route} doesn't accept any parameters, received ${args[0]}` ); } let path = hasRequiredParams ? inject(route, params as RegexRouteParams ) : route; if (searchAndHash && searchAndHash.search) { if (typeof searchAndHash.search === 'string') { path += searchAndHash.search.startsWith('?') ? searchAndHash.search : '?' + searchAndHash.search; } else { path += '?' + new URLSearchParams(searchAndHash.search).toString(); } } if (searchAndHash && searchAndHash.hash) { path += searchAndHash.hash.startsWith('#') ? searchAndHash.hash : '#' + searchAndHash.hash; } return path as Path ; }, raw: route, keys: keys as RouteParam [] || [], ambiguousness: keys.length, pattern: pattern, }; return parsedRoute; }; también es muy simple, aunque notablemente más largo. Para analizar la ruta y extraer parámetros, utilizamos la biblioteca . Nos permite obtener una serie de parámetros necesarios para la ruta y genera una expresión regular que luego usaremos para hacer coincidir la URL con la ruta. parseRoute regexparam Almacenamos esta información junto con la ruta original sin procesar utilizada para construir este objeto y el nivel de ambigüedad (que es solo una cantidad de parámetros en la ruta). Envoltorio de historia Cada enrutador tiene que almacenar su estado en algún lugar. En el caso de las aplicaciones en el navegador, eso realmente se reduce a 4 opciones: en memoria (ya sea en una variable de estado dentro del componente raíz o en una variable fuera del árbol de componentes), API de historial o parte hash de la URL. El enrutamiento en memoria puede ser tu elección si no quieres mostrarle al usuario que tienes rutas, por ejemplo, si estás codificando un juego en React. Almacenar la ruta en hash puede ser útil cuando tu aplicación React es solo una página en una aplicación más grande y no puedes simplemente cambiar la URL como quieras. Pero en la mayoría de los casos, utilizar History API será la mejor opción. Es compatible con SSR (otras opciones no lo son), sigue patrones de comportamiento a los que el usuario está acostumbrado y simplemente se ve más limpio. En este proyecto, también lo usaremos. Sin embargo, tiene un defecto notable: es prácticamente inutilizable sin envoltorios adicionales. Con History AP, puede suscribirse al evento y el navegador le informará cuando cambie la URL. Pero sólo si el cambio lo inicia el usuario, por ejemplo, haciendo clic en el botón Atrás. Si se inicia un cambio de URL desde el código, debe realizar un seguimiento usted mismo. popstate La mayoría de los enrutadores que estudié usan su propio contenedor: reaccionar-router y chicane usan el paquete NPM , el enrutador TanStack tiene su y wouter no tiene un contenedor completo, pero aún tiene que . de historial propia implementación parchear el historial Entonces, implementemos nuestro propio contenedor. export type HistoryLocation = Pick ; export type NavigationBlocker = (isSoftNavigation: boolean) => boolean; export const createHistory = () => { const winHistory = window.history; const winLocation = window.location; const getLocation = (): HistoryLocation => { return { origin: winLocation.origin, href: winLocation.href, pathname: winLocation.pathname, search: winLocation.search, hash: winLocation.hash, }; }; /* Some magic code */ return /* something... */; }; Hay dos tipos que usaremos, y . Primero, es una versión un poco limitada del tipo incorporado (ese es el tipo de ), y el segundo se cubrirá una vez que lleguemos al bloqueo de navegación. Todo el código adicional de este capítulo irá dentro de la función . HistoryLocation NavigationBlocker Location window.location createHistory Comencemos implementando una suscripción a los cambios del historial. Usaremos funciones de estilo React para suscribirte en este proyecto: llamas a pasando una devolución de llamada y devuelve otra función a la que debes llamar cuando quieras cancelar la suscripción. subscribe const subscribers: Set = new Set(); const onChange = () => { subscribers.forEach(fn => { try { fn(); } catch (err) { console.error('Error while handling location update', err); } }) }; const subscribe = (listener: VoidFunction) => { subscribers.add(listener); return () => { subscribers.delete(listener); }; }; El siguiente paso es reaccionar a los cambios de ubicación, incluidos los cambios realizados mediante programación. ¿Como lo harias? Con , por supuesto. Eso puede parecer un poco sucio (y realmente lo es), pero desafortunadamente no tenemos mejores opciones. parches de mono const origPushState = winHistory.pushState.bind(winHistory); const origReplaceState = winHistory.replaceState.bind(winHistory); winHistory.pushState = (data, unused, url) => { // tryNavigate will be covered later tryNavigate(() => { origPushState(data, unused, url); onChange(); }); }; winHistory.replaceState = (data, unused, url) => { tryNavigate(() => { origReplaceState(data, unused, url); onChange(); }); }; // This event is emmited when user initiates navigation // or when calling history.go, history.back and history.forward window.addEventListener('popstate', onChange); Y la última pieza importante que falta en nuestra implementación histórica es el bloqueo de navegación: una característica que le permite interceptar la solicitud de navegación y cancelarla condicionalmente. Un ejemplo canónico de bloqueo de navegación sería evitar que el usuario pierda su progreso en un formulario. let blockers: NavigationBlocker[] = []; const beforeUnloadHandler = (event: Event) => { const blocked = blockers.some(blocker => blocker(false)); if (blocked) { event.preventDefault(); // @ts-ignore For older browsers event.returnValue = ''; return ''; } }; const tryNavigate = (cb: VoidFunction) => { const blocked = blockers.some(blocker => blocker(true)); if (blocked) return; cb(); }; const addBlocker = (blocker: NavigationBlocker) => { blockers.push(blocker); if (blockers.length === 1) { addEventListener('beforeunload', beforeUnloadHandler, { capture: true }); } return () => { blockers = blockers.filter(b => b !== blocker); if (blockers.length === 0) { removeEventListener('beforeunload', beforeUnloadHandler, { capture: true }); } } }; En nuestra implementación, un bloqueador es una función que devuelve un valor booleano que indica si necesitamos bloquear esta navegación. En lo que respecta al bloqueo de navegación, existen dos tipos de navegación y tendremos que manejarlos de manera diferente. Por un lado, está la navegación suave, cuando el usuario navega de una página de nuestra aplicación a otra página de nuestra aplicación. Lo controlamos completamente y, por lo tanto, podemos bloquearlo, mostrar cualquier interfaz de usuario personalizada (para confirmar la intención del usuario) o realizar acciones después de bloquear la navegación. Por otro lado, existe la navegación difícil, cuando el usuario navega a otro sitio o cierra la pestaña por completo. El navegador no puede permitir que JavaScript decida si se debe realizar esta navegación, ya que sería un problema de seguridad. Pero el navegador permite que JavaScript indique si queremos mostrar un cuadro de diálogo de confirmación adicional al usuario. Al bloquear la navegación suave, es posible que desee mostrar una interfaz de usuario adicional (por ejemplo, un cuadro de diálogo de confirmación personalizado), pero en el caso de una navegación difícil, en realidad no tiene sentido ya que el usuario solo la verá si decide permanecer en la página y , en ese punto, es inútil y confuso. Cuando nuestro historial llama a la función de bloqueo de navegación, proporcionará un valor booleano que indica si estamos realizando una navegación suave. Y con todo eso, sólo necesitamos devolver nuestro objeto de historial: return { subscribe, getLocation, push: winHistory.pushState, replace: winHistory.replaceState, go: (distance: number) => tryNavigate(() => winHistory.go.call(winHistory, distance)), back: () => tryNavigate(() => winHistory.back.call(winHistory)), forward: () => tryNavigate(() => winHistory.forward.call(winHistory)), addBlocker, }; Paso 1: API imperativa Finalmente estamos aquí. La API imperativa será la base para todos los enlaces y componentes adicionales y permitirá al desarrollador crear enlaces personalizados para cubrir sus necesidades. En primer lugar, necesitamos transformar nuestro mapa de rutas en una matriz plana. De esta manera, será mucho más fácil recorrer todas las rutas, lo que será útil cuando comencemos a trabajar en la parte de coincidencia de rutas. Necesitamos tanto una utilidad de tipo (que transformará en una unión de ) como una función (que transformará en una matriz de rutas analizadas). Comencemos con el tipo: ParsedRoutesMap ParsedRoute routesMap export type Values = T[keyof T]; type FlattenRouteMap = T extends ParsedRoute | RawRoute ? T : T extends ParsedRoutesMap | RawRoutesMap ? AllRoutesFromMap : never; export type AllRoutesFromMap | RawRoutesMap > = FlattenRouteMap >; Puede parecer innecesario dividir esto en dos tipos, pero hay una razón muy importante para ello: si lo implementa como un tipo único que se llama a sí mismo, TS se quejará de que el tipo es excesivamente profundo y posiblemente infinito. Entonces, solucionamos esto dividiéndolo en dos tipos que se llaman entre sí. Para una función de nivel de valor, también necesitaremos un tipo de protección para verificar si el valor pasado es una ruta analizada. export const isParsedRoute = ( route: any ): route is ParsedRoute => { return !!route && typeof route === 'object' && typeof route.raw === 'string' && typeof route.build === 'function'; } export const getAllRoutes = ( routesMap: ParsedRoutesMap ): ParsedRoute >[] => { type PossibleRawRoute = AllRoutesFromMap ; return typedKeys(routesMap).flatMap((k) => { const val = routesMap[k]; if (isParsedRoute (val)) { return [val] as const; } // At this point we know that val isn't ParsedRoute, so it has to be map of routes // but TS can't infer that, so we help him a little by casting val to correct type return getAllRoutes(val as ParsedRoutesMap ); }); }; Ahora, comencemos a implementar nuestro enrutador. Al igual que con la historia, en este y los dos capítulos siguientes, todo el código irá a la función , a menos que se indique lo contrario. createRouter import { useSyncExternalStore, ComponentType, useMemo, MouseEventHandler, ComponentProps, useEffect } from 'react'; export const createRouter = (routesMap: ParsedRoutesMap ) => { // Type for any possible route from passed routesMap type RouteType = AllRoutesFromMap ; // Similar to above, but for matched routes, ie includes URL parameters type BindedRouteWithParams = RouteWithParams ; // Some of our functions will accept route filter, // which can be single parsed route, array or object type RouteFilter = | ParsedRoute | ParsedRoute [] | Record >; const history = createHistory(); const routes = getAllRoutes(routesMap); }; En primer lugar, enseñemos a nuestro enrutador a hacer coincidir la ubicación actual con una de las rutas conocidas. Un par de utilidades pueden tener un alcance global o archivos separados, no dentro de la función : createRouter export const filterOutFalsy = (obj: T[]): Exclude [] => { return obj.filter(Boolean) as Exclude []; }; export class RouteMatchingConflict extends Error { }; // This will be used later export class RouteMismatch extends Error { }; Y este código va a la función . createRouter const extractRouteParams = ( pathname: string, parsedRoute: ParsedRoute ) => { const match = parsedRoute.pattern.exec(pathname); if (!match) return undefined; // Extract all route parameters from match array // and construct object from them return Object.fromEntries(parsedRoute.keys.map((key, index) => { return [key, match[index + 1]]; })) as RouteParamsMap ; }; const findMatchingRoute = ( location: HistoryLocation ): BindedRouteWithParams | undefined => { const matchingRoutes = filterOutFalsy(routes.map(route => { const params = extractRouteParams ( location.pathname, route ); if (!params) return undefined; return { route, params, matches (r: ParsedRoute ) { return route === r; }, }; })); if (matchingRoutes.length === 0) return undefined; if (matchingRoutes.length === 1) return matchingRoutes[0]; // At this point we have multiple matching routes :/ // Gotta decide which one we prefer let lowestAmbiguousnessLevel = Infinity; let lowestAmbiguousnessMatches: BindedRouteWithParams[] = []; matchingRoutes.forEach((match) => { if (match.route.ambiguousness === lowestAmbiguousnessLevel) { lowestAmbiguousnessMatches.push(match); } else if (match.route.ambiguousness m.route.raw).join(', ')}` ); } return lowestAmbiguousnessMatches[0]; }; let currentRoute = findMatchingRoute(history.getLocation()); // This function will be later returned from createRouter function const getCurrentRoute = () => currentRoute; Aquí repasamos todas las rutas conocidas e intentamos hacer coincidir cada una con la ubicación actual. Si la expresión regular de la ruta coincide con la URL, obtenemos los parámetros de ruta de la URL; de lo contrario, obtenemos . Para cada ruta coincidente, creamos un objeto y lo guardamos en una matriz. Ahora bien, si tenemos 0 o 1 rutas coincidentes, todo es sencillo. null RouteWithParams Sin embargo, si más de una ruta coincide con la ubicación actual, tendremos que decidir cuál tiene mayor prioridad. Para solucionar esto, utilizamos el campo . Como recordarás, esta ruta tiene una serie de parámetros y se prioriza una ruta con la menor . ambiguousness ambiguousness Por ejemplo, si tuviéramos dos rutas y , la ubicación coincidiría con ambas rutas. Pero es bastante obvio que esta URL debe corresponder a la ruta , no . /app/dashboard /app/:section http://example.com/app/dashboard /app/dashboard /app/:section Sin embargo, este algoritmo no es a prueba de balas. Por ejemplo, las rutas y coincidirán con la URL . Y como tienen el mismo nivel de ambigüedad, nuestro router no podrá decidir cuál debe tener prioridad. /app/:user/settings/:section /app/dashboard/:section/:region http://example.com/app/dashboard/settings/asia Ahora, necesitamos unir este código para reaccionar a los cambios de ubicación y actualizar la variable ; currentRoute const areRoutesEqual = ( a: RouteWithParams | undefined, b: RouteWithParams | undefined ): boolean => { if (!a && !b) return true; // Both are undefined if ((!a && b) || (a && !b)) return false; // Only one is undefined if (!a!.matches(b!.route)) return false; // Different routes // Same routes, but maybe parameters are different? const allParamsMatch = a.route.keys.every(key => a.params[key] === b!.params[key]); return allParamsMatch; }; history.subscribe(() => { const newRoute = findMatchingRoute(history.getLocation()); if (!areRoutesEqual(newRoute, currentRoute)) { currentRoute = newRoute; notifyRouteChange(); // Will be covered later } }); Ahora, nuestro enrutador reacciona a los cambios de ubicación y el usuario siempre puede obtener la ruta actual, ¡sí! Pero no es muy útil sin la posibilidad de suscribirse a cambios de ruta, así que agreguemos eso. El enfoque es muy similar al que usamos en el contenedor histórico. const subscribers: Set = new Set(); const subscribe = (cb: VoidFunction) => { subscribers.add(cb); return () => void subscribers.delete(cb); }; const notifyRouteChange = () => { subscribers.forEach(cb => { try { cb(); } catch (err) { console.error('Error in route change subscriber', err); } }); }; Para realizar la navegación, expondremos las funciones y , que son un contenedor simple para y : navigate navigateUnsafe history.push history.replace // This function accepts any string path (no type-safety) const navigateUnsafe = ( path: string, { action = 'push' }: { action?: 'push' | 'replace' } = {} ) => { history[action]({}, '', path) }; // And this function accepts only paths that correspond to one of routes const navigate = ( path: Path , options: { action?: 'push' | 'replace' } = {} ) => { navigateUnsafe(path, options); }; Bueno, ¡ese sí que es un enrutador real! Muy básico, pero funcionando de todos modos. Todavía tenemos algunos ganchos y componentes para implementar, pero a partir de aquí se vuelve mucho más fácil. Paso 2: Ganchos Para los ganchos, podemos comenzar con los simples que devuelven la ubicación actual y la ruta actual. Son bastante fáciles por sí solos, pero los convierte en una sola línea. La forma en que diseñamos nuestra API imperativa anteriormente nos permitió reducir drásticamente el código para estos enlaces. useSyncExternalStore const useLocation = () => { return useSyncExternalStore(history.subscribe, history.getLocation); }; const useCurrentRoute = () => { return useSyncExternalStore(subscribe, getCurrentRoute); }; Al codificar componentes que se supone que deben representarse solo en una ruta/conjunto de rutas específico, puede usar para obtener la ruta actual, verificar si coincide con los criterios y luego usar sus parámetros (o generar un error). useCurrentRoute Pero esta es una tarea tan común que sería un delito obligar a nuestros usuarios a escribir su propio enlace para ello; nuestro enrutador debería proporcionarlo de forma inmediata. function useRoute (filter: RouteFilter , strict?: true): RouteWithParams ; function useRoute (filter: RouteFilter , strict: false): RouteWithParams | undefined; function useRoute (filter: RouteFilter , strict?: boolean): RouteWithParams | undefined { const currentRoute = useCurrentRoute(); const normalizedFilter = Array.isArray(filter) ? filter : isParsedRoute(filter) ? [filter] : Object.values(filter); const isMatching = !!currentRoute && normalizedFilter.some(route => currentRoute.matches(route)); if (isMatching) return currentRoute as RouteWithParams ; else { if (strict === false) return undefined; throw new RouteMismatch( `Current route doesn't match provided filter(s)` ); } } Este gancho tiene dos versiones: estricta y relajada. Si el usuario pasa como segundo parámetro (o no pasa nada, ya que es el valor predeterminado), este enlace generará un error si la ruta actual no coincide con uno de los filtros proporcionados. true true De esta manera, puede estar seguro de que el gancho devolverá una ruta coincidente o no regresará en absoluto. Si el segundo parámetro es falso, en lugar de generar una excepción, el gancho simplemente devolverá un valor indefinido si la ruta actual no coincide con los filtros. Para describir este comportamiento en TypeScript, utilizamos una característica llamada . Esto nos permite definir múltiples definiciones de funciones con diferentes tipos, y TypeScript elegirá automáticamente una para usar cuando el usuario llame a dicha función. sobrecarga de funciones Además de los parámetros de ruta, es posible que se pasen algunos datos en los parámetros de búsqueda, así que agreguemos un enlace para analizarlos desde la cadena hasta el mapeo. Para esto, usaremos la API integrada del navegador . URLSearchParams const useSearchParams = () => { const location = useLocation(); return useMemo(() => { return Object.fromEntries( (new URLSearchParams(location.search)).entries() ); }, [location.search]); }; Y el último gancho en esta sección es , que también es bastante simple: simplemente aceptará devolución de llamada y envolverá llamadas a en un efecto, para volver a adjuntar el bloqueador si cambia. useNavigationBlocker history.addBlocker const useNavigationBlocker = (cb: NavigationBlocker) => { useEffect(() => { return history.addBlocker(cb); }, [cb]); }; ¡Ahora, pasemos a los componentes! Paso 3: Componentes ¿Cuál es el primer componente que me viene a la mente cuando se mencionan las bibliotecas de enrutamiento? Apuesto a que es o, al menos, algo parecido. Como vio anteriormente, nuestros ganchos eran muy simples debido a una API imperativa bien diseñada que hace todo el trabajo pesado. Route Lo mismo ocurre con los componentes; El usuario puede implementarlos fácilmente en unas pocas líneas de código. Pero somos una biblioteca de enrutamiento seria, incluyamos baterías en la caja :) type RouteProps = { component: ComponentType, match: RouteFilter }; const Route = ({ component: Component, match }: RouteProps) => { const matchedRoute = useRoute(match, false); if (!matchedRoute) return null; return ( ); }; Bueno, ¡eso fue fácil! ¿Quieres adivinar cómo implementamos el componente ? :) NotFound type NotFoundProps = { component: ComponentType }; const NotFound = ({ component: Component }: NotFoundProps) => { const currentRoute = useCurrentRoute(); if (currentRoute) return null; return ( ); }; Y el último componente necesario para nuestro enrutador es , que es un poco más complicado. No puedes simplemente usar ya que siempre iniciará una navegación difícil y no proporciona ninguna seguridad de tipos. Entonces, abordemos estos problemas: Link type LinkProps = Omit , 'href'> & ( // Our link accepts either type-strict href // or relaxed unsafeHref { href: Path , unsafeHref?: undefined } | { href?: undefined, unsafeHref: string } ) & { action?: 'push' | 'replace' }; const Link = ({ action = 'push', onClick, href, unsafeHref, ...props }: LinkProps) => { const hrefToUse = (href ?? unsafeHref)!; const targetsCurrentTab = props.target !== '_blank'; const localOnClick: MouseEventHandler = (event) => { if (onClick) { onClick(event); if (event.isDefaultPrevented()) { // User-defined click handler cacnelled navigation, we should exit too return; } } const inNewTab = !targetsCurrentTab || event.ctrlKey || event.shiftKey || event.metaKey || event.button === 1; if (!isExternal && !inNewTab) { event.preventDefault(); navigateUnsafe(hrefToUse, { action }); } }; const isExternal = useMemo(() => { if (!hrefToUse) return false; return new URL(hrefToUse, window.location.href).origin !== location.origin; }, [hrefToUse]); return }; De manera similar a la función , el tipo de componente verifica la URL que le pasa pero también le permite proporcionar una URL de cadena arbitraria (como una trampilla de escape o para enlaces externos). Para anular el comportamiento de , adjuntamos nuestro propio oyente , dentro del cual necesitaremos llamar al original (pasado a nuestro componente ). navigate Link onClick onClick Link Después de eso, verificamos si el desarrollador no canceló la navegación (si lo fue, debemos ignorar el evento). Si todo está bien, comprobamos si el enlace no es externo y si debe estar abierto en la pestaña actual. Y solo entonces podremos cancelar la navegación física incorporada y, en su lugar, llamar a nuestra propia función . navigateUnsafe Y ahora, solo necesitamos devolver todas nuestras funciones, enlaces y componentes (junto con algunas funciones reexportadas directamente desde el historial) desde la función . createRouter return { // Directly re-exported from history go: history.go, back: history.back, forward: history.forward, addBlocker: history.addBlocker, getLocation: history.getLocation, subscribeToLocation: history.subscribe, // Imperative API subscribe, getCurrentRoute, navigate, navigateUnsafe, // Hooks useLocation, useCurrentRoute, useRoute, useSearchParams, useNavigationBlocker, // Components Link, Route, NotFound, }; Y con eso, nuestro enrutador estará listo. ¡Ahora podemos crear nuestra pequeña aplicación para mostrar nuestro pequeño enrutador que acabamos de crear! Por cierto, puedes encontrar el código completo para este enrutador (incluido el código de una aplicación de ejemplo) . aquí Armar las piezas del rompecabezas Entonces, ¿cómo se une todo este código? ¡Muy bien, si lo digo yo mismo! Imagina que estás creando una aplicación para tomar notas. En primer lugar, comenzarías definiendo las rutas y creando un enrutador como este: export const routes = defineRoutes({ // Yep, this will be very minimal app root: '/', newNote: '/new', note: '/note/:noteId', }); const router = createRouter(routes); // Export functions and component you will be using export const { navigate, Link, Route, NotFound, useRoute, useNavigationBlocker } = router; Y luego, vincula las rutas que ha definido con los componentes de la página: function App() { return ( {/* This is how you build URL for Link */} View all notes Create new ) } Cuando estás en , necesitas obtener un ID de nota de la URL, por lo que usas un enlace : NoteDetailsPage useRoute export const NoteDetailsPage = () => { const { getNote } = useNotes(); const { params } = useRoute(routes.note); const note = getNote(params.noteId); return note ? (<> {note.title} {note.text} ) : ( Not found ); }; Y al crear una nueva nota, probablemente quieras confirmar la intención del usuario si navega sin guardar la nota: export const NewNotePage = () => { const saveNote = () => { isSubmittingNoteRef.current = true; const note = createNote(title, text); // And this is programmatic redirect navigate(routes.note.build({ noteId: note.id })); isSubmittingNoteRef.current = false; }; const [title, setTitle] = useState(''); const [text, setText] = useState(''); const { createNote } = useNotes(); const isSubmittingNoteRef = useRef(false); useNavigationBlocker((isSoftNavigation) => { const dirty = title !== '' || text !== ''; if (!dirty || isSubmittingNoteRef.current) return false; if (isSoftNavigation) { const confirmation = confirm('Do you want to leave?'); return !confirmation; } else { return true; } }); return <> New note setTitle(e.target.value)} /> setText(e.target.value)} /> Save ; }; Posibles mejoras Si bien nuestro enrutador sí enruta, no es rival para soluciones listas para producción como el enrutador TanStack, el enrutador reaccionar o el enrutador Next.js. Quiero decir, son solo ~500 líneas de código, eso no es mucho. ¿Pero qué es exactamente lo que falta? En primer lugar, renderizado del lado del servidor. Hoy en día, es posible que no todas las aplicaciones necesiten SSR, pero se espera que todas las bibliotecas de enrutamiento lo admitan. Agregar representación del lado del servidor a una cadena (¡no transmitir SSR!) implicará crear un diferente que almacenará la ubicación actual en la memoria (ya que no hay una API de historial en el servidor) y lo conectará a la función . history createRouter No sé lo difícil que será implementar el streaming SSR, pero supongo que estará fuertemente relacionado con el soporte de Suspense. En segundo lugar, este enrutador no se integra bien con el renderizado concurrente. Principalmente debido a nuestro uso de , ya que no es compatible con . Funciona de esta manera para evitar el desgarro: una situación en la que una parte de la interfaz de usuario se representa con un valor de tienda particular, pero el resto de la interfaz de usuario se representa con uno diferente. useSyncExternalStore transiciones sin bloqueo Y debido a esto, el enrutador no se integra bien con Suspense, ya que por cada actualización de ubicación que se suspenda, se mostrará un respaldo. Por cierto, cubrí la concurrencia en React en este , y en , hablo sobre Suspense, obtención de datos y de gancho. artículo este use Pero incluso con estas desventajas, espero que este artículo te haya resultado interesante y hayas construido tu propio enrutador a lo largo del camino :)