React Router Tree

Implement Next.js style page directories in your single page application. Supports React projects created using Vite or CRA (or any other webpack implementation).

DEPRECATED ⚠️

This package is no longer actively maintained and has been superseded by Sceptre.

Installation

Install the package using NPM

npm install react-router-tree

Page folder structure

Pages are defined using a folder structure in your application. Subfolders denote path segments, while pages map to index.tsx or index.jsx files. In react-router-tree, each page is given it's own directory, in which assets and styles can be placed, allowing for a clean and structured page setup.

Exporting pages

Each page is expected to contain a default export of it's RouteObject. For TypeScript users a defineRoute helper function is included. The path property will automatically be populated when parsing the tree, so it may be omitted.

import { defineRoute } from "react-router-tree";

function IndexPage() {
	return (
		<div>
			Page content
		</div>
	)
}

export default defineRoute({
	element: <IndexPage />
});

URL Parameters

Parameters can be defined by using [name] as folder name. This will automatically translate into :name when building routes.

We also support a other parameter type: ... which will match any path segment.

Index mapping

Folders named @ will map to the index page of the parent directory.

Parent pages

You can add a parent pages by making a folder named _ anywhere in your file tree. Parent pages are responsible for placing an <Outlet /> where child routes will be rendered. Routes can be parented any number of times, each rendering in its closest parent outlet.

Visual example:

/example/_				- Responsible for rendering outlet 1
/example/@				- Rendered inside outlet 1
/example/page/_			- Rendered inside outlet 1 and responsible for rendering outlet 2
/example/page/@			- Rendered inside outlet 2
/example/page/child 	- Rendered inside outlet 2

Alternative paths

The route object returned from a page allows defining a list of alternative routes that can be used to reach the page. These alternative paths are relative to the route itself and share the same meta.

Example:

export default defineRoute({
	element: <HelpPage />,
	alternatives: [
		{ path: 'instructions' },
		{ path: 'sub/path/:param' }
	]
});

Example folder structure

pages/
	@/
		index.tsx
		styles.tsx
	help/
		index.tsx
		style.scss
	settings/
		_/
			index.tsx
		overview/
			index.tsx
		[param]/
			index.tsx
	folder/
		_/
			index.tsx
		[...]/
			index.tsx
			style.scss

The above example translates to the given routes

/
/help
/settings/overview
/settings/:param
/folder/*

Usage

// Using vite:
const pageTree: RouteTree = {
	prefix: './pages',
	routes: import.meta.glob('./pages/**/index.tsx', { eager: true })
};

// Using Create React App:
const pageTree: RouteTree = {
	prefix: './',
	routes: require.context('./pages/', true, /\index\.tsx$/)
};

// Combine page trees into a single array of routes
const routes = buildRouteObjects(pageTree);

Example

An example implementation can be found here.

Vindigo

This package was originally developed for use in Vindigo, a free and open source task planner.

License

react-router-tree is licensed under MIT

Copyright (c) 2022-present, Starlane Studios