Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท Getting Started

Project Setup and Folder Structure

Create a React Router v7 (Remix) app, understand every file and npm script in the template, and learn how client and server bundles are split, with runnable stand-ins.

Starting a Remix app is one command. The template gives you a working server-rendered site, TypeScript, Tailwind CSS and a production build. This lesson walks through creating the project, what each generated file does, which commands you will run every day, and how the build separates code that runs on the server from code that runs in the browser.

You need Node.js 20 or newer and a package manager (npm, pnpm or yarn). All the commands below are read-only examples; run them on your own machine.

Creating the project

Terminal
npx create-react-router@latest my-app
cd my-app
npm install      # the CLI offers to do this for you
npm run dev

The dev server prints a local address (by default http://localhost:5173). Open it and you see the starter page. Edit app/routes/home.tsx and the page updates without a reload, because Vite hot-reloads changes.

There are community templates too (--template takes a GitHub repository). The default template is a good start because it is small enough to read in full.

If you have an existing Remix v2 app, you do not start over. You upgrade the packages, rename imports from @remix-run/* to react-router, and add a routes.ts. The official upgrade guide covers it, and the React Router migration guide lists the same import changes.

What is in the template

TEXT
my-app/
  app/
    routes/
      home.tsx          a route module
    app.css             global styles (Tailwind in the default template)
    root.tsx            the root route: the HTML shell
    routes.ts           the route configuration
    welcome/            assets used by the starter page
  public/
    favicon.ico         served as-is from the site root
  package.json
  react-router.config.ts
  tsconfig.json
  vite.config.ts
File Job
app/root.tsx the outermost layout: <html>, <head>, <body>; every page renders inside it
app/routes.ts tells the router which URL maps to which file
app/routes/*.tsx route modules: loader, action, component, error boundary
app/entry.client.tsx optional: how the browser hydrates (a default is built in)
app/entry.server.tsx optional: how the server renders HTML (a default is built in)
react-router.config.ts framework settings: ssr, appDirectory, prerender, buildDirectory
vite.config.ts Vite plugins: reactRouter(), tsconfigPaths(), Tailwind
public/ static files, copied untouched into the client build

The two entry files do not appear in the template because the framework supplies defaults. Run npx react-router reveal to copy them into your project when you need to change streaming, add a provider or customise the response headers. Root and entry files covers them in depth.

Scripts you will use daily

JSON
{
  "scripts": {
    "build": "react-router build",
    "dev": "react-router dev",
    "start": "react-router-serve ./build/server/index.js",
    "typecheck": "react-router typegen && tsc"
  }
}
  • npm run dev starts Vite with hot module replacement and a server that renders on each request.
  • npm run build writes two bundles: build/client (static assets with hashed file names, safe to cache forever) and build/server (the code that renders pages).
  • npm start runs the built server with react-router-serve, a small Express-based server. Real deployments often use another adapter instead (see the deployment chapter).
  • npm run typecheck first generates the route types (react-router typegen) and then runs tsc.

Type generation

For every route, the framework generates a +types/<file> module under .react-router/types/. That is where import type { Route } from "./+types/product" comes from. It knows the route's URL parameters, what the loader returns, and what the action returns, so loaderData in your component is typed with no manual work. The generated folder belongs in .gitignore, and tsconfig.json contains rootDirs so the editor finds it.

Server code and browser code

Because the same repository holds server and client code, you need clear rules about what ships to the browser.

  • Code inside loader, action and headers is removed from the client bundle. The compiler deletes those exports (and any imports used only by them) when it builds for the browser.
  • Files named *.server.ts (or inside a .server/ folder) can never be bundled for the browser. Importing one from client-reachable code fails the build. Put database clients and secrets there.
  • Files named *.client.ts run only in the browser, and are empty on the server.
  • process.env is available only on the server. Values you want in the browser must be returned from a loader on purpose.

One repo, two bundles

build/server Loaders, actions, rendering
build/client Components, hashed assets
*.server.ts Never leaves the server
*.client.ts Browser only

The compiler enforces the split, not your good intentions.

1 / 2

Stand-in: listing a project as a tree

The real CLI creates the folder for you. This stand-in prints a file list as a tree, so you can try arranging a project. Add or rename paths to see how folders group.

JS Stand-in: draw the project tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: how the build splits server and client code

This stand-in does what the compiler does in spirit. It walks the import graph of a tiny app, adds everything reachable from client code to the client bundle, and rejects any .server file found there.

JS Stand-in: split the bundles by file name

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The client list contains only home.tsx and button.tsx: the database file is imported only by the loader code, which the compiler strips for the browser. The server list contains all four. If a component imported db.server.ts directly, the client build would stop with an error, which is exactly what you want, because secrets must not reach the browser.

Useful configuration

TypeScript
// react-router.config.ts  (real, read-only)
import type { Config } from "@react-router/dev/config";

export default {
  appDirectory: "app",   // where root.tsx and routes.ts live
  ssr: true,             // false = SPA mode, a static shell only
  // prerender: ["/", "/about"],   // render these URLs at build time
} satisfies Config;
  • ssr: true is the default: pages render on the server for each request.
  • ssr: false builds a single-page app. Loaders are then written as clientLoader.
  • prerender renders chosen URLs to static HTML at build time, which suits marketing pages.

The deployment chapter returns to these settings; for now keep the defaults.

Common mistakes

  • Importing a .server file in a component. The build fails; return the data from a loader instead.
  • Editing .react-router/types. It is regenerated on every run.
  • Committing build/. It is output; ignore it.
  • Using window at module scope. The module also runs on the server where window does not exist. Read it inside an effect or an event handler.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new React Router v7 framework app?

    create-react-router is the official scaffolding tool for framework mode.
  2. 2. What does npm run build produce?

    build/client holds hashed browser assets, build/server holds the code that renders pages.
  3. 3. Where should the database client and secrets live?

    Files named .server are never included in the browser bundle, and the build fails if client code imports them.
  4. 4. What does react-router typegen generate?

    Generated +types modules give each route typed params, loader data and action data.

Summary

  • npx create-react-router@latest scaffolds a working app; npm run dev starts it with hot reload.
  • root.tsx is the HTML shell, routes.ts maps URLs to route modules, public/ holds static files.
  • build writes separate client and server bundles; start serves the build.
  • Type generation gives every route a typed Route namespace.
  • Keep secrets in .server files and read window only in effects or handlers.

Next: Root and Entry Files