React Router Installation

Purpose and Scope

Use this page when you want to start a shadcn/ui project on React Router, or when you need to understand how the first-party React Router template is wired. The official guide presents three supported starting points: build a preset in shadcn/create, scaffold from the CLI, or configure an existing React Router project manually. In all three paths, the goal is the same: create a React Router application that can receive shadcn/ui registry components, resolve the expected import aliases, and share the same design-system conventions used by the project templates.

Sources: apps/v4/content/docs/installation/react-router.mdx, packages/shadcn/src/templates/react-router.ts

React Router support is not treated as a generic React setup. The template entry in the CLI package is named React Router, uses react-router as its framework identifier, and declares a default project name of react-router-app. It also distinguishes between a single application template directory and a monorepo template directory. That matters because component import examples differ between those two layouts: an app-only project imports UI files from the local components tree, while the monorepo guide points readers to the workspace UI package path.

Sources: apps/v4/content/docs/installation/react-router.mdx, packages/shadcn/src/templates/react-router.ts

Relevant Source Files

• apps/v4/content/docs/installation/react-router.mdx: The reader-facing installation guide for React Router, including the create flow, CLI flow, component-add commands, monorepo notes, and example imports.
• apps/v4/content/docs/installation/tanstack-router.mdx: A nearby router installation guide that shows the same documentation pattern of creating a router app, adding a component, and importing it into a route file.
• templates/react-router-monorepo/apps/web/package.json: The first-party monorepo web app manifest, including React Router scripts, React 19 dependencies, workspace UI dependency, Tailwind v4, Vite, and typecheck command.
• packages/shadcn/src/templates/react-router.ts: The CLI template definition for React Router, including template metadata, target framework, default generated route file, and monorepo template configuration.
• templates/react-router-monorepo/apps/web/app/root.tsx: The React Router root module for the monorepo template, showing document layout, framework components, global stylesheet import from the workspace UI package, outlet rendering, and error boundary behavior.
• templates/react-router-monorepo/apps/web/app/routes.ts: The route configuration used by the monorepo template, mapping the index route to routes/home.tsx.

Setup Paths

For a new project, the most guided path is shadcn/create. The React Router guide sends readers to a React Router-specific create URL where they choose style, colors, fonts, icons, and related preset options visually. After the choices are made, create generates a command shaped like an init command with a preset code and the React Router template selected. The exact command may include extra flags such as base styling, monorepo layout, or right-to-left support, so it is better to copy the generated command than to reconstruct it by hand.

Sources: apps/v4/content/docs/installation/react-router.mdx

The terminal-first path uses the same template without visiting the visual preset builder. Run the CLI init command with the React Router template flag, then answer prompts for options such as base, preset, and monorepo. If you already know that the repository should be a monorepo, pass the monorepo flag during initialization. The CLI template definition backs this flow by registering react-router as a supported framework and by associating the generated project with the React Router template directories used by the repository.

Sources: apps/v4/content/docs/installation/react-router.mdx, packages/shadcn/src/templates/react-router.ts

npx shadcn@latest init --preset [CODE] --template react-router
npx shadcn@latest init -t react-router
npx shadcn@latest init -t react-router --monorepo

Existing React Router projects follow the same installation intent but require more attention from the application owner. The guide frames this path as manually configuring shadcn/ui inside an app that already exists. In practice, you should verify that your project has the same pieces the generated template relies on: React Router tooling, Tailwind support, a component import alias, and a place for generated UI components. The repository evidence for the monorepo template is useful here because it shows the expected runtime scripts, root module shape, and route entry file that a working React Router integration uses.

Sources: apps/v4/content/docs/installation/react-router.mdx, templates/react-router-monorepo/apps/web/package.json, templates/react-router-monorepo/apps/web/app/root.tsx, templates/react-router-monorepo/apps/web/app/routes.ts

Template Runtime Shape

The monorepo web application manifest shows the runtime contract of the generated React Router app. It exposes scripts for development, build, production serving, formatting, and type checking. Development runs the React Router dev server, builds use the React Router build command, and production serving points react-router-serve at the built server entry. The typecheck script runs React Router type generation before TypeScript, which is important because the root module imports generated route types for its error boundary props. The dependency list also shows that the web app consumes the workspace UI package rather than owning every UI file locally.

