快速開始

剛開始使用 Remix 嗎？最新版本的 Remix 現在是 React Router v7。如果您想使用最新功能，應該使用 React Router 文件來開始。

本指南將讓您熟悉盡快執行 Remix 應用程式所需的基本架構。雖然有許多具有不同執行階段、部署目標和資料庫的入門範本，但我們將從頭開始建立一個簡陋的專案。

當您準備好認真對待您的 Remix 專案時，您可以考慮從社群範本開始。它們包括 TypeScript 設定、資料庫、測試框架、身份驗證等等。您可以在 Remix 資源頁面上找到社群範本的清單。

安裝

如果您希望初始化一個包含所有功能的 Remix 專案，可以使用 create-remix CLI

npx create-remix@latest

但是，本指南將說明 CLI 為設定您的專案所做的所有事情，並且您可以按照這些步驟而不是使用 CLI。如果您剛開始使用 Remix，我們建議您遵循本指南來了解組成 Remix 應用程式的所有不同部分。

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 react-dom

# install dev dependencies
npm i -D @remix-run/dev vite

Vite 配置

touch vite.config.js

由於 Remix 使用 Vite，您需要提供一個包含 Remix Vite 外掛程式的 Vite 設定。以下是您需要的基本設定

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [remix()],
});

根路由

mkdir app
touch app/root.jsx

app/root.jsx 是我們所謂的「根路由」。它是整個應用程式的根佈局。以下是您任何專案都需要的基本元素集

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>
  );
}

建置與執行

首先建置應用程式以用於生產環境

npx remix vite:build

您現在應該會看到一個 build 資料夾，其中包含一個 server 資料夾（應用程式的伺服器版本）和一個 client 資料夾（瀏覽器版本），其中有一些建置成品。（這些都是可配置的。）

👉 使用 remix-serve 執行應用程式

首先，您需要在 package.json 中將類型指定為模組，以便 remix-serve 可以執行您的應用程式。

{
  "type": "module"
  // ...
}

現在您可以使用 remix-serve 執行您的應用程式

# note the dash!
npx remix-serve build/server/index.js

您應該可以打開 https://127.0.0.1:3000 並看到「hello world」頁面。

除了 node_modules 中大量的程式碼之外，我們的 Remix 應用程式只有一個檔案

├── app/
│   └── root.jsx
└── package.json
└── vite.config.js

自備伺服器

remix vite:build 建立的 build/server 目錄只是一個模組，您可以在 Express、Cloudflare Workers、Netlify、Vercel、Fastly、AWS、Deno、Azure、Fastify、Firebase 等伺服器中執行它。

如果您不想設定自己的伺服器，可以使用 remix-serve。它是一個由 Remix 團隊維護的簡單基於 Express 的伺服器。但是，Remix 專門設計為在任何 JavaScript 環境中執行，以便您擁有自己的堆疊。預計許多（如果不是大多數）生產應用程式都會有自己的伺服器。您可以在執行階段、配接器和堆疊中閱讀更多相關資訊。

只是為了好玩，讓我們停止使用 remix-serve 並改用 express。

👉 安裝 Express、Remix Express 配接器和 cross-env 以在生產模式下執行

npm i express @remix-run/express cross-env

# not going to use this anymore
npm uninstall @remix-run/serve

👉 建立一個 Express 伺服器

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 https://127.0.0.1:3000");
});

👉 使用 express 執行您的應用程式

node server.js

現在您已經擁有自己的伺服器，您可以使用伺服器上的任何工具來除錯您的應用程式。例如，您可以使用 Chrome 開發者工具以及 Node.js 的 inspect flag 來檢查您的應用程式。

node --inspect server.js

開發工作流程

您可以不用一直停止、重新建置並啟動伺服器，而是使用 Vite 的中介軟體模式來在開發環境中執行 Remix。這讓您可以透過 React Refresh（熱模組替換）和 Remix 熱資料重新驗證，即時獲得應用程式變更的回饋。

首先，為了方便起見，請在 package.json 中加入 dev 和 start 指令，以便分別在開發和生產模式下執行您的伺服器。

👉 在 package.json 中加入 "scripts" 項目

{
  "scripts": {
    "dev": "node ./server.js",
    "start": "cross-env NODE_ENV=production node ./server.js"
  }
  // ...
}

👉 將 Vite 開發中介軟體加入到您的伺服器

如果 process.env.NODE_ENV 設定為 "production"，則不會套用 Vite 中介軟體，在這種情況下，您仍然會像之前一樣執行常規的建置輸出。

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 https://127.0.0.1:3000");
});

👉 啟動開發伺服器

npm run dev

現在您可以立即獲得回饋來開發您的應用程式。試試看，更改 root.jsx 中的文字，然後觀察結果！

控制伺服器和瀏覽器入口

Remix 正在使用一些大多數應用程式不需要修改的預設神奇檔案，但是如果您想要自訂 Remix 的伺服器和瀏覽器入口點，您可以執行 remix reveal，它們就會被傾印到您的專案中。

npx remix reveal

Entry file entry.client created at app/entry.client.tsx.
Entry file entry.server created at app/entry.server.tsx.

總結

恭喜，您可以將 Remix 加入到您的履歷中了！總而言之，我們已經學會了：

Remix 會將您的應用程式編譯成兩個東西：
- 一個您添加到自己的 JavaScript 伺服器的請求處理器
- 一堆位於您 public 目錄中，供瀏覽器使用的靜態資源
您可以使用適用於任何部署環境的轉接器來攜帶您自己的伺服器
您可以設定一個內建 HMR 的開發工作流程

總的來說，Remix 有點像是「內臟外露」。只需幾分鐘的樣板程式碼，您就可以掌控自己的堆疊。

下一步是什麼？

教學