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 TanStack's React Location
• React with React Router
• Solid with Solid Router

Getting started

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

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 />)

React Router

Installation

pnpm add generouted react-router-dom

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 />)

Solid Router

If you're using Solid, check out their getting started guide to start a new project.

Installation

pnpm add generouted @solidjs/router

Usage

// src/main.tsx

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

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

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

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 Location

• Basic
• Data loaders
• Modals
• Nested layouts

React Router

• Basic
• Nested layouts

Solid Router

• Basic

License

MIT