Como escrever seu próprio roteador Typesafe React em 500 linhas

Quando eu estava aprendendo React, há cerca de 6 anos, react-router foi uma das primeiras bibliotecas de terceiros que adquiri. Quero dizer, faz sentido: o roteamento é um dos aspectos principais dos aplicativos modernos de página única. Eu tomei isso como certo. Para mim, o react-router era uma caixa mágica, não tinha ideia de como funcionava internamente. Então, quando depois de algum tempo eu naturalmente descobri como funciona o roteamento em geral, fiquei um pouco triste. Chega de magia, hein :( Mas estou feliz por ter deixado para trás esse conceito de “caixas pretas mágicas”. Acho que é uma ideia muito prejudicial. Entender que peça de tecnologia foi construída por engenheiros, assim como você e eu, me inspira muito e espero que faça o mesmo por você. cada Então, junte-se a mim neste post onde construiremos nosso próprio roteador typesafe do zero para abrir essa caixa preta e entender seu funcionamento interno. Este artigo pressupõe que você já conheça o React e esteja confortável com o TypeScript. Recursos e limitações Deixe-me descrever quais recursos do nosso roteador serão abordados neste artigo. Nosso recurso matador será a segurança de tipografia. Isso significa que você precisará definir suas rotas com antecedência e o TypeScript verificará se você não passou alguma bobagem em vez de URL ou tentará obter parâmetros que estão faltando na rota atual. Isso exigirá algum tipo de ginástica, mas não se preocupe, vou orientá-lo. Além disso, nosso roteador suportará tudo o que você esperaria de um roteador comum: navegação para URLs, correspondência de rotas, análise de parâmetros de rota, navegação para trás/para frente e bloqueio de navegação. Agora, sobre limitações. Nosso roteador funcionará apenas no navegador (desculpe, React Native!) E não suportará SRR. O suporte SSR deve ser relativamente fácil, mas este post já é enorme, então não vou abordá-lo. Terminologia Agora que temos uma visão do que gostaríamos de fazer, precisamos falar sobre estrutura e terminologia. Haverá muitos conceitos semelhantes, portanto defini-los com antecedência é crucial. Haverá dois tipos de rotas em nossa biblioteca: rotas brutas e rotas analisadas. é apenas uma string que se parece com ou ; é um modelo para URLs. A rota bruta pode conter parâmetros, que são seções que começam com dois pontos, como . A rota bruta /user/:id/info /login :id Este formato é fácil de usar para desenvolvedores, mas não tanto para um programa; transformaremos essas rotas em um formato mais amigável à máquina e chamaremos isso de . rota analisada Mas os usuários não abrem rotas, eles abrem URLs. E URL é um identificador do recurso (página dentro do aplicativo no nosso caso); pode ser parecido com . Nosso roteador se preocupa principalmente com a segunda parte da URL ( ), que chamaremos . http://example.app/user/42/info?anonymous=1#bio /user/42/info?anonymous=1#bio de path O caminho consiste em nome do ( ), ( ) e ( ). O objeto que armazena esses componentes como campos separados será chamado . caminho /user/42/info parâmetros de pesquisa ?anonymous=1 hash #bio location Visão geral de alto nível da API Ao construir bibliotecas React, gosto de seguir três etapas. Em primeiro lugar, API imperativa. Suas funções podem ser chamadas de qualquer lugar e geralmente não estão vinculadas ao React. No caso de um roteador, serão funções como , ou . navigate getLocation subscribe Então, com base nessas funções, são criados ganchos como ou . E então essas funções e ganchos são usados como base para a construção de componentes. Isso funciona excepcionalmente bem, na minha experiência, e permite criar uma biblioteca facilmente extensível e versátil. useLocation useCurrentRoute A API do roteador começa com a função . O usuário deve passar um mapa de todas as rotas brutas para a função, que analisa as rotas e retorna um mapeamento com o mesmo formato. Todas as APIs voltadas para o desenvolvedor, como geração de URL ou correspondência de rotas, aceitarão rotas analisadas e não brutas. defineRoutes const routes = defineRoutes({ login: '/login', user: { me: '/user/me', byId: '/user/:id/info', } }); A próxima etapa é passar as rotas analisadas para a função . Esta é a essência do nosso roteador. Esta função criará todas as funções, ganchos e componentes. Isso pode parecer incomum, mas tal estrutura nos permite adaptar os tipos de argumentos e adereços aceitos a um conjunto específico de rotas definidas em , garantindo a segurança de tipo (e melhorando o DX). createRouter routes const { Link, Route, useCurrentRoute, navigate, /* etc... */ } = createRouter(routes); retornará funções que podem ser usadas em qualquer lugar do seu aplicativo (API imperativa), ganchos que permitem que seus componentes reajam às mudanças de localização e três componentes: , e . Isso será suficiente para cobrir a maioria dos casos de uso, e você poderá construir seus próprios componentes com base nessas APIs. createRouter Link Route NotFound Programação de nível de tipo para diversão e lucro Começamos abordando a parte de segurança de tipografia do nosso argumento de venda. Como mencionei antes, com um roteador typesafe, o TypeScript irá avisá-lo com antecedência sobre uma situação como esta: Ou assim: const { userld } = useRoute(routes.user.byId); E se você não consegue ver imediatamente o que há de errado com eles, você definitivamente precisa de um roteador typesafe :) O sistema de tipos no TypeScript é muito poderoso. Quero dizer, você pode criar um , um ou até mesmo um usando programação em nível de tipo. mecanismo de xadrez jogo de aventura banco de dados SQL Você já está familiarizado com a 'programação em nível de valor', onde você manipula valores, por exemplo, concatenando duas strings: function concat(a, b) { return a + b; } concat('Hello, ', 'World!'); // 'Hello, World!' Mas você também pode fazer isso com tipos! type Concat = `${A}${B}`; type X = Concat ; // ^? type X = "Hello, World!" Sim, não é tão poderoso quanto suas funções normais e parece diferente. Mas permite que você faça coisas muito legais e úteis. Usaremos programação em nível de tipo para extrair parâmetros de rotas brutas e construir novos tipos que possam verificar se o desenvolvedor não tenta passar valores incorretos para ou para a função que está construindo a URL. Link A programação em nível de tipo com TS pode rapidamente se tornar uma bagunça ilegível. Felizmente para nós, já existem vários projetos que escondem toda essa complexidade e nos permitem escrever código limpo como este: export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; Muito legal, hein? A propósito, esse é todo o código que você precisa para analisar os parâmetros da rota bruta. Neste projeto, usaremos a biblioteca - ela nos ajudará a reduzir a complexidade e a quantidade de código em nível de tipo. hotscript Mas não é obrigatório: se você se sente aventureiro, pode tentar implementar todos esses tipos sozinho. Você pode encontrar alguma inspiração no , que implementa recursos semelhantes sem usar bibliotecas de tipos de terceiros. roteador Chicane Se você quiser acompanhar, recomendo que você crie um novo projeto React usando seu starter favorito (eu uso ) e comece a codificar lá. Dessa forma, você poderá testar seu roteador imediatamente. Vite Observe que estruturas como Next.js fornecem seu próprio roteamento que pode interferir neste projeto e, em vez disso, use React 'vanilla'. Caso tenha alguma dificuldade, você pode encontrar o código completo . aqui Comece instalando pacotes de terceiros: para utilitários de nível de tipo e para analisar parâmetros de URL/rota bruta. hotscript regexparam npm install hotscript regexparam O primeiro tijolo de construção de nossos tipos é a rota bruta. A rota bruta deve começar com ; como você codificaria isso em TS? Assim: / export type RawRoute = `/${string}`; Fácil, certo? Mas não aceita uma única rota bruta, aceita mapeamento, possivelmente aninhado, então vamos codificar isso. Você pode ficar tentado a escrever algo assim: defineRoutes export type RawRoutesMap = { [key: string]: RawRoute | RawRoutesMap }; Isso funcionará. No entanto, esse tipo pode ser infinitamente profundo e o TS terá dificuldade em calculá-lo em alguns casos. Para facilitar a vida do TS, limitaremos o nível de aninhamento permitido. 20 níveis de aninhamento devem ser suficientes para todos os aplicativos e o TS pode lidar com isso facilmente. Mas como limitar a profundidade dos tipos recursivos? Aprendi esse truque com esta ; aqui está uma versão modificada para nossos requisitos: resposta do SO export type RecursiveMap = { [key: string]: RecursiveMap_ ; }; type RecursiveMap_ = MaxDepth extends Stack["length"] ? T : T | { [key: string]: RecursiveMap_ }; Este é o nosso primeiro tipo complexo, então deixe-me explicar. Temos dois tipos aqui: funciona como um ponto de entrada e chama passando um parâmetro de tupla adicional. Esta tupla é usada para rastrear a profundidade do mapeamento, a cada chamada adicionamos um elemento a este array. RecursiveMap RecursiveMap_ E continuamos a chamá-lo até que o comprimento desta tupla seja igual a . No TS, quando é usado com valores , também chamados de literais (por exemplo, especificamente , não ), significa 'igual'. MaxDepth extends específicos 42 number E como e são números específicos, esse código pode ser lido como . Você verá essa construção sendo muito utilizada. MaxDepth Stack["length"] MaxDepth === Stack["length"] Por que usar tupla em vez de apenas somar números? Bem, não é tão fácil adicionar dois números no TypeScript! Existe para isso, e o Hotscript também pode adicionar números, mas requer muito código (mesmo que você não o veja), o que pode tornar lento o servidor TS e o editor de código se usado excessivamente. uma biblioteca inteira Portanto, minha regra é evitar tipos complexos tanto quanto razoavelmente possível. Com este tipo de utilitário, podemos definir nosso mapeamento tão simples quanto: export type RawRoutesMap = RecursiveMap ; Isso é tudo para tipos de rotas brutas. O próximo na fila é a rota analisada. A rota analisada é apenas um objeto JavaScript com alguns campos adicionais e uma função; aqui está como parece: export type ParsedRoute = { keys: RouteParam []; build(...params: PathConstructorParams ): Path ; raw: R; ambiguousness: number, pattern: RegExp; }; Vamos começar a descompactar isso no campo . É simplesmente uma série de parâmetros necessários para esta rota. Aqui está como isso é feito: keys import { Pipe, Strings, Tuples } from "hotscript"; export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; No Hotscript, existem duas maneiras de chamar uma função: ou . é útil quando você precisa chamar uma única função, mas no nosso caso temos 4 delas! aceita entrada e, bem, canaliza-a para a primeira função de uma tupla fornecida. Call Pipe Call Pipe O valor retornado é passado como entrada para a segunda função e assim por diante. No nosso caso, se tivéssemos, por exemplo, rota bruta , ela seria transformada assim: /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? Esta é a magia da programação em nível de tipo! Agora, vamos abordar essa função . Ele aceita parâmetros de rota (como e ) e parâmetros/hash de pesquisa opcionais e os combina em um caminho. Dê uma olhada em uma implementação de : 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]; Os parâmetros da função são definidos como um array (que é posteriormente ... espalhado na definição do função ), onde o primeiro elemento é e o segundo é opcional . Que tal retornar o valor de ? Já estabelecemos seu caminho, mas como descrevê-lo com TypeScript? build RouteParamsMap SearchAndHashPathConstructorParams build Bem, este é bastante semelhante ao , mas requer um pouco mais de ginástica do tipo! 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}`; O que fazemos aqui é dividir nossa rota em segmentos, mapear cada segmento e chamar nossa função personalizada em cada um. Ele verifica se o segmento atual é um parâmetro e o substitui por ou retorna o segmento como está. A 'função' pode parecer um pouco estranha, mas é assim que você define funções personalizadas com Hotscript. ReplaceParam string ReplaceParam Afirmamos explicitamente que o caminho consiste apenas em caminho, caminho seguido por um ponto de interrogação (isso abrange URLs com parâmetros de pesquisa e hash) ou um símbolo de hash (isso abrange URLs sem parâmetros de pesquisa, mas com hash). Também precisaremos de um tipo para descrever a rota correspondente, ou seja, rota analisada com parâmetros capturados da 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 , } O último tipo é ; é semelhante a , mas para rotas analisadas. 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; }; E com essa nota, terminamos com os tipos. Haverá mais alguns, mas são mais simples e iremos abordá-los à medida que avançamos na implementação. Se a programação em nível de tipo é algo que você gostaria de experimentar mais, você pode conferir para aprender mais e tentar resolver (eles também têm uma boa ). Typescript em nível de tipo desafios de tipo lista de recursos Analisador de rota Finalmente, voltamos à codificação normal em nível de valor. Vamos dar o pontapé inicial 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 complexo aqui; vamos nos aprofundar na função . 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; }; também é muito simples, embora visivelmente mais longo. Para analisar a rota e extrair parâmetros, usamos a biblioteca . Ele nos permite obter uma matriz de parâmetros necessários para a rota e gera uma expressão regular que usaremos mais tarde para combinar a URL com a rota. parseRoute regexparam Armazenamos essas informações junto com a rota bruta original usada para construir esse objeto e o nível de ambiguidade (que é apenas uma série de parâmetros na rota). Invólucro de histórico Todo roteador precisa armazenar seu estado em algum lugar. No caso de aplicativos no navegador, isso se resume a 4 opções: na memória (seja em uma variável de estado dentro do componente raiz ou em uma variável fora da árvore de componentes), API de histórico ou parte hash da URL. O roteamento na memória pode ser sua escolha se você não quiser mostrar ao usuário que possui rotas, por exemplo, se estiver codificando um jogo no React. Armazenar a rota em hash pode ser útil quando seu aplicativo React é apenas uma página em um aplicativo maior e você não pode simplesmente alterar a URL como quiser. Mas, na maioria dos casos, usar a API History será a melhor opção. É compatível com SSR (outras opções não são), segue padrões de comportamento aos quais o usuário está acostumado e parece mais limpo. Neste projeto, iremos usá-lo também. Porém, ele tem uma falha notável: é praticamente inutilizável sem invólucros adicionais. Com o History AP, você pode se inscrever no evento e o navegador avisará quando o URL for alterado. Mas somente se a alteração for iniciada pelo usuário, por exemplo, clicando no botão Voltar. Se uma alteração de URL for iniciada a partir do código, você mesmo precisará controlá-la. popstate A maioria dos roteadores que estudei usa seu próprio wrapper: react-router e chicane usam o pacote NPM , o roteador TanStack tem sua e o wouter não tem um wrapper completo, mas ainda precisa . de histórico própria implementação corrigir o histórico Então, vamos implementar nosso próprio wrapper. 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... */; }; Existem dois tipos que usaremos, e . Primeiro, é uma versão um pouco limitada do tipo integrado (esse é o tipo de ), e o segundo será abordado quando chegarmos ao bloqueio de navegação. Todo o código adicional deste capítulo irá para dentro da função . HistoryLocation NavigationBlocker Location window.location createHistory Vamos começar implementando uma assinatura para alterações no histórico. Usaremos funções estilo React para assinatura neste projeto: você chama passando um retorno de chamada e ele retorna outra função que você precisa chamar quando quiser cancelar a assinatura. 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); }; }; A próxima etapa é reagir às alterações de localização, incluindo alterações feitas programaticamente. Como você faria? Com , é claro. Isso pode parecer um pouco sujo (e realmente é), mas infelizmente não temos opções melhores. patch de macaco 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); E a última grande peça que falta em nossa implementação de histórico é o bloqueio de navegação: um recurso que permite interceptar a solicitação de navegação e cancelá-la condicionalmente. Um exemplo canônico de bloqueio de navegação seria evitar que o usuário perdesse o progresso em um formulário. 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 }); } } }; Em nossa implementação, um bloqueador é uma função que retorna um booleano indicando se precisamos bloquear esta navegação. No que diz respeito ao bloqueio de navegação, existem dois tipos de navegação e precisaremos tratá-los de forma diferente. Por um lado, existe a navegação suave - quando o usuário navega de uma página do nosso aplicativo para outra página do nosso aplicativo. Nós o controlamos totalmente e, portanto, podemos bloqueá-lo, exibir qualquer UI personalizada (para confirmar a intenção do usuário) ou realizar ações após bloquear a navegação. Por outro lado, há uma navegação difícil – quando o usuário navega para outro site ou fecha totalmente a aba. O navegador não pode permitir que o JavaScript decida se esta navegação deve ser realizada, pois isso será uma preocupação de segurança. Mas o navegador permite que o JavaScript indique se queremos mostrar uma caixa de diálogo de confirmação extra ao usuário. Ao bloquear a navegação suave, você pode querer exibir uma interface de usuário adicional (por exemplo, caixa de diálogo de confirmação personalizada), mas no caso de navegação difícil, isso realmente não faz sentido, pois o usuário só a verá se decidir permanecer na página e , nesse ponto, é inútil e confuso. Quando nosso histórico chamar a função de bloqueador de navegação, ele fornecerá um booleano, indicando se estamos realizando uma navegação suave. E com tudo isso, só precisamos retornar nosso objeto histórico: 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, }; Etapa 1: API imperativa Finalmente estamos aqui. A API Imperative será a base para todos os outros ganchos e componentes e permitirá ao desenvolvedor construir ganchos personalizados para atender às suas necessidades. Primeiro de tudo, precisamos transformar nosso mapa de rotas em um array plano. Dessa forma, será muito mais fácil percorrer todas as rotas, o que será útil quando começarmos a trabalhar na parte de correspondência de rotas. Precisamos do tipo utility (que transformará na união de ) e function (que transformará em uma matriz de rotas analisadas). Vamos começar com o 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 >; Pode parecer desnecessário dividir isso em dois tipos, mas há uma razão muito importante para isso: se você implementá-lo como um tipo único que chama a si mesmo, o TS reclamará que o tipo é excessivamente profundo e possivelmente infinito. Então, contornamos isso dividindo-o em dois tipos que se chamam. Para uma função de nível de valor, também precisaremos de um protetor de tipo para verificar se o valor passado é uma rota analisada. 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 ); }); }; Agora, vamos começar a implementar nosso roteador. Assim como na história, neste e nos próximos dois capítulos, todo o código irá para a função , salvo indicação em contrário. 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); }; Primeiro de tudo, vamos ensinar nosso roteador a combinar a localização atual com uma das rotas conhecidas. Alguns utilitários podem entrar no escopo global ou em arquivos separados, não dentro da função : 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 { }; E esse código vai para a função . 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; Aqui examinamos todas as rotas conhecidas e tentamos combinar cada uma com a localização atual. Se o regex da rota corresponder a URL - obtemos parâmetros de rota de URL, caso contrário, obtemos . Para cada rota correspondente, criamos um objeto e o salvamos em um array. Agora, se tivermos 0 ou 1 rotas correspondentes, tudo é simples. null RouteWithParams Contudo, se mais de uma rota corresponder à localização atual, temos que decidir qual delas tem maior prioridade. Para resolver isso, usamos o campo . Como você deve se lembrar, essa rota possui vários parâmetros, e uma rota com a menor é priorizada. ambiguousness ambiguousness Por exemplo, se tivéssemos duas rotas e , a localização corresponderia a ambas as rotas. Mas é bastante óbvio que esse URL deve corresponder a route, não . /app/dashboard /app/:section http://example.com/app/dashboard /app/dashboard /app/:section Este algoritmo não é à prova de balas. Por exemplo, as rotas e corresponderão ao URL . E como possuem o mesmo nível de ambiguidade, nosso roteador não conseguirá decidir qual deles deve ser priorizado. /app/:user/settings/:section /app/dashboard/:section/:region http://example.com/app/dashboard/settings/asia Agora, precisamos unir esse código para reagir às mudanças de localização e atualizar a variável ; 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 } }); Agora, nosso roteador reage às mudanças de localização, e o usuário sempre pode obter a rota atual, sim! Mas não é muito útil sem a capacidade de assinar alterações de rota, então vamos adicionar isso. A abordagem é muito semelhante àquela que usamos no wrapper de 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 a navegação, exporemos as funções e , que são um wrapper simples em torno de e : 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); }; Bem, isso é um roteador de verdade! Muito básico, mas funcionando mesmo assim. Ainda temos alguns ganchos e componentes para implementar, mas fica muito mais fácil a partir daqui. Etapa 2: ganchos Para ganchos, podemos começar com ganchos simples que retornam a localização atual e a rota atual. Eles são bastante fáceis por si só, mas os transforma em uma linha única. A maneira como projetamos nossa API imperativa anteriormente nos permitiu reduzir drasticamente o código desses ganchos. useSyncExternalStore const useLocation = () => { return useSyncExternalStore(history.subscribe, history.getLocation); }; const useCurrentRoute = () => { return useSyncExternalStore(subscribe, getCurrentRoute); }; Ao codificar componentes que devem ser renderizados apenas em uma rota/conjunto de rotas específico, você pode usar para obter a rota atual, verificar se ela corresponde aos critérios e então usar seus parâmetros (ou gerar um erro). useCurrentRoute Mas esta é uma tarefa tão comum que será um crime fazer com que nossos usuários escrevam seus próprios ganchos para isso - nosso roteador deve fornecer isso imediatamente. 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 tem duas versões: rigoroso e descontraído. Se o usuário passar como segundo parâmetro (ou não passar nada, já que é o valor padrão), esse gancho gerará um erro se a rota atual não corresponder a um dos filtros fornecidos. true true Dessa forma, você pode ter certeza de que o gancho retornará uma rota correspondente ou nem retornará. Se o segundo parâmetro for falso, em vez de lançar uma exceção, o gancho simplesmente retornará indefinido se a rota atual não corresponder aos filtros. Para descrever esse comportamento para TypeScript, usamos um recurso chamado . Isso nos permite definir múltiplas definições de funções com tipos diferentes, e o TypeScript escolherá automaticamente uma para ser usada quando o usuário chamar tal função. sobrecarga de função Além dos parâmetros de caminho, alguns dados podem ser passados em parâmetros de pesquisa, então vamos adicionar um gancho para analisá-los da string para o mapeamento. Para isso, usaremos a API integrada do navegador . URLSearchParams const useSearchParams = () => { const location = useLocation(); return useMemo(() => { return Object.fromEntries( (new URLSearchParams(location.search)).entries() ); }, [location.search]); }; E o último gancho nesta seção é que também é bastante simples: ele apenas aceitará retorno de chamada e agrupará chamadas para em um efeito, para anexar novamente o bloqueador se ele mudar. useNavigationBlocker history.addBlocker const useNavigationBlocker = (cb: NavigationBlocker) => { useEffect(() => { return history.addBlocker(cb); }, [cb]); }; Agora, vamos pular para os componentes! Etapa 3: Componentes Qual é o primeiro componente que vem à mente ao mencionar bibliotecas de roteamento? Aposto que é ou, pelo menos, algo parecido. Como você viu anteriormente, nossos ganchos eram muito simples devido a uma API imperativa bem projetada que faz todo o trabalho pesado. Route O mesmo vale para componentes; eles podem ser facilmente implementados pelo usuário em poucas linhas de código. Mas somos uma biblioteca séria de roteamento por aí, vamos incluir baterias na caixa :) type RouteProps = { component: ComponentType, match: RouteFilter }; const Route = ({ component: Component, match }: RouteProps) => { const matchedRoute = useRoute(match, false); if (!matchedRoute) return null; return ( ); }; Bem, isso foi fácil! Quer adivinhar como implementamos o componente ? :) NotFound type NotFoundProps = { component: ComponentType }; const NotFound = ({ component: Component }: NotFoundProps) => { const currentRoute = useCurrentRoute(); if (currentRoute) return null; return ( ); }; E o último componente necessário para o nosso roteador é , que é um pouco mais complicado. Você não pode simplesmente usar pois ele sempre iniciará uma navegação difícil e não fornece nenhuma segurança de tipo. Então, vamos abordar estas questões: 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 }; Da mesma forma que a função , o componente verifica o tipo da URL que você passa para ele, mas também permite fornecer uma URL de string arbitrária (como uma saída de escape ou para links externos). Para substituir o comportamento de , anexamos nosso próprio ouvinte , dentro do qual precisaremos chamar o original (passado para nosso componente ). navigate Link onClick onClick Link Depois disso, verificamos se a navegação já não foi abortada pelo desenvolvedor (se foi, devemos ignorar o evento). Se tudo estiver bem, verificamos se o link não é externo e se deve estar aberto na aba atual. E só então poderemos cancelar a navegação rígida integrada e, em vez disso, chamar nossa própria função . navigateUnsafe E agora, só precisamos retornar todas as nossas funções, ganchos e componentes (junto com algumas funções reexportadas diretamente do histórico) da função . 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, }; E com isso, nosso roteador está pronto. Agora, podemos construir nosso pequeno aplicativo para mostrar nosso minúsculo roteador que acabamos de fazer! A propósito, você pode encontrar o código completo deste roteador (incluindo o código de um aplicativo de exemplo) . aqui Juntando as peças do quebra-cabeça Então, como todo esse código se interliga? Muito bem, se é que posso dizer! Imagine que você está criando um aplicativo de anotações. Primeiramente, você começaria definindo as rotas e criando um roteador 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; E então, você vincula as rotas definidas aos componentes da página: function App() { return ( {/* This is how you build URL for Link */} View all notes Create new ) } Quando estiver em , você precisa obter um ID de nota do URL, então use um gancho : 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 ); }; E ao criar uma nova nota, você provavelmente gostaria de confirmar a intenção do usuário se ele sair sem salvar a 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 ; }; Possíveis melhorias Embora nosso roteador realmente faça o roteamento, ele não é páreo para soluções prontas para produção, como roteador TanStack, roteador react ou roteador Next.js. Quero dizer, são apenas cerca de 500 linhas de código, isso não é muito. Mas o que exatamente está faltando? Primeiro de tudo, renderização no lado do servidor. Hoje, nem todos os aplicativos podem precisar de SSR, mas espera-se que todas as bibliotecas de roteamento o suportem. Adicionar renderização do lado do servidor em uma string (não transmitir SSR!) Envolverá a criação de um diferente que armazenará a localização atual na memória (já que não há API de histórico no servidor) e conectará isso à função . history createRouter Não estou ciente de quão difícil será implementar o SSR de streaming, mas presumo que estará fortemente conectado com o suporte do Suspense. Em segundo lugar, este roteador não se integra bem à renderização simultânea. Principalmente por causa do uso de , pois não é compatível com . Funciona desta forma para evitar tearing: uma situação em que uma parte da UI foi renderizada com um valor armazenado específico, mas o resto da UI é renderizado com um valor diferente. useSyncExternalStore transições sem bloqueio E por causa disso, o roteador não se integra bem ao Suspense, pois para cada atualização de localização suspensa, um fallback será mostrado. A propósito, abordei simultaneidade no React neste , e , falo sobre Suspense, busca de dados e de gancho. artigo neste use Mas mesmo com essas desvantagens, espero que você tenha achado este artigo interessante e construído seu próprio roteador ao longo do caminho :)