Sources: templates/react-router-monorepo/apps/web/package.json, templates/react-router-monorepo/apps/web/app/root.tsx

{
  "scripts": {
    "dev": "react-router dev",
    "build": "react-router build",
    "start": "react-router-serve ./build/server/index.js",
    "typecheck": "react-router typegen && tsc"
  }
}

The root module establishes the shell that every route renders inside. It imports React Router document helpers for metadata, links, scripts, scroll restoration, and nested route output. It also imports the global stylesheet from the workspace UI package, which is the monorepo signal that shared design-system styles live outside the app package. The default application component renders an outlet, so generated route modules remain focused on page content. The error boundary handles route error responses, assigns a simple 404 message for missing pages, and exposes error details and a stack only during development when an Error object is available.

Sources: templates/react-router-monorepo/apps/web/app/root.tsx

The route configuration is intentionally small. The monorepo template exports an array satisfying the React Router route configuration type and maps the index route to routes/home.tsx. That file path lines up with both the documentation examples and the template definition in the CLI package. When the CLI template adds its starter file, it targets app/routes/home.tsx with a default component example import. This alignment is what lets the docs say to update the home route after adding a component: the route exists in the generated application and is already wired as the index page.

Sources: templates/react-router-monorepo/apps/web/app/routes.ts, packages/shadcn/src/templates/react-router.ts, apps/v4/content/docs/installation/react-router.mdx

Adding Components and Imports

After initialization, the guide uses Card as the first component-add example. The command installs the registry item into the project, then the route module imports Card, CardContent, CardDescription, CardHeader, and CardTitle. In a single React Router app, the example import comes from the app alias that resolves to the local components directory. In a monorepo, the docs instruct you to update apps/web/app/routes/home.tsx and import from the workspace UI package path instead. That difference is the most important day-one distinction between the two template shapes.

Sources: apps/v4/content/docs/installation/react-router.mdx, templates/react-router-monorepo/apps/web/package.json

npx shadcn@latest add card
npx shadcn@latest add card -c apps/web

import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "~/components/ui/card"
 
export default function Home() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Project Overview</CardTitle>
        <CardDescription>Track progress and recent activity for your React Router app.</CardDescription>
      </CardHeader>
      <CardContent>Your design system is ready.</CardContent>
    </Card>
  )
}

Use the workspace-aware command when you run from the repository root and want the CLI to modify the web app configuration rather than guessing from the current directory. The guide also allows running the add command from apps/web in a monorepo. The web package declares @workspace/ui as a workspace dependency, and the root file imports @workspace/ui/globals.css, so a monorepo installation should be evaluated as two cooperating packages: the app provides routing and rendering, while the shared UI package provides generated components and global styles.

Sources: apps/v4/content/docs/installation/react-router.mdx, templates/react-router-monorepo/apps/web/package.json, templates/react-router-monorepo/apps/web/app/root.tsx

System-to-Code Mapping

Troubleshooting and Next Steps

If the first component import fails, check whether you are in an app-only or monorepo layout before changing source code. App-only examples use the local components alias, while monorepo examples expect the workspace UI package. If a route does not render, confirm that the route file is the index route named by the route configuration. If type checking fails around route types, run the package typecheck script so React Router can generate types before TypeScript evaluates the app. These checks mirror the generated template rather than relying on framework guesses.

Sources: apps/v4/content/docs/installation/react-router.mdx, templates/react-router-monorepo/apps/web/package.json, templates/react-router-monorepo/apps/web/app/routes.ts

For adjacent setup patterns, compare this page with Installation Overview for choosing a starting path, Monorepos for workspace import strategy, CLI for command-level options, components.json for alias and generation settings, and Package Imports for package-level import mapping. If you are evaluating another router ecosystem, the TanStack Router installation page follows the same high-level shape: create a router app, add a shadcn/ui component, then import it into a route module. That comparison is useful for understanding which steps are shadcn/ui conventions and which are framework-specific routing conventions.

Sources: apps/v4/content/docs/installation/tanstack-router.mdx, apps/v4/content/docs/installation/react-router.mdx