react-router-v7-app

name	react-router-v7-app
description	Implements React Router v7 app structure, routing patterns, and component templates. Use when creating or modifying React Router v7 applications to ensure consistent folder structure, data loading patterns, and component architecture.

React Router v7 App Implementation

1. Route Structure

• Use file-based routing in app/routes/.
• Route files: route.tsx for route components.
• Prefer folder routes like users.$id/route.tsx when a route needs colocated helpers, components, or tests; sibling files in the folder do not become routes.
• If tests live under app/routes/, configure flatRoutes({ ignoredRouteFiles: [...] }) to exclude *.test.* and *.spec.* from route discovery.
• Use underscore prefix for route groups: _app, _landing.
• Use dot notation for nested routes: users.$id.tsx.

2. Data Loading Patterns

• Use loader functions for server-side data fetching.
• Use action functions for form submissions and mutations.
• Leverage useLoaderData() and useActionData() hooks.
• Handle loading states with useNavigation().

3. Route Component Structure

Use arrow functions for all exports.

import type { Route } from './+types/route';

export const loader = async ({ request, params, context }: Route.LoaderArgs) => {
  // Server-side data loading
  // Return an object
  return { ... };
};

export const action = async ({ request, params, context }: Route.ActionArgs) => {
  // Handle form submissions and mutations
  // Return an object
  return { ... };
};

const Page = ({ loaderData, actionData }: Route.ComponentProps) => {
  // Component implementation with typed props
  return (
    <div>
      {/* Content */}
    </div>
  );
};

export default Page;

4. Error Handling

• Use ErrorBoundary components for route-level error handling.
• Implement proper error responses in loaders/actions.
• Use isRouteErrorResponse() for typed error handling.

5. Meta and Headers

• Export meta function for dynamic page metadata.
• Export headers function for custom HTTP headers.
• Use proper SEO practices with meta tags.

6. Project Structure

The app folder should follow this structure:

public                # Static files (images, fonts, etc.)
|
app
|
+-- components        # Shared components
|
+-- config            # Global configuration and environment variables
|
+-- constants         # Global constants
|
+-- hooks             # Shared hooks
|
+-- lib               # Pre-configured reusable libraries
|
+-- routes            # React Router routing directory
|
+-- stores            # Global state stores
|
+-- testing           # Test utilities and mock servers
|
+-- types             # Base types used across the application
|
+-- utils             # Shared utility functions
|

app/components

• Place app-wide shared components under app/components.
• Components in this directory should be reusable across multiple routes or features.
• Do not place feature-scoped components here; keep them inside each route directory's components folder.
• Use lowercase kebab-case for all component file names in both app/components and route-scoped components directories.
• Examples: app-header.tsx, empty-state.tsx, todo-form.tsx.

app/components
|
+-- ui              # shadcn/ui components
|   |
|   +-- button.tsx
|   ...
|
+-- app-header.tsx  # Shared across multiple routes
+-- empty-state.tsx # Shared across multiple features
|

routes

Use collocation to group files related to layouts and pages.

• Keep the route module in route.tsx and colocate route-local tests as route.test.ts only when route discovery is configured to ignore test/spec files.

app/routes/_app._index
|
+-- assets      # Feature-specific static files
|
+-- components  # Feature-scoped components
|
+-- constants   # Feature-specific constants
|
+-- hooks       # Feature-scoped hooks
|
+-- services    # Feature services (business logic)
|
+-- stores      # Feature state stores
|
+-- types       # Feature-specific TypeScript types
|
+-- utils       # Feature-specific utility functions

Example structure:

app/routes
|
+-- _app                # App-wide layout & shared files
|   |
|   +-- route.tsx       # Layout file
|   
+-- _app.index          # App top page
|   |
|   +-- route.tsx       # Page file
|   
+-- _app.todos          # (Example) todos layout & shared files
|   |
|   +-- components      # Components used in layout
|   |
|   +-- types           # Types common to todos
|   |
|   +-- route.tsx       # Layout file
|
+-- _app.todos._index   # (Example) todos top page
|   |
|   +-- components      # Components used in page
|   |
|   +-- route.tsx       # Page file
|
+-- _app.todos.$todoId.edit._index  # (Example) todos edit page
|   |
|   +-- components      # Components used in page
|   |
|   +-- hooks           # Hooks used in page
|   |
|   +-- stores          # Stores used in page
|   |
|   +-- route.tsx       # Page file
|
+-- _app.todos.$todoId_.delete      # (Example) todos delete resource route
    |
    +-- route.tsx       # Resource route file

7. Advanced Routing Patterns

Nested Routes for UI Segmentation

Use nested routes to split complex pages (e.g., tabs) into independent route modules.

• Parent route renders shared UI and <Outlet />.
• Child routes handle their own data loading (loader) and mutations (action).
• Reduces prop drilling and isolates logic.

Example (Tabs):

• routes/user.tsx: Renders tabs navigation and <Outlet />.
• routes/user.profile.tsx: Renders profile tab content.
• routes/user.account.tsx: Renders account tab content.

Route-based Modals

Manage modal state via URLs instead of useState.

• Define the modal as a child route.
• Parent route renders the background UI and <Outlet />.
• Modal component renders inside the <Outlet /> (often using a Dialog component).
• Closing the modal is a navigation action (e.g., <Link to="..">).

Example:

• routes/users.tsx: Lists users and contains <Outlet />.
• routes/users.new.tsx: Renders the "Create User" modal.