### Install react-router-fs-routes

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Install the plugin using npm, yarn, or pnpm.

```bash
npm install --save-dev react-router-fs-routes
# or
yarn add -D react-router-fs-routes
# or
pnpm add -D react-router-fs-routes
```

--------------------------------

### Custom File Names Configuration

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Example of configuring custom filenames for page and layout components, and a different output path.

```typescript
reactRouterFsRoutes({
  routesDir: 'app/routes',
  pageFilename: 'component',     // component.tsx instead of page.tsx
  layoutFilename: 'wrapper',     // wrapper.tsx instead of layout.tsx
  outputPath: 'app/generated/routes.tsx'
})
```

--------------------------------

### Generated Route Structure Example

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

An example of the TypeScript code generated by the plugin, defining React Router route objects.

```typescript
// Generated: src/lib/app-routes.tsx
import type { RouteObject } from 'react-router';
import RootPage from '../pages/page';
import AboutPage from '../pages/about/page';
import BlogLayout from '../pages/blog/layout';
import BlogPage from '../pages/blog/page';
import BlogDetailsPage from '../pages/blog/[id]/page';

export const routes: RouteObject[] = [
  {
    path: "/",
    Component: RootPage,
  },
  {
    path: "about",
    Component: AboutPage,
  },
  {
    path: "blog",
    Component: BlogLayout,
    children: [
      {
        index: true,
        Component: BlogPage,
      },
      {
        path: ":id",
        Component: BlogDetailsPage,
      },
    ],
  },
];

export default routes;
```

--------------------------------

### Generated RouteObject Array

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

This is an example of the auto-generated RouteObject array. It should be imported and passed directly to createBrowserRouter.

```typescript
// AUTO-GENERATED: src/lib/app-routes.tsx  (do not edit manually)
import type { RouteObject } from 'react-router';
import AboutPage from '../pages/about/page';
import BlogDetailsPage from '../pages/blog/[id]/page';
import BlogLayout from '../pages/blog/layout';
import BlogPage from '../pages/blog/page';
import RootLayout from '../pages/layout';
import RootNotFound from '../pages/not-found';
import RootPage from '../pages/page';
import SettingsPage from '../pages/(admin)/settings/page';
import UsersPage from '../pages/(admin)/users/page';

export const routes: RouteObject[] = [
  {
    path: "/",
    Component: RootLayout,
    children: [
      { index: true, Component: RootPage },
      { path: "about", Component: AboutPage },
      {
        path: "blog",
        Component: BlogLayout,
        children: [
          { index: true, Component: BlogPage },
          { path: ":id", Component: BlogDetailsPage },
        ],
      },
      { path: "users",    Component: UsersPage },
      { path: "settings", Component: SettingsPage },
      { path: "*",        Component: RootNotFound },
    ],
  },
];

export default routes;
```

--------------------------------

### Debug Mode Configuration

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Enable debug logging for the plugin to get more detailed output during development.

```typescript
reactRouterFsRoutes({
  debug: true  // Enables detailed logging
})
```

--------------------------------

### Filesystem to Route Path Mapping Conventions

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Illustrates how the plugin translates directory structures and file names into React Router paths, including dynamic segments and route groups.

```plaintext
src/pages/
├── page.tsx                        →  /
├── layout.tsx                      →  Root layout (wraps all routes)
├── not-found.tsx                   →  path: "*" catch-all at root
├── about/
│   └── page.tsx                    →  /about
├── blog/
│   ├── layout.tsx                  →  Layout for /blog/*
│   ├── page.tsx                    →  /blog  (index route)
│   └── [id]/
│       └── page.tsx                →  /blog/:id
├── (admin)/                        →  Route group — no URL segment added
│   ├── layout.tsx                  →  Shared layout for /users and /settings
│   ├── users/
│   │   └── page.tsx                →  /users
│   └── settings/
│       └── page.tsx                →  /settings
└── (marketing)/
    ├── layout.tsx
    └── landing/
        └── page.tsx                →  /landing
```

--------------------------------

### Create Route Files Structure

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Organize your React components in the specified routes directory to define your application's routes.

```treeview
src/pages/
├── page.tsx              # / route
├── about/
│   └── page.tsx          # /about route
├── blog/
│   ├── layout.tsx        # /blog layout
│   ├── page.tsx          # /blog route (index)
│   └── [id]/
│       └── page.tsx      # /blog/:id route
└── (admin)/              # Route group (no URL segment)
    ├── layout.tsx        # Admin layout
    ├── users/
    │   └── page.tsx      # /users route
    └── settings/
        └── page.tsx      # /settings route
```

