Generouted

Generated file-based routes for Vite

Motivation

I enjoyed working with file-based routing since started using it with Next.js. After trying the same concept with Vite, I started a series of blog posts covering client-side file-based routing with React Router inspired by Next.js. Later, in the last two posts, I replaced React Router with React Location to add more features like data loaders and nested layouts that are inspired by Remix. The final version covered in the blog posts is now published as generouted, see all the available features below.

How

generouted is only one source code file, with no dependencies or build step. It uses Vite's glob import API to list the modules within src/pages directory to be used as React Location's routes.

Why

• Declarative and universal file-based routing system
• Automatically update routes by adding/removing/renaming files at the src/pages directory
• Can be used with any Vite project
• Easier to migrate when switching from or to Next.js
• Automatic route-based code-splitting and pre-loading
• Route-based data loaders
• Route-based actions

Framework support

• React with React Router w/ type-safe navigation 🆕
• React with TanStack React Router
• React with TanStack's React Location
• Solid with Solid Router w/ type-safe navigation 🆕

Getting started

In case you don't have a Vite project with React and TypeScript, check Vite documentation to start a new project.

React Router w/ type-safe navigation 🆕

Installation

pnpm add @generouted/react-router generouted react-router-dom

• generouted provides the file-based routes
• @generouted/react-router optional but recommended plugin to generates types and type-safe router component/hooks/utils

Setup

// vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import generouted from '@generouted/react-router'

export default defineConfig({ plugins: [react(), generouted()] })

Usage

// src/main.tsx

import { createRoot } from 'react-dom/client'
import { Routes } from 'generouted/react-router'

const container = document.getElementById('app')!
createRoot(container).render(<Routes />)

🚀 Check more about type-safe navigation and global modals in the plugin docs.

TanStack React Router

Check out the docs here

React Location

Installation

pnpm add generouted @tanstack/react-location

Usage

// src/main.tsx

import { createRoot } from 'react-dom/client'
import { Routes } from 'generouted/react-location'

const container = document.getElementById('app')!
createRoot(container).render(<Routes />)

Solid Router w/ type-safe navigation 🆕

In case you don't have a Vite project with Solid and TypeScript, check out this getting started guide to start a new project.

Installation

pnpm add @generouted/solid-router generouted @solidjs/router

• generouted provides the file-based routes
• @generouted/solid-router optional but recommended plugin to generates types and type-safe router component/hooks

Setup

// vite.config.ts

import { defineConfig } from 'vite'
import solid from 'vite-plugin-solid'
import generouted from '@generouted/solid-router'

export default defineConfig({ plugins: [solid(), generouted()] })

Usage

// src/main.tsx

import { render } from 'solid-js/web'
import { Routes } from 'generouted/solid-router'

render(Routes, document.getElementById('app')!)

🚀 Check more about type-safe navigation and global modals in the plugin docs.

Adding pages

Add the home page by creating a new file src/pages/index.tsx → /, then export a default component:

export default function Home() {
  return <h1>Home</h1>
}

See more about generouted routing conventions below.

Features

• File-based routing
• Route-based code-splitting and pre-loading
• Route-based data loaders and actions
• Route-based actions
• Nested layouts

File-based routing

• Next.js inspired
• Files within src/pages directory
• Supports .jsx and .tsx extensions
• Renders page's default export
• Custom app at src/pages/_app.tsx (optional)
• Custom 404 page at src/pages/404.tsx (optional)
• Navigation between routes using the routing library Link or A component

Route-based code-splitting and pre-loading

• Includes routes components, data loaders and actions
• Pre-loading is only available for TanStack's React Location

Route-based data loaders

• Remix inspired
• By exporting a named function Loader from a page: export const Loader = async () => ({...})
• React Location's route loaders guide

Route-based actions

• Actions are only available for React Router
• By exporting a named function Action from a page: export const Action = async () => ({...})

Nested layouts

• Remix inspired
• Adding a layout for a group of routes by naming a file same as their parent directory or using a _layout.tsx file inside of the nested directory
• Supports data loaders
• Requires <Outlet /> component to render its children

Conventions

Index routes

• src/pages/index.tsx → /
• src/pages/posts/index.tsx → /posts

Nested routes

• src/pages/posts/2022/index.tsx → /posts/2022
• src/pages/posts/2022/resolutions.tsx → /posts/2022/resolutions

Dynamic routes

• src/pages/posts/[slug].tsx → /posts/:slug
• src/pages/posts/[slug]/tags.tsx → /posts/:slug/tags
• src/pages/posts/[...all].tsx → /posts/*

Nested layouts

Enable for all directory routes

Add a layout for all the routes within src/pages/posts directory by adding src/pages/posts.tsx or src/pages/posts/_layout.tsx:

• src/pages/posts.tsx or src/pages/posts/_layout.tsx
  • src/pages/posts/index.tsx → /posts
  • src/pages/posts/2022/index.tsx → /posts/2022
  • src/pages/posts/[slug].tsx → /posts/:slug

Exclude a route - URL nesting without layout nesting

Add a file outside of the directory with a nested layout, then name the file by adding a dot between each segment, it will be converted to forward slashes:

• src/pages/posts.nested.as.url.not.layout.tsx → /posts/nested/as/url/not/layout

Pathless layout groups 🆕

By wrapping a directory name with (): src/pages/(app)/...

src/pages/
├── (app)/
│   ├── _layout.tsx
│   ├── dashboard.tsx      →  /dashboard      wrapped by (app)/_layout.tsx
│   └── item.tsx           →  /item           wrapped by (app)/_layout.tsx
├── (marketing)/
│   ├── _layout.tsx
│   ├── about.tsx          →  /about          wrapped by (marketing)/_layout.tsx
│   └── testimonials.tsx   →  /testimonials   wrapped by (marketing)/_layout.tsx
└── admin/
    ├── _layout.tsx
    └── index.tsx          →  /admin          wrapped by admin/_layout.tsx

Optional route segments 🆕

By prefixing a minus sign - to a segment; meaning this segment can be subtracted/removed from route url:

• src/pages/-some/thing.tsx → /some?/thing
• src/pages/-[param]/another.tsx → /:param?/another

React Router v6.5.0+ supports regular and dynamic optional route segments:

src/pages/-en/about.tsx  →  /en?/about            /en/about and /about
src/pages/-[lang]/about.tsx  →  /:lang?/about     /en/about, /fr/about, /about

However other integration might only support optional dynamic segments:

src/pages/-[lang]/about.tsx  →  /:lang?/about     /en/about, /fr/about, /about

Ignored routes - co-locating non-pages files inside the pages directory

Any directory or a file starts with _ will be ignored

• src/pages/_ignored.tsx
• src/pages/posts/_components/button.tsx
• src/pages/posts/_components/link.tsx

API

React Location

<Routes />

<Routes /> component accepts all React Location's RouterProps except children, location and routes props.

React Router

<Routes />

No available props.

Solid Router

<Routes />

No available props.

Examples

React Router

• Basic
• Nested layouts
• w/ type-safe navigation plugin 🆕

TanStack React Router

• Basic

TanStack React Location

• Basic
• Data loaders
• Modals
• Nested layouts

Solid Router

• w/ type-safe navigation plugin 🆕

License

MIT