Skip to content

Commit 4a910ac

Browse files
brookslybrandbrookslybrand
authored
docs: add quick start doc for framework mode (#13864)
* docs: add quick start doc for framework mode * docs(quickstart): refine language and improve clarity in quick start guide
1 parent f33e6b7 commit 4a910ac

File tree

2 files changed

+307
-1
lines changed

2 files changed

+307
-1
lines changed

‎docs/tutorials/address-book.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
---
22
title: Address Book
3-
order: 1
3+
order: 2
44
---
55

66
# Address Book
77

8+
[MODES: framework]
9+
10+
<br />
11+
<br />
12+
813
We'll be building a small, but feature-rich address book app that lets you keep track of your contacts. There's no database or other "production ready" things, so we can stay focused on the features React Router gives you. We expect it to take 30-45m if you're following along, otherwise it's a quick read.
914

1015
<docs-info>

‎docs/tutorials/quickstart.md

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
---
2+
title: Quick Start
3+
order: 1
4+
---
5+
6+
# Quick Start
7+
8+
[MODES: framework]
9+
10+
<br />
11+
<br />
12+
13+
This guide will familiarize you with the basic plumbing required to run a React Router app as quickly as possible. While there are many starter templates with different runtimes, deploy targets, and databases, we're going to create a bare-bones project from scratch.
14+
15+
## Installation
16+
17+
If you prefer to initialize a batteries-included React Router project, you can use the `create-react-router` CLI to get started with any of our [templates][templates]:
18+
19+
```shellscript nonumber
20+
npx create-react-router@latest
21+
```
22+
23+
However, this guide will explain everything the CLI does to set up your project. Instead of using the CLI, you can follow these steps. If you're just getting started with React Router, we recommend following this guide to understand all the different pieces that make up a React Router app.
24+
25+
```shellscript nonumber
26+
mkdir my-react-router-app
27+
cd my-react-router-app
28+
npm init -y
29+
30+
# install runtime dependencies
31+
npm i react-router @react-router/node @react-router/serve isbot react react-dom
32+
33+
# install dev dependencies
34+
npm i -D @react-router/dev vite
35+
```
36+
37+
## Vite Config
38+
39+
```shellscript nonumber
40+
touch vite.config.js
41+
```
42+
43+
Since React Router uses [Vite], you'll need to provide a [Vite config][vite-config] with the React Router Vite plugin. Here's the basic configuration you'll need:
44+
45+
```js filename=vite.config.js
46+
import { reactRouter } from "@react-router/dev/vite";
47+
import { defineConfig } from "vite";
48+
49+
export default defineConfig({
50+
plugins: [reactRouter()],
51+
});
52+
```
53+
54+
## The Root Route
55+
56+
```shellscript nonumber
57+
mkdir app
58+
touch app/root.jsx
59+
```
60+
61+
`app/root.jsx` is what we call the "Root Route". It's the root layout of your entire app. Here's the basic set of elements you'll need for any project:
62+
63+
```jsx filename=app/root.jsx
64+
import { Outlet, Scripts } from "react-router";
65+
66+
export default function App() {
67+
return (
68+
<html>
69+
<head>
70+
<link
71+
rel="icon"
72+
href="data:image/x-icon;base64,AA"
73+
/>
74+
</head>
75+
<body>
76+
<h1>Hello world!</h1>
77+
<Outlet />
78+
<Scripts />
79+
</body>
80+
</html>
81+
);
82+
}
83+
```
84+
85+
## Additional Routes
86+
87+
```shellscript nonumber
88+
touch app/routes.js
89+
```
90+
91+
`app/routes.js` is where you define your routes. This guide focuses on the minimal setup to get a React Router app up and running, so we don't need to define any routes and can just export an empty array:
92+
93+
```js filename=app/routes.js
94+
export default [];
95+
```
96+
97+
The existence of `routes.js` is required to build a React Router app; if you're using React Router we assume you'll want to do some routing eventually. You can read more about defining routes in our [Routing][routing] guide.
98+
99+
## Build and Run
100+
101+
First, you will need to specify the type as `module` in `package.json` to satisfy ES module requirements for `react-router` and future versions of Vite.
102+
103+
```shellscript nonumber
104+
npm pkg set type="module"
105+
```
106+
107+
Next build the app for production:
108+
109+
```shellscript nonumber
110+
npx react-router build
111+
```
112+
113+
You should now see a `build` folder containing a `server` folder (the server version of your app) and a `client` folder (the browser version) with some build artifacts in them. (This is all [configurable][react-router-config].)
114+
115+
👉 **Run the app with `react-router-serve`**
116+
117+
Now you can run your app with `react-router-serve`:
118+
119+
```shellscript nonumber
120+
npx react-router-serve build/server/index.js
121+
```
122+
123+
You should be able to open up [http://localhost:3000][http-localhost-3000] and see the "hello world" page.
124+
125+
Aside from the unholy amount of code in `node_modules`, our React Router app is just four files:
126+
127+
```
128+
├── app/
129+
│ ├── root.jsx
130+
│ └── routes.js
131+
├── package.json
132+
└── vite.config.js
133+
```
134+
135+
## Bring Your Own Server
136+
137+
The `build/server` directory created by `react-router build` is just a module that you run inside a server like Express, Cloudflare Workers, Netlify, Vercel, Fastly, AWS, Deno, Azure, Fastify, Firebase, ... anywhere.
138+
139+
<docs-info>
140+
141+
You can also use React Router as a Single Page Application with no server. For more information, see our guide on [Single Page Apps][spa].
142+
143+
</docs-info>
144+
145+
If you don't care to set up your own server, you can use `react-router-serve`. It's a simple `express`-based server maintained by the React Router maintainers. However, React Router is specifically designed to run in _any_ JavaScript environment so that you own your stack. It is expected many —if not most— production apps will have their own server.
146+
147+
Just for kicks, let's stop using `react-router-serve` and use `express` instead.
148+
149+
👉 **Install Express, the React Router Express adapter, and [cross-env] for running in production mode**
150+
151+
```shellscript nonumber
152+
npm i express @react-router/express cross-env
153+
154+
# not going to use this anymore
155+
npm uninstall @react-router/serve
156+
```
157+
158+
👉 **Create an Express server**
159+
160+
```shellscript nonumber
161+
touch server.js
162+
```
163+
164+
```js filename=server.js
165+
import { createRequestHandler } from "@react-router/express";
166+
import express from "express";
167+
168+
const app = express();
169+
app.use(express.static("build/client"));
170+
171+
// notice that your app is "just a request handler"
172+
app.use(
173+
createRequestHandler({
174+
// and the result of `react-router build` is "just a module"
175+
build: await import("./build/server/index.js"),
176+
})
177+
);
178+
179+
app.listen(3000, () => {
180+
console.log("App listening on http://localhost:3000");
181+
});
182+
```
183+
184+
👉 **Run your app with `express`**
185+
186+
```shellscript nonumber
187+
node server.js
188+
```
189+
190+
Now that you own your server, you can debug your app with whatever tooling your server has. For example, you can inspect your app with Chrome DevTools using the [Node.js inspect flag][inspect]:
191+
192+
```shellscript nonumber
193+
node --inspect server.js
194+
```
195+
196+
## Development Workflow
197+
198+
Instead of stopping, rebuilding, and starting your server all the time, you can run React Router in development using [Vite in middleware mode][vite-middleware]. This enables instant feedback to changes in your app with React Refresh (Hot Module Replacement) and React Router Hot Data Revalidation.
199+
200+
First, as a convenience, add `dev` and `start` commands in `package.json` that will run your server in development and production modes respectively:
201+
202+
👉 **Add a "scripts" entry to `package.json`**
203+
204+
```jsonc filename=package.json lines=[2-4] nocopy
205+
{
206+
"scripts": {
207+
"dev": "node ./server.js",
208+
"start": "cross-env NODE_ENV=production node ./server.js"
209+
}
210+
// ...
211+
}
212+
```
213+
214+
👉 **Add Vite development middleware to your server**
215+
216+
Vite middleware is not applied if `process.env.NODE_ENV` is set to `"production"`, in which case you'll still be running the regular build output as you did earlier.
217+
218+
```js filename=server.js lines=[6,13-28]
219+
import { createRequestHandler } from "@react-router/express";
220+
import express from "express";
221+
222+
const app = express();
223+
224+
if (process.env.NODE_ENV === "production") {
225+
app.use(express.static("build/client"));
226+
app.use(
227+
createRequestHandler({
228+
build: await import("./build/server/index.js"),
229+
})
230+
);
231+
} else {
232+
const viteDevServer = await import("vite").then((vite) =>
233+
vite.createServer({
234+
server: { middlewareMode: true },
235+
})
236+
);
237+
app.use(viteDevServer.middlewares);
238+
app.use(
239+
createRequestHandler({
240+
build: () =>
241+
viteDevServer.ssrLoadModule(
242+
"virtual:react-router/server-build"
243+
),
244+
})
245+
);
246+
}
247+
248+
app.listen(3000, () => {
249+
console.log(`Server is running on http://localhost:3000`);
250+
});
251+
```
252+
253+
👉 **Start the dev server**
254+
255+
```shellscript nonumber
256+
npm run dev
257+
```
258+
259+
Now you can work on your app with immediate feedback. Give it a try by changing the text in `root.jsx` and watch the changes appear instantly!
260+
261+
## Controlling Server and Browser Entries
262+
263+
There are default magic files React Router is using that most apps don't need to mess with, but if you want to customize React Router's entry points to the server and browser you can run `react-router reveal` and they'll get dumped into your project.
264+
265+
```shellscript nonumber
266+
npx react-router reveal
267+
```
268+
269+
```
270+
Entry file entry.client created at app/entry.client.tsx.
271+
Entry file entry.server created at app/entry.server.tsx.
272+
```
273+
274+
## Summary
275+
276+
Congrats, you can add React Router to your resume! Summing things up, we've learned:
277+
278+
- React Router framework mode compiles your app into two things:
279+
- A request handler that you add to your own JavaScript server
280+
- A pile of static assets in your public directory for the browser
281+
- You can bring your own server with adapters to deploy anywhere
282+
- You can set up a development workflow with HMR built-in
283+
284+
In general, React Router is a bit "guts out". It requires a few minutes of boilerplate, but now you own your stack.
285+
286+
What's next?
287+
288+
- [Address Book Tutorial][address-book-tutorial]
289+
290+
[templates]: ../start/framework/deploying#templates
291+
[spa]: ../how-to/spa
292+
[inspect]: https://nodejs.org/en/docs/guides/debugging-getting-started/
293+
[vite-config]: https://vite.dev/config
294+
[routing]: ../start/framework/routing
295+
[templates]: /resources?category=templates
296+
[http-localhost-3000]: http://localhost:3000
297+
[vite]: https://vitejs.dev
298+
[react-router-config]: https://api.reactrouter.com/v7/types/_react_router_dev.config.Config.html
299+
[vite-middleware]: https://vitejs.dev/guide/ssr#setting-up-the-dev-server
300+
[cross-env]: https://www.npmjs.com/package/cross-env
301+
[address-book-tutorial]: ./address-book

0 commit comments

Comments
 (0)