--------------------------------

### Auto-Generated Starter Templates for Empty Route Files

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

When a route file is empty, the plugin automatically generates a minimal working component to ensure the app remains runnable. This applies to both page and layout files.

```typescript
// Empty src/pages/contact/page.tsx triggers auto-generation of:
export default function ContactPage() {
  return (
    <div>
      <h1>ContactPage</h1>
      <p>This page was auto-generated by react-router-fs-routes.</p>
    </div>
  );
}
```

```typescript
// Empty src/pages/dashboard/layout.tsx triggers auto-generation of:
import { Outlet } from 'react-router';

export default function DashboardLayout() {
  return (
    <div>
      <header>
        <h1>DashboardLayout</h1>
      </header>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
```

--------------------------------

### Configuration Options Interface

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

TypeScript interface defining the available configuration options for the plugin.

```typescript
interface ReactRouterFsRoutesOptions {
  /** Root directory for route files (default: "src/pages") */
  routesDir?: string;
  
  /** Filename for page components (default: "page") */
  pageFilename?: string;
  
  /** Filename for layout components (default: "layout") */
  layoutFilename?: string;
  
  /** Output path for generated routes configuration (default: "src/lib/app-routes.tsx") */
  outputPath?: string;
  
  /** Enable debug logging (default: false) */
  debug?: boolean;
}
```

--------------------------------

### Blog Details Page Component Convention

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

A page file exports a default React component. The plugin uses the directory path to derive a PascalCase component name and generates a starter template when an empty file is detected.

```typescript
// src/pages/blog/[id]/page.tsx
import { useParams } from 'react-router';

export default function BlogDetailsPage() {
  const { id } = useParams<{ id: string }>();

  return (
    <article>
      <h1>Post #{id}</h1>
      <p>Fetched dynamically based on the :id route parameter.</p>
    </article>
  );
}
```

--------------------------------

### reactRouterFsRoutes(options?)

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

The main factory function to create a Vite plugin instance. It scans the filesystem for route definitions and generates a typed routes file. It also watches for changes during development for hot-reloading.

```APIDOC
## reactRouterFsRoutes(options?)

### Description
Creates a Vite plugin instance that generates React Router v7 route configurations by scanning the filesystem. It registers with Vite's dev server to watch for changes and regenerate routes automatically.

### Method
`reactRouterFsRoutes(options?: ReactRouterFsRoutesOptions): Plugin`

### Parameters
#### Request Body
- **options** (ReactRouterFsRoutesOptions) - Optional - Configuration object for the plugin.
  - **routesDir** (string) - Optional - The root directory to scan for route files. Defaults to `src/pages`.
  - **pageFilename** (string) - Optional - The base filename for page components. Defaults to `page` (e.g., `page.tsx`).
  - **layoutFilename** (string) - Optional - The base filename for layout components. Defaults to `layout` (e.g., `layout.tsx`).
  - **notFoundFilename** (string) - Optional - The base filename for not-found/catch-all components. Defaults to `not-found` (e.g., `not-found.tsx`).
  - **outputPath** (string) - Optional - The path where the generated routes configuration file will be written. Defaults to `src/lib/app-routes.tsx`.
  - **ignoreFolders** (string[]) - Optional - An array of subdirectory names to ignore during the scan. Defaults to `['components']`.
  - **debug** (boolean) - Optional - Enables verbose console logging for debugging. Defaults to `false`.

### Request Example
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { reactRouterFsRoutes } from 'react-router-fs-routes';

export default defineConfig({
  plugins: [
    reactRouterFsRoutes({
      routesDir: 'src/pages',
      outputPath: 'src/lib/app-routes.tsx',
      debug: true,
    }),
  ],
});
```

### Response
Returns a Vite `Plugin` instance.
```

--------------------------------

### Blog Layout Component Convention

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

A layout file must render <Outlet /> where child routes appear. The plugin detects layout.tsx in a directory and automatically makes it the Component of that route.

```typescript
// src/pages/blog/layout.tsx
import { Outlet, NavLink } from 'react-router';

