\n \n\n# Generouted\n\nGenerated file-based routes for [Vite](https://vitejs.dev)\n\n\nMotivation\n\n \n\nI enjoyed using file-based routing since I tried Next.js (pages directory). After applying the same concept with Vite and client-side applications, I started writing blog posts covering the implementation of [client-side file-based routing with React Router](https://omarelhawary.me/blog/file-based-routing-with-react-router) which was packaged later as `generouted`.\n\nToday `generouted` brings many features, supports multiple frameworks and routers, and inspires ideas and conventions from Next.js, Remix, Expo, Docusaurus, SvelteKit and more.\n\n \n\n\n\n\nHow does it work?\n\n \n\n`generouted` uses [Vite's glob import API](https://vitejs.dev/guide/features.html#glob-import) to list the routes within the `src/pages` directory and generates the routes tree and modals based on `generouted`'s conventions.\n\nThere are also Vite plugins available for some integrations to provide type-safe components/hooks/utils through code-generation.\n\n \n\n\n\n \n\n## Features\n\n- ๐ Client-side file-based routing\n- โก Powered by [Vite](https://vitejs.dev)\n- โจ React support with [`react-router`](https://github.com/remix-run/react-router) or [`@tanstack/router`](https://github.com/tanstack/router) ๐งช or [`@tanstack/react-location`](https://github.com/tanstack/router/tree/9c8eb043e4ac350fc1d28655542e01defb0c82e5) ๐จ\n- โจ Solid support with [`@solidjs/router`](https://github.com/solidjs/solid-router)\n- โจ File-based MDX routes with React or Solid, requires [`@mdx-js/rollup`](https://mdxjs.com/packages/rollup) [installation and setup](/examples/react-router-mdx)\n- ๐ Type-safe navigation\n- ๐ Type-safe global modals\n- ๐ค Route-based code-splitting and lazy-loading\n- ๐ Route-based data loaders and actions\n- ๐ฃ Route-based error boundary\n- ๐ Nested layouts\n- ๐ซ Pathless layout groups\n- โ Optional static and dynamic routes\n- ๐ญ Ignored routes per file or directory\n\n \n\n## Online explorer\n\n- โก Visit [`generouted`'s interactive playground via StackBlitz](https://stackblitz.com/github.com/oedotme/generouted/tree/main/explorer)\n- ๐งฉ Explore file-based routing patterns and conventions\n- ๐ Visualize the routes layouts and the resolved routes paths\n- ๐ Update `src/pages/` files and see your changes reflecting\n\n \n\n## Getting started\n\n\nReact Router\n\n### React Router\n\nIn case you don't have a Vite project with React and TypeScript, check [Vite documentation to start a new project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).\n\n#### Installation\n\n```shell\npnpm add @generouted/react-router react-router\n```\n\n#### Setup\n\n```ts\n// vite.config.ts\n\nimport { defineConfig } from 'vite'\nimport react from '@vitejs/plugin-react'\nimport generouted from '@generouted/react-router/plugin'\n\nexport default defineConfig({ plugins: [react(), generouted()] })\n```\n\n#### Usage\n\n```tsx\n// src/main.tsx\n\nimport { createRoot } from 'react-dom/client'\nimport { Routes } from '@generouted/react-router'\n\ncreateRoot(document.getElementById('root')!).render()\n```\n\n#### Adding pages\n\nAdd the home page by creating a new file `src/pages/index.tsx` โ `/`, then export a default component:\n\n```tsx\nexport default function Home() {\n return
Home
\n}\n```\n\nCheck the [routing conventions section below](#conventions).\n\n#### Docs\n\nYou can find more details about type-safe navigation and global modals at [`@generouted/react-router` docs](/packages/react-router).\n\n#### Examples\n\n- [Type-safe navigation + global modals](/examples/react-router)\n- [Custom integration](/examples/react-router-custom)\n- [Custom integration with custom path](/examples/react-router-custom-path)\n- [MDX routes](/examples/react-router-mdx)\n\n \n\n\n\n\nSolid Router\n\n### Solid Router\n\nIn case you don't have a Vite project with Solid and TypeScript, check [Vite documentation to start a new project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).\n\n#### Installation\n\n```shell\npnpm add @generouted/solid-router @solidjs/router\n```\n\n#### Setup\n\n```ts\n// vite.config.ts\n\nimport { defineConfig } from 'vite'\nimport solid from 'vite-plugin-solid'\nimport generouted from '@generouted/solid-router/plugin'\n\nexport default defineConfig({ plugins: [solid(), generouted()] })\n```\n\n#### Usage\n\n```tsx\n// src/main.tsx\n\nimport { render } from 'solid-js/web'\nimport { Routes } from '@generouted/solid-router'\n\nrender(Routes, document.getElementById('root')!)\n```\n\n#### Adding pages\n\nAdd the home page by creating a new file `src/pages/index.tsx` โ `/`, then export a default component:\n\n```tsx\nexport default function Home() {\n return
Home
\n}\n```\n\nSee more about `generouted` [routing conventions below](#conventions).\n\n#### Docs\n\nYou can find more details about type-safe navigation and global modals at [`@generouted/solid-router` docs](/packages/solid-router).\n\n#### Examples\n\n- [Type-safe navigation + global modals](/examples/solid-router)\n\n \n\n\n\n\nTanStack React Router โ In-progress experimental support ๐งช\n\n### TanStack React Router โ In-progress experimental support ๐งช\n\n[Check out the docs here](/packages/tanstack-react-router)\n\n#### Examples\n\n- [Basic](/examples/tanstack-react-router)\n\n \n\n\n\n\nReact Location โ Deprecated ๐จ\n\n### React Location โ Deprecated ๐จ\n\nIn case you don't have a Vite project with React and TypeScript, check [Vite documentation to start a new project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).\n\n#### Installation\n\n```shell\npnpm add generouted @tanstack/react-location\n```\n\n#### Usage\n\n```tsx\n// src/main.tsx\n\nimport { createRoot } from 'react-dom/client'\nimport { Routes } from 'generouted/react-location'\n\ncreateRoot(document.getElementById('root')!).render()\n```\n\n#### Adding pages\n\nAdd the home page by creating a new file `src/pages/index.tsx` โ `/`, then export a default component:\n\n```tsx\nexport default function Home() {\n return
Home
\n}\n```\n\n#### Examples\n\n- [Basic](/examples/react-location/basic)\n- [Data loaders](/examples/react-location/data-loaders)\n- [Modals](/examples/react-location/modals)\n- [Nested layouts](/examples/react-location/nested-layouts)\n\n \n\n\n\n \n\n## Conventions\n\n### File and directories naming and conventions\n\n- Routes declaration at `src/pages`\n- Supports `.tsx`, `.jsx` and `.mdx` file extensions\n- Optional `src/pages/_app.tsx` for an **app level layout**\n- Optional `src/pages/404.tsx` for a **custom not-found page**\n\n#### Index routes\n\n- `src/pages/index.tsx` โ `/`\n- `src/pages/posts/index.tsx` โ `/posts`\n\n#### Nested routes\n\n- `src/pages/posts/2022/index.tsx` โ `/posts/2022`\n- `src/pages/posts/2022/resolutions.tsx` โ `/posts/2022/resolutions`\n\n#### Dynamic routes\n\n- `src/pages/posts/[slug].tsx` โ `/posts/:slug`\n- `src/pages/posts/[slug]/tags.tsx` โ `/posts/:slug/tags`\n- `src/pages/posts/[...all].tsx` โ `/posts/*`\n\n#### Nested layouts\n\n- By defining `_layout.tsx` in any nested directory โ `src/pages/posts/_layout.tsx`\n- **Requires** using an `` component to render layout children\n- All the files within the `src/pages/posts/` directory in this case, will be wrapped with that layout\n\n#### Nested URLs without nested layouts\n\n- Route file should be outside of the nested layout directory\n- Include **dots** `.` between the segments to be converted to forward slashes\n- `src/pages/posts.nested.as.url.not.layout.tsx` โ `/posts/nested/as/url/not/layout`\n\n#### Pathless layouts\n\n- Similar to nested layouts for layout definition\n- By wrapping the parent directory with **parentheses** `()`\n- `src/pages/(auth)/_layout.tsx`\n- `src/pages/(auth)/login.tsx` โ `/login`\n- Layout parent directory name is not included in the routes paths\n\n#### Global modals\n\n- By **prefixing** the file name with a **plus sign** `+` _(thinking the modal is an extra route overlaying the current route)_\n- Modals navigation available via the `useModals()` hook\n- `src/pages/+info.tsx` โ `/info`\n- `src/pages/+checkout/+details.tsx` โ `/checkout/details`\n- `src/pages/+checkout/+payment.tsx` โ `/checkout/payment`\n\n#### Optional segments\n\n- By **prefixing** a route segment with a **minus sign** `-` _(thinking the segment can be subtracted or removed from the route path)_\n- `src/pages/-en/about.tsx` โ `/en?/about` โ `/en/about`, `/about`\n- `src/pages/-[lang]/about.tsx` โ `/:lang?/about` โ `/en/about`, `/fr/about`, `/about`\n\n#### Ignored routes\n\n- Any directory or file starts with an **underscore** `_` will be **ignored**\n- `src/pages/_ignored.tsx`\n- `src/pages/posts/_components/button.tsx`\n- `src/pages/posts/_components/link.tsx`\n\n \n\n### Page exports\n\n- **Required** page component `export default Component() {...}`\n- Optional page loader function `export const Loader = () => {...}`\n- Optional page action function `export const Action = () => {...}`\n- Optional suspense-based pending component `export const Pending = () => {...}`\n- Optional error boundary component `export const Catch = () => {...}`\n\n \n\n### Example\n\n\nDirectory structure\n\n \n\n```shell\nsrc/pages\nโโโ (auth)\nโ โโโ _layout.tsx\nโ โโโ login.tsx\nโ โโโ register.tsx\nโโโ blog\nโ โโโ _components\nโ โ โโโ button.tsx\nโ โ โโโ comments.tsx\nโ โโโ [...all].tsx\nโ โโโ [slug].tsx\nโ โโโ _layout.tsx\nโ โโโ index.tsx\nโ โโโ tags.tsx\nโโโ docs\nโ โโโ -[lang]\nโ โ โโโ index.tsx\nโ โ โโโ resources.tsx\nโ โโโ -en\nโ โโโ contributors.tsx\nโโโ +info.tsx\nโโโ 404.tsx\nโโโ _app.tsx\nโโโ _ignored.tsx\nโโโ about.tsx\nโโโ blog.w.o.layout.tsx\nโโโ index.tsx\n```\n\n\n\n\nOverview\n\n \n\n| File | Path | Convention |\n| :------------------------------ | :----------------------- | :------------------------------------ |\n| `(auth)/_layout.tsx` | | Pathless Layout group |\n| `(auth)/login.tsx` | `/login` | Regular route |\n| `(auth)/register.tsx` | `/register` | Regular route |\n| `blog/_components/button.tsx` | | Ignored route by an ignored directory |\n| `blog/_components/comments.tsx` | | Ignored route by an ignored directory |\n| `blog/[...all].tsx` | `/blog/*` | Dynamic catch-all route |\n| `blog/[slug].tsx` | `/blog/:slug` | Dynamic route |\n| `blog/_layout.tsx` | | Layout for `/blog` routes |\n| `blog/index.tsx` | `/blog` | Index route |\n| `blog/tags.tsx` | `/blog/tags` | Regular route |\n| `docs/-[lang]/index.tsx` | `/docs/:lang?/index` | Optional dynamic route segment |\n| `docs/-[lang]/resources.tsx` | `/docs/:lang?/resources` | Optional dynamic route segment |\n| `docs/-en/contributors.tsx` | `/docs/en?/contributors` | Optional static route segment |\n| `+info.tsx` | `/info` | Modal route |\n| `404.tsx` | `*` | Custom `404` _(optional)_ |\n| `_app.tsx` | | Custom `app` layout _(optional)_ |\n| `_ignored.tsx` | | Ignored route |\n| `about.tsx` | `/about` | Regular route |\n| `blog.w.o.layout.tsx` | `/blog/w/o/layout` | Route without `/blog` layout |\n| `index.tsx` | `/` | Index route |\n\n\n\n \n\n## API\n\n### Routing\n\nVia [`@generouted/react-router`](/packages/react-router) or [`@generouted/solid-router`](/packages/solid-router)\n\n- `` โ file-based routing component to be render in the app entry\n- `routes` โ file-based routes tree/object used by default at `` component\n\n### Routing + code-splitting and lazy-loading\n\nVia `@generouted/react-router/lazy` or `@generouted/solid-router/lazy`\n\n- Used instead of `@generouted/react-router` or `@generouted/solid-router` to enable lazy-loading\n- Make sure to replace all imports to lazy imports โ namely at app entry and `src/pages/_app.tsx`\n- Provides the same `` and `routes` exports\n\n### Plugins\n\nVia `@generouted/react-router/plugin` or `@generouted/solid-router/plugin`\n\n- Vite plugin for type generation and initializing type-safe components/hooks/utils\n- Generates `src/router.ts` file\n- Exports type-safe ``, ``, `useModals()`, `useNavigate()`, `useParams()`, `redirect()`, etc.\n- Check out [`@generouted/react-router` docs](/packages/react-router) or [`@generouted/solid-router` docs](/packages/solid-router) for more details\n\n### Core\n\nVia `@generouted/react-router/core` or `@generouted/solid-router/core`\n\n- Available for customization, however it's recommended to use the available integrations directory via the `` component\n- Check out the [custom integration example](/examples/react-router-custom)\n\n \n\n## FAQ\n\n\nHow to implement protected or guarded routes?\n\n \n\nThere are multiple approaches to achieve that. If you prefer handling the logic in one place, you can define the protected routes with redirection handling within a component:\n\n```tsx\n// src/config/redirects.tsx\n\nimport { Navigate, useLocation } from 'react-router'\n\nimport { useAuth } from '../context/auth'\nimport { Path } from '../router'\n\nconst PRIVATE: Path[] = ['/logout']\nconst PUBLIC: Path[] = ['/login']\n\nexport const Redirects = ({ children }: { children: React.ReactNode }) => {\n const auth = useAuth()\n const location = useLocation()\n\n const authenticatedOnPublicPath = auth.active && PUBLIC.includes(location.pathname as Path)\n const unAuthenticatedOnPrivatePath = !auth.active && PRIVATE.includes(location.pathname as Path)\n\n if (authenticatedOnPublicPath) return \n if (unAuthenticatedOnPrivatePath) return \n\n return children\n}\n```\n\nThen use that component (`` ) at the root-level layout `src/pages/_app.tsx` to wrap the `` component:\n\n```tsx\n// src/pages/_app.tsx\n\nimport { Outlet } from 'react-router'\n\nimport { Redirects } from '../config/redirects'\n\nexport default function App() {\n return (\n \n \n \n \n\n \n \n \n \n \n \n )\n}\n```\n\nYou can find a full example of this approach at [Render template](https://github.com/oedotme/render/blob/main/src/config/redirects.tsx)\n\n \n\n\n\n\nHow to use with Hash or Memory Routers?\n\n \n\nYou can use the exported `routes` object to customize the router or to use hash/memory routers:\n\n```tsx\nimport { createRoot } from 'react-dom/client'\nimport { RouterProvider, createHashRouter } from 'react-router'\nimport { routes } from '@generouted/react-router'\n\nconst router = createHashRouter(routes)\nconst Routes = () => \n\ncreateRoot(document.getElementById('root')!).render()\n```\n\n \n\n\n\n \n\n## License\n\nMIT\n","readmeFilename":"readme.md"}
![\"generouted\"](\"https://raw.githubusercontent.com/oedotme/generouted/main/logo.svg\"){kind=logo}
![](\"https://img.shields.io/npm/v/generouted.svg\"/)
\n ![](\"https://img.shields.io/npm/l/generouted.svg?color=blue\"/)
\n ![](\"https://img.shields.io/badge/generouted/explorer-StackBlitz-blue\"/){kind=icon}
![](\"https://img.shields.io/npm/dm/generouted.svg\"/)
\n ![](\"https://img.shields.io/npm/dt/generouted.svg\"/)
\n