{"id":13496333,"url":"https://github.com/zilch/type-route","last_synced_at":"2025-03-28T18:31:57.611Z","repository":{"id":42535219,"uuid":"179408313","full_name":"zilch/type-route","owner":"zilch","description":"The flexible, type safe routing library.","archived":false,"fork":false,"pushed_at":"2024-03-14T04:33:29.000Z","size":19417,"stargazers_count":428,"open_issues_count":17,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-08T04:02:16.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://type-route.zilch.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zilch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-04T02:41:04.000Z","updated_at":"2024-12-17T07:13:38.000Z","dependencies_parsed_at":"2024-01-06T07:58:28.710Z","dependency_job_id":"56a03435-9eb8-4b82-9a24-fe1630fd1329","html_url":"https://github.com/zilch/type-route","commit_stats":{"total_commits":327,"total_committers":13,"mean_commits":"25.153846153846153","dds":0.6452599388379205,"last_synced_commit":"d1f9a3fe9727a5158bef70f2521c5d9b2676ab8d"},"previous_names":["typehero/type-route"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilch%2Ftype-route","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilch%2Ftype-route/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilch%2Ftype-route/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilch%2Ftype-route/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zilch","download_url":"https://codeload.github.com/zilch/type-route/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246080706,"owners_count":20720574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:46.172Z","updated_at":"2025-03-28T18:31:55.465Z","avatar_url":"https://github.com/zilch.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://type-route.zilch.dev\"\u003e\n    \u003cimg src=\"https://type-route.zilch.dev/logo.svg\" width=\"200\" alt=\"Type Route\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n\u003ch1 align=\"center\"\u003eType Route\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"#getting-started\"\u003eQuick Start\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"https://type-route.zilch.dev\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n\n## Getting Started\n\nType Route is a flexible, type safe routing library built on top of the same [core library](https://github.com/ReactTraining/history) that powers React Router.\n\n\u003e **Type Route was designed with excellent React integration in mind** but isn't coupled to a specific UI framework. Most code examples in the documentation use React, but the general principles covered apply regardless of framework.\n\nContinue reading this introduction for a quick overview of how to start using Type Route in your React project. Find a full \u003cb\u003erunnable\u003c/b\u003e version of the below introduction on the [Simple React Example](https://type-route.zilch.dev/introduction/simple-react-example) page or see the [Type Route without React](https://type-route.zilch.dev/guides/type-route-without-react) guide to learn how to use Type Route without React.\n\n## Install\n\nType Route's primary distribution channel is the [NPM registry](https://www.npmjs.com/package/type-route). React `16.8` (or any subsequent version of React) is a peer dependency of Type Route so you'll need to ensure that's installed as well.\n\n```bash\nnpm install type-route react\n```\n\n## Step 1: Create a Router\n\n`router.ts`\n\n```typescript\nimport { createRouter, defineRoute, param } from \"type-route\";\n\nexport const { RouteProvider, useRoute, routes } = createRouter({\n  home: defineRoute(\"/\"),\n  userList: defineRoute(\n    {\n      page: param.query.optional.number,\n    },\n    () =\u003e \"/user\"\n  ),\n  user: defineRoute(\n    {\n      userId: param.path.string,\n    },\n    (p) =\u003e `/user/${p.userId}`\n  ),\n});\n```\n\nBest practice is to immediately destructure the result of [`createRouter`](https://type-route.zilch.dev/api-reference/router/create-router) into the properties you'll be using in your application. The [`createRouter`](https://type-route.zilch.dev/api-reference/router/create-router) function accepts an object with route names and route definitions created via [`defineRoute`](https://type-route.zilch.dev/api-reference/route-definition/define-route) and returns a new router.\n\n## Step 2: Connect Router to Application\n\n`App.tsx`\n\n```tsx {17-19}\nimport React, { useState, useEffect } from \"react\";\nimport ReactDOM from \"react-dom\";\nimport { RouteProvider } from \"./router\";\nimport { Page } from \"./Page\";\nimport { Navigation } from \"./Navigation\";\n\nfunction App() {\n  return (\n    \u003c\u003e\n      \u003cNavigation /\u003e\n      \u003cPage /\u003e\n    \u003c/\u003e\n  );\n}\n\nReactDOM.render(\n  \u003cRouteProvider\u003e\n    \u003cApp /\u003e\n  \u003c/RouteProvider\u003e,\n  document.querySelector(\"#root\")\n);\n```\n\nWrap your entire application in the `\u003cRouteProvider\u003e` component returned by [`createRouter`](https://type-route.zilch.dev/api-reference/router/create-router).\n\n## Step 3: Display Current Route\n\n`Page.tsx`\n\n```tsx\nimport React from \"react\";\nimport { useRoute, routes } from \"./router\";\nimport { HomePage } from \"./HomePage\";\nimport { UserListPage } from \"./UserListPage\";\nimport { UserPage } from \"./UserPage\";\nimport type { Route } from \"type-route\";\n\nexport function Page() {\n  const route = useRoute();\n\n  return (\n    \u003c\u003e\n      {route.name === \"home\" \u0026\u0026 \u003cHomePage /\u003e}\n      {route.name === \"userList\" \u0026\u0026 \u003cUserListPage route={route} /\u003e}\n      {route.name === \"user\" \u0026\u0026 \u003cUserPage route={route} /\u003e}\n      {route.name === false \u0026\u0026 \"Not Found\"}\n    \u003c/\u003e\n  );\n}\n\nfunction HomePage() {\n  return \u003cdiv\u003eHome Page\u003c/div\u003e;\n}\n\nfunction UserListPage({ route }: { route: Route\u003ctypeof routes.userList\u003e }) {\n  return \u003cdiv\u003eUserList Page: {route.params.page}\u003c/div\u003e;\n}\n\nfunction UserPage({ route }: { route: Route\u003ctypeof routes.user\u003e }) {\n  return \u003cdiv\u003eUser: {route.params.userId}\u003c/div\u003e;\n}\n```\n\nInside the code blocks above the TypeScript compiler (and your editor) will be able to correctly infer the type of `route`. This allows you, for instance, to pass the `user` route to the `UserPage` component and access the `userId` param with confidence in code blocks where it will definitely exist.\n\n\u003e Type Route is written in TypeScript and designed for TypeScript users. Any editor, however, whose JavaScript experience is powered by TypeScript (VSCode for instance) will provide many of the same benefits described here when using regular JavaScript.\n\n## Step 4: Navigate Between Routes\n\n`Navigation.tsx`\n\n```tsx\nimport React from \"react\";\nimport { routes } from \"./router\";\n\nexport function Navigation() {\n  return (\n    \u003cnav\u003e\n      \u003ca {...routes.home().link}\u003eHome\u003c/a\u003e\n      \u003ca {...routes.userList().link}\u003eUser List\u003c/a\u003e\n      \u003ca {...routes.userList({ page: 2 }).link}\u003eUser List Page 2\u003c/a\u003e\n      \u003ca {...routes.user({ userId: \"abc\" }).link}\u003eUser \"abc\"\u003c/a\u003e\n    \u003c/nav\u003e\n  );\n}\n```\n\nThe [`link`](https://type-route.zilch.dev/api-reference/route/link) property is an object with an `href` attribute and an `onClick` function. You need both to [properly render](https://type-route.zilch.dev/guides/rendering-links) a link in a single page application. Immediately spreading the `link` object into the properties of an `\u003ca\u003e` tag makes usage simple. [Programmatic navigation](https://type-route.zilch.dev/guides/programmatic-navigation) is possible with the [`push`](https://type-route.zilch.dev/api-reference/route/push) and [`replace`](https://type-route.zilch.dev/api-reference/route/replace) functions of a specific route. Type Route also supports [extending the behavior of a link](https://type-route.zilch.dev/guides/custom-link-behavior) to cover more complex scenarios.\n\n## Next Steps\n\nHopefully that was enough to point you in the right direction!\n\nIf you need more guidance there is a full runnable version of the above code on the [Simple React Example](https://type-route.zilch.dev/introduction/simple-react-example) page. The **Guides** section of the documentation has detailed overviews and examples for most use cases. Additionally, the **API Reference** section has descriptions and examples for each part of the API.\n\n[View Docs →](https://type-route.zilch.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilch%2Ftype-route","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzilch%2Ftype-route","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilch%2Ftype-route/lists"}