export default function BlogLayout() {
  return (
    <div className="blog-shell">
      <aside>
        <NavLink to="/blog">All Posts</NavLink>
      </aside>
      <main>
        <Outlet /> {/* child routes render here */}
      </main>
    </div>
  );
}
```

--------------------------------

### Layout Component Template

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Auto-generated starter template for a layout component. Includes Outlet for nested routes.

```typescript
// Auto-generated layout.tsx
import { Outlet } from 'react-router';

export default function LayoutName() {
  return (
    <div>
      <header>
        <h1>LayoutName</h1>
      </header>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
```

--------------------------------

### Configure Vite Plugin

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Integrate the plugin into your Vite configuration file.

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { reactRouterFsRoutes } from 'react-router-fs-routes';

export default defineConfig({
  plugins: [
    reactRouterFsRoutes({
      routesDir: 'src/pages',
      outputPath: 'src/lib/app-routes.tsx'
    })
  ]
});
```

--------------------------------

### Page Component Template

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Auto-generated starter template for a page component. Used when creating empty route files.

```typescript
// Auto-generated page.tsx
export default function PageName() {
  return (
    <div>
      <h1>PageName</h1>
      <p>This page was auto-generated by react-router-fs-routes.</p>
    </div>
  );
}
```

--------------------------------

### Use Generated Routes in Application

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Import and use the generated routes configuration to set up your React Router.

```typescript
// src/main.tsx
import { createBrowserRouter, RouterProvider } from 'react-router';
import { routes } from './lib/app-routes';

const router = createBrowserRouter(routes);

function App() {
  return <RouterProvider router={router} />;
}

export default App;
```

--------------------------------

### Not-Found Component Conventions

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Place a not-found.tsx file in any directory to generate a path: "*" catch-all entry scoped to that route branch. If no root not-found file exists, the plugin auto-creates one.

```typescript
// src/pages/not-found.tsx  — catches any unmatched URL
export default function RootNotFound() {
  return (
    <div style={{ textAlign: 'center', padding: '4rem' }}>
      <h1>404 — Page Not Found</h1>
      <a href="/">Go home</a>
    </div>
  );
}

// src/pages/blog/not-found.tsx  — catches unmatched /blog/* URLs only
export default function BlogNotFound() {
  return <p>That blog post doesn't exist.</p>;
}
```

--------------------------------

### Enable Debug Mode for Logging

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Enable detailed logging for debugging route generation, file changes, and error details.

```typescript
reactRouterFsRoutes({
  debug: true
})
```

--------------------------------

### Consuming Generated Routes in App Entry Point

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Wire the generated routes into a React app using createBrowserRouter from React Router v7. Ensure you import the generated routes file.

```typescript
// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { createBrowserRouter, RouterProvider } from 'react-router';
import { routes } from './lib/app-routes'; // generated file

const router = createBrowserRouter(routes);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>
);
```

--------------------------------

### Dynamic Route Segments with Folder Convention

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Use folders wrapped in square brackets to define dynamic route segments. Nested dynamic folders are supported.

```typescript
// src/pages/products/[productId]/reviews/[reviewId]/page.tsx
import { useParams } from 'react-router';

export default function ProductsDetailsPage() {
  const { productId, reviewId } = useParams<{ 
    productId: string;
    reviewId: string;
  }>();

  return <h1>Product {productId} — Review {reviewId}</h1>;
}
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Enable debug mode to see detailed error messages and file paths during route generation.

```typescript
reactRouterFsRoutes({
  debug: true  // Shows detailed error messages and file paths
})
```

--------------------------------

### Auth Layout Component Convention

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Wrapping a folder name in parentheses creates a route group. The folder name is stripped from the URL but its layout.tsx (if present) still wraps all descendants, enabling shared UI without adding a URL prefix.

```typescript
// src/pages/(auth)/layout.tsx
import { Outlet } from 'react-router';

export default function AuthLayout() {
  return (
    <div className="auth-card">
      <img src="/logo.svg" alt="Logo" />
      <Outlet />
    </div>
  );
}
```

--------------------------------

### ReactRouterFsRoutesOptions Interface

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

TypeScript interface defining all available options for the reactRouterFsRoutes plugin. All fields are optional, with sensible defaults provided.

```typescript
import type { Plugin } from 'vite';

interface ReactRouterFsRoutesOptions {
  /** Root directory for route files (default: "src/pages") */
  routesDir?: string;
  /** Filename for page components (default: "page") */
  pageFilename?: string;
  /** Filename for layout components (default: "layout") */
  layoutFilename?: string;
  /** Filename for not-found/404 components (default: "not-found") */
  notFoundFilename?: string;
  /** Output path for generated routes configuration (default: "src/lib/app-routes.tsx") */
  outputPath?: string;
  /** Folders to ignore when scanning routes (default: ["components"]) */
  ignoreFolders?: string[];
  /** Enable debug logging (default: false) */
  debug?: boolean;
}

// Minimal config — all defaults apply
reactRouterFsRoutes();

// Custom monorepo layout
reactRouterFsRoutes({
  routesDir: 'apps/web/routes',
  pageFilename: 'component',
  layoutFilename: 'wrapper',
  outputPath: 'apps/web/generated/routes.tsx',
  ignoreFolders: ['components', 'utils', 'hooks'],
});
```

--------------------------------

### Enabling Debug Mode for Verbose Logging

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Set `debug: true` in the plugin configuration to enable verbose logging of file changes, generation timing, and detailed error information.

```typescript
// vite.config.ts
reactRouterFsRoutes({ debug: true });
```

--------------------------------

### ReactRouterFsRoutesOptions Interface

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Defines the TypeScript interface for all available configuration options for the `reactRouterFsRoutes` plugin.

```APIDOC
### ReactRouterFsRoutesOptions

This interface defines the configuration options for the `reactRouterFsRoutes` Vite plugin. All fields are optional, and sensible defaults are provided.

```typescript
interface ReactRouterFsRoutesOptions {
  /** Root directory for route files (default: "src/pages") */
  routesDir?: string;
  /** Filename for page components (default: "page") */
  pageFilename?: string;
  /** Filename for layout components (default: "layout") */
  layoutFilename?: string;
  /** Filename for not-found/404 components (default: "not-found") */
  notFoundFilename?: string;
  /** Output path for generated routes configuration (default: "src/lib/app-routes.tsx") */
  outputPath?: string;
  /** Folders to ignore when scanning routes (default: ["components"]) */
  ignoreFolders?: string[];
  /** Enable debug logging (default: false) */
  debug?: boolean;
}
```

#### Example Usage

```typescript
// Minimal config — all defaults apply
reactRouterFsRoutes();

// Custom config for a monorepo structure
reactRouterFsRoutes({
  routesDir: 'apps/web/routes',
  pageFilename: 'component',
  layoutFilename: 'wrapper',
  outputPath: 'apps/web/generated/routes.tsx',
  ignoreFolders: ['components', 'utils', 'hooks'],
});
```
```

--------------------------------

### Configure react-router-fs-routes in vite.config.ts

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Register the reactRouterFsRoutes factory function in your Vite configuration. Customize options like the routes directory, output path, and ignored folders.

```typescript
import {
  defineConfig
} from 'vite';
import { reactRouterFsRoutes } from 'react-router-fs-routes';

export default defineConfig({
  plugins: [
    reactRouterFsRoutes({
      routesDir: 'src/pages', // Root directory scanned for route files
      pageFilename: 'page', // Matches page.tsx / page.jsx
      layoutFilename: 'layout', // Matches layout.tsx / layout.jsx
      notFoundFilename: 'not-found', // Matches not-found.tsx / not-found.jsx
      outputPath: 'src/lib/app-routes.tsx', // Where the generated file is written
      ignoreFolders: ['components'], // Subdirectories to skip during scanning
      debug: false, // Set true for verbose console output
    }),
  ],
});
```

--------------------------------

### Excluding Folders with ignoreFolders Option

Source: https://context7.com/aljaff94/react-router-fs-routes/llms.txt

Specify folders to be skipped during route scanning using the `ignoreFolders` option in `vite.config.ts`. This is useful for directories containing shared UI components or utilities.

```typescript
// vite.config.ts
reactRouterFsRoutes({
  routesDir: 'src/pages',
  ignoreFolders: ['components', 'hooks', 'utils', 'lib', '__tests__'],
});
```

--------------------------------

### Safe File Operation Function

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

A utility function for performing file operations safely, with error handling and optional file path context.

```typescript
// Safe file operations
function safeFileOperation<T>(
  operation: () => T,
  errorMessage: string,
  filePath?: string
): T;
```

--------------------------------

### Custom Error Class

Source: https://github.com/aljaff94/react-router-fs-routes/blob/main/README.md

Defines a custom error class for route generation errors, including optional file path and cause.

```typescript
// Custom error types with context
class RouteGenerationError extends Error {
  constructor(message: string, filePath?: string, cause?: Error);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.