¥Quick Start
本指南将帮助你尽快熟悉运行 Remix 应用所需的基本流程。虽然市面上有很多入门模板，它们拥有不同的运行时、部署目标和数据库，但我们将从头开始创建一个最基本的项目。
¥This guide will get you familiar with the basic plumbing required to run a Remix 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.
当你准备认真对待你的 Remix 项目时，可以考虑从社区模板开始。它们包括 TypeScript 设置、数据库、测试工具、身份验证等等。你可以在 Remix 资源 页面上找到社区模板列表。
¥When you're ready to get serious about your Remix project, you might consider starting with a community template. They include TypeScript setups, databases, testing harnesses, authentication, and more. You can find a list of community templates on the Remix Resources page.
¥Installation
如果你希望初始化包含电池的 Remix 项目，你可以使用 create-remix CLI：
¥If you prefer to initialize a batteries-included Remix project, you can use the create-remix CLI:
npx create-remix@latest
不过，本指南将讲解 CLI 设置项目的所有步骤，你可以按照以下步骤操作，而无需使用 CLI。如果你刚刚开始使用 Remix，我们建议你遵循本指南来了解构成 Remix 应用的所有不同部分。
¥However, this guide will explain everything the CLI does to set up your project, and instead of using the CLI, you can follow these steps. If you're just getting started with Remix, we recommend following this guide to understand all the different pieces that make up a Remix app.
mkdir my-remix-app
cd my-remix-app
npm init -y
# install runtime dependencies
npm i @remix-run/node @remix-run/react @remix-run/serve isbot@4 react@18 react-dom@18
# install dev dependencies
npm i -D @remix-run/dev vite
¥Vite Config
touch vite.config.js
由于 Remix 使用 Vite，因此你需要为 Remix Vite 插件提供 Vite 配置。以下是你需要的基本配置：
¥Since Remix uses Vite, you'll need to provide a Vite config with the Remix Vite plugin. Here's the basic configuration you'll need:
import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [remix()],
});
¥The Root Route
mkdir app
touch app/root.jsx
app/root.jsx 就是我们所说的 "根路由"。它是整个应用的根布局。以下是任何项目所需的基本元素集：
¥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:
import {
Links,
Meta,
Outlet,
Scripts,
} from "@remix-run/react";
export default function App() {
return (
<html>
<head>
<link
rel="icon"
href="data:image/x-icon;base64,AA"
/>
<Meta />
<Links />
</head>
<body>
<h1>Hello world!</h1>
<Outlet />
<Scripts />
</body>
</html>
);
}
¥Build and Run
首先，你需要在 package.json 中将类型指定为 module，以满足 remix-run 和未来 vite 版本的 ESModule 要求。
¥First you will need to specify the type as module in package.json to satisfy esmodule requirements for remix-run and future versions of vite.
{
"type": "module"
// ...
}
接下来构建生产环境的应用：
¥Next build the app for production:
npx remix vite:build
现在你应该看到一个 build 文件夹，其中包含一个 server 文件夹（你的应用的服务器版本）和一个 client 文件夹（浏览器版本），其中包含一些构建工件。（这全是 configurable。）
¥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.)
👉 使用 remix-serve 运行应用
¥👉 Run the app with remix-serve
现在你可以使用 remix-serve 运行你的应用了：
¥Now you can run your app with remix-serve:
# note the dash!
npx remix-serve build/server/index.js
你应该能够打开 [http://localhost:3000]http-localhost-3000 并看到 "你好，世界" 页面。
¥You should be able to open up http://localhost:3000 and see the "hello world" page.
除了 node_modules 中大量的代码外，我们的 Remix 应用只有三个文件：
¥Aside from the unholy amount of code in node_modules, our Remix app is just three files:
├── app/
│ └── root.jsx
├── package.json
└── vite.config.js
¥Bring Your Own Server
remix vite:build 创建的 build/server 目录只是一个在服务器（例如 Express、Cloudflare Workers、Netlify、Vercel、Fastly、AWS、Deno、Azure、Fastify、Firebase 等）内运行的模块。任何地方。
¥The build/server directory created by remix vite:build is just a module that you run inside a server like Express, Cloudflare Workers, Netlify, Vercel, Fastly, AWS, Deno, Azure, Fastify, Firebase, ... anywhere.
如果你不想设置自己的服务器，可以使用 remix-serve。这是一个由 Remix 团队维护的基于 Express 的简单服务器。然而，Remix 专门设计用于在任何 JavaScript 环境中运行，因此你可以掌控自己的堆栈。预计许多（如果不是大多数）生产环境应用都会拥有自己的服务器。你可以在 运行时、适配器和堆栈 中阅读更多相关信息。
¥If you don't care to set up your own server, you can use remix-serve. It's a simple express-based server maintained by the Remix team. However, Remix 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. You can read more about this in Runtimes, Adapters, and Stacks.
为了好玩，我们还是别用 remix-serve 了，改用 express 吧。
¥Just for kicks, let's stop using remix-serve and use express instead.
👉 安装 Express、Remix Express 适配器和 cross-env，以便在生产模式下运行
¥👉 Install Express, the Remix Express adapter, and cross-env for running in production mode
npm i express@4 @remix-run/express cross-env
# not going to use this anymore
npm uninstall @remix-run/serve
👉 创建 Express 服务器
¥👉 Create an Express server
touch server.js
import { createRequestHandler } from "@remix-run/express";
import express from "express";
// notice that the result of `remix vite:build` is "just a module"
import * as build from "./build/server/index.js";
const app = express();
app.use(express.static("build/client"));
// and your app is "just a request handler"
app.all("*", createRequestHandler({ build }));
app.listen(3000, () => {
console.log("App listening on http://localhost:3000");
});
👉 使用 express 运行应用
¥👉 Run your app with express
node server.js
现在你拥有了自己的服务器，就可以使用服务器提供的任何工具来调试应用了。例如，你可以使用 Chrome DevTools 使用 Node.js 检查标志 检查你的应用：
¥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 with the Node.js inspect flag:
node --inspect server.js
¥Development Workflow
无需反复停止、重建和启动服务器，你可以在开发环境中使用 Vite 中间件模式 运行 Remix。这使得使用 React Refresh（热模块替换）和 Remix 热数据重新验证，可以即时反馈应用中的更改。
¥Instead of stopping, rebuilding, and starting your server all the time, you can run Remix in development using Vite in middleware mode. This enables instant feedback to changes in your app with React Refresh (Hot Module Replacement) and Remix Hot Data Revalidation.
首先，为了方便起见，在 package.json 中添加 dev 和 start 命令，分别用于在开发和生产模式下运行服务器：
¥First, as a convenience, add dev and start commands in package.json that will run your server in development and production modes respectively:
👉 将 "scripts" 条目添加到 package.json
¥👉 Add a "scripts" entry to package.json
{
"scripts": {
"dev": "node ./server.js",
"start": "cross-env NODE_ENV=production node ./server.js"
}
// ...
}
👉 将 Vite 开发中间件添加到你的服务器。
¥👉 Add Vite development middleware to your server
如果 process.env.NODE_ENV 设置为 "production"，则 Vite 中间件将不适用，在这种情况下，你仍将像之前一样运行常规构建输出。
¥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.
import { createRequestHandler } from "@remix-run/express";
import express from "express";
const viteDevServer =
process.env.NODE_ENV === "production"
? null
: await import("vite").then((vite) =>
vite.createServer({
server: { middlewareMode: true },
})
);
const app = express();
app.use(
viteDevServer
? viteDevServer.middlewares
: express.static("build/client")
);
const build = viteDevServer
? () =>
viteDevServer.ssrLoadModule(
"virtual:remix/server-build"
)
: await import("./build/server/index.js");
app.all("*", createRequestHandler({ build }));
app.listen(3000, () => {
console.log("App listening on http://localhost:3000");
});
👉 启动开发服务器
¥👉 Start the dev server
npm run dev
现在你可以立即处理你的应用并获得反馈了。试试看，修改 root.jsx 中的文本，然后观察！
¥Now you can work on your app with immediate feedback. Give it a try, change the text in root.jsx and watch!
¥Controlling Server and Browser Entries
Remix 使用默认的魔法文件，大多数应用无需处理，但如果你想自定义 Remix 的服务器和浏览器入口点，你可以运行 remix reveal，它们会被转储到你的项目中。
¥There are default magic files Remix is using that most apps don't need to mess with, but if you want to customize Remix's entry points to the server and browser you can run remix reveal and they'll get dumped into your project.
npx remix reveal
Entry file entry.client created at app/entry.client.tsx.
Entry file entry.server created at app/entry.server.tsx.
¥Summary
恭喜，你可以将 Remix 添加到你的简历中！总结一下，我们了解到：
¥Congrats, you can add Remix to your resume! Summing things up, we've learned:
Remix 将你的应用编译为两种形式：
¥Remix compiles your app into two things:
添加到你自己的 JavaScript 服务器的请求处理程序
¥A request handler that you add to your own JavaScript server
浏览器公共目录中的一堆静态资源
¥A pile of static assets in your public directory for the browser
你可以携带自己的服务器和适配器，部署到任何地方。
¥You can bring your own server with adapters to deploy anywhere
你可以设置内置 HMR 的开发工作流程
¥You can set up a development workflow with HMR built-in
总的来说，Remix 有点像 "大胆尝试"。只需几分钟的样板代码，现在你就拥有了自己的技术栈。
¥In general, Remix is a bit "guts out". A few minutes of boilerplate but now you own your stack.
下一步是什么？
¥What's next?
