React Router Tree Routes

This package provides a way to define React Router v7 routes using your file system tree. It simplifies route management by automatically generating route configurations based on your file structure.

Introduction

React Router v7 introduced file-system based routing through its @react-router/fs-routes package. While this approach simplifies route configuration by mapping URLs directly to files, it can lead to challenges with deeply nested routes. For instance, a route like /some/path/to/deeply/nested/route might require a file named app/routes/some.path.to.deeply.nested.route.tsx.

This naming convention can make your file system difficult to navigate, especially as your application grows and routes become more complex. It also makes it harder to visualize the route hierarchy within a file explorer.

This package addresses this issue by providing an alternative file-system convention that leverages directory structures more effectively, allowing for cleaner organization and easier navigation of your routes.

Features

• File System Based Routing: Define your routes by organizing files and directories.
• Flexible Modes: Supports both 'file' and 'dir' routing modes.
• Customizable File Naming: Configure custom filenames for index, route, and splat routes.
• TypeScript Support: Built with TypeScript for type safety.

Installation

To install the package, use pnpm (or npm/yarn):

pnpm install react-router-tree-routes

Usage

Basic Usage

Put this in app/routes.ts.

import treeRoutes from 'react-router-tree-routes'

// all of these parameters are the default values and optional.
export default treeRoutes({
  mode: 'dir',
  appDirectory: 'app',
  routesDirectory: 'routes',
  extensions: ['js', 'jsx', 'ts', 'tsx'],
  exclude: /^_|\.test/,
  filenames: {
    route: 'route',
    index: 'main',
    splat: 'splat',
  },
})

Configuration Options

The treeRoutes function accepts an RoutesOptions object to customize its behavior:

interface RoutesOptions {
  /**
   * The routing mode to use.
   *
   * @default 'dir'
   */
  mode?: 'dir' | 'file'
  /**
   * The base directory where your application's route files are located.
   * This path is relative to the project root.
   *
   * @default 'app'
   */
  appDirectory?: string
  /**
   * The subdirectory within `appDirectory` that contains the route definitions.
   *
   * @default 'routes'
   */
  routesDirectory?: string
  /**
   * An array of file extensions to consider when searching for route files.
   *
   * @default ['js', 'jsx', 'ts', 'tsx']
   */
  extensions?: string[]
  /**
   * A regular expression to exclude files or directories from being processed as routes.
   * Files matching this pattern will be ignored.
   *
   * @default /^_|\.test/
   */
  exclude?: RegExp

  /**
   * Custom filenames to identify specific types of routes (e.g., index, splat).
   * These names are used in conjunction with the `mode` to determine route behavior.
   */
  filenames?: {
    /**
     * The filename used to identify a regular route file in 'dir' mode.
     * For example, if `route` is 'route', then `some/route.tsx` defines the 'some' route.
     *
     * @default 'route'
     */
    route?: string
    /**
     * The filename used to identify an index route.
     * An index route serves as the default route for its parent directory.
     *
     * @default 'main'
     */
    index?: string
    /**
     * The filename used to identify a splat route (catch-all route).
     * A splat route matches any subsequent path segments.
     *
     * @default 'splat'
     */
    splat?: string
  }
}

License

This project is licensed under the MIT License.