Remix 扁平路由

此包使您可以使用 flat-routes 约定来定义路由。它基于 Ryan Florence 的 gist。

💡 React Router v7 支持

React Router v7 使用新的路由配置。为了简化从 Remix 的迁移，该团队发布了一个适配器包，该包将把现有的基于 Remix 文件的路由转换为新的配置格式。

要使用现有的基于文件的路由，请安装适配器并更新 routes.ts 来包装您的适配器。

npm install -D @react-router/remix-config-routes-adapter
npm install -D remix-flat-routes

// app/routes.ts
import { remixConfigRoutes } from "@react-router/remix-config-routes-adapter";
import { flatRoutes } from "remix-flat-routes";

export const routes = remixConfigRoutes((defineRoutes) => {
  return flatRoutes("routes", defineRoutes, {/* options */});
});

✨🎉 v0.5.0 中的新功能

Remix v2 扁平路由约定

remix-flat-routes 是扁平路由规范的最初实现。我根据用户反馈添加了一些增强功能。当 Remix v2 将扁平路由约定添加为默认值时，他们只使用了原始规范。

如果您想要混合路由、扩展的路由文件名、自定义参数前缀等增强功能，您将需要继续使用此包。

remix-flat-routes 将始终保持与默认 Remix 约定的兼容性。此包只是核心约定的超集/扩展。

注意：像 Kent C. Dodds 的 Epic Stack 这样的热门项目使用了 remix-flat-routes

混合路由

您现在可以使用嵌套文件夹作为路由名称，同时仍然保留扁平路由的同位置功能。

如果您有一个大型应用程序，路由嵌套多层并不罕见。使用默认的扁平路由，文件夹名称就是整个路由路径：some.really.long.route.edit/index.tsx

通常，您可能有多个父布局，如 _public 或 admin。您可以创建顶层文件夹，然后在它们下面嵌套您的路由，而不是必须在每个路由中重复名称。这样，您仍然可以利用带有同位置的扁平文件夹。

之前

❯ tree app/routes-folders
app/routes-folders
├── _index
│   └── page.tsx
├── _public
│   └── _layout.tsx
├── _public.about
│   └── index.tsx
├── _public.contact[.jpg]
│   └── index.tsx
├── test.$
│   ├── _route.server.tsx
│   └── _route.tsx
├── users
│   ├── _layout.tsx
│   └── users.css
├── users.$userId
│   ├── _route.tsx
│   └── avatar.png
├── users.$userId_.edit
│   └── _route.tsx
└── users._index
    └── index.tsx

之后

❯ tree app/routes-hybrid
app/routes-hybrid
├── _index
│   └── index.tsx
├── _public
│   ├── _layout.tsx
│   ├── about
│   │   └── _route.tsx
│   └── contact[.jpg]
│       └── _route.tsx
├── test.$
│   └── _route.tsx
└── users
    ├── $userId
    │   ├── _route.tsx
    │   └── avatar.png
    ├── $userId_.edit
    │   └── _route.tsx
    ├── _index
    │   └── index.tsx
    ├── _layout.tsx
    └── users.css

带有 flat-files 约定的嵌套文件夹（✨ v0.5.1 中的新功能）

要创建一个文件夹但将其视为扁平文件，只需在文件夹名称后附加 +。

_auth+/forgot-password.tsx => _auth.forgot-password.tsx

注意：您可以在文件夹中包含 _layout.tsx 文件。您不需要有 _public.tsx 或 users.tsx 文件。

您仍然可以使用扁平文件夹进行同位置。因此，这是两种格式的最佳结合。

❯ tree app/routes-hybrid-files/
app/routes-hybrid-files/
├── _auth+
│   ├── forgot-password.tsx
│   └── login.tsx
├── _public+
│   ├── _layout.tsx
│   ├── about.tsx
│   ├── contact[.jpg].tsx
│   └── index.tsx
├── project+
│   ├── _layout.tsx
│   ├── parent.child
│   │   └── index.tsx
│   └── parent.child.grandchild
│       ├── index.tsx
│       └── styles.css
└── users+
    ├── $userId.tsx
    ├── $userId_.edit.tsx
    ├── _layout.tsx
    └── index.tsx

<Routes>
  <Route file="root.tsx">
    <Route
      path="forgot-password"
      file="routes-hybrid-files/_auth+/forgot-password.tsx"
    />
    <Route path="login" file="routes-hybrid-files/_auth+/login.tsx" />
    <Route file="routes-hybrid-files/_public+/_layout.tsx">
      <Route path="about" file="routes-hybrid-files/_public+/about.tsx" />
      <Route
        path="contact.jpg"
        file="routes-hybrid-files/_public+/contact[.jpg].tsx"
      />
      <Route index file="routes-hybrid-files/_public+/index.tsx" />
    </Route>
    <Route path="project" file="routes-hybrid-files/project+/_layout.tsx">
      <Route
        path="parent/child"
        file="routes-hybrid-files/project+/parent.child/index.tsx"
      >
        <Route
          path="grandchild"
          file="routes-hybrid-files/project+/parent.child.grandchild/index.tsx"
        />
      </Route>
    </Route>
    <Route path="users" file="routes-hybrid-files/users+/_layout.tsx">
      <Route path=":userId" file="routes-hybrid-files/users+/$userId.tsx" />
      <Route
        path=":userId/edit"
        file="routes-hybrid-files/users+/$userId_.edit.tsx"
      />
      <Route index file="routes-hybrid-files/users+/index.tsx" />
    </Route>
  </Route>
</Routes>

扩展的路由文件名

除了标准的 index | route | page | layout 名称之外，任何具有 _ 前缀的文件都将被视为路由文件。这将更容易找到特定的路由，而不是浏览一堆 route.tsx 文件。这受到了 SolidStart "重命名索引" 功能的启发。

所以，而不是

_public.about/route.tsx
_public.contact/route.tsx
_public.privacy/route.tsx

您可以将其命名为

_public.about/_about.tsx
_public.contact/_contact.tsx
_public.privacy/_privacy.tsx

多个路由文件夹

您现在可以传递除了默认 routes 文件夹之外的其他路由文件夹。这些路由将合并到一个命名空间中，因此您可以在一个文件夹中拥有路由，这些路由将使用另一个文件夹中的共享路由。

自定义参数前缀

您可以覆盖默认的参数前缀 $。一些 shell 使用 $ 前缀作为变量，这可能会由于 shell 扩展而出现问题。使用任何有效的字符作为文件名，例如：^

users.^userId.tsx  => users/:userId
test.^.tsx         => test/*

自定义基本路径

您可以覆盖默认的基本路径 /。这会将您的基本路径添加到根路径。

可选路由段

React Router 将为可选路由段引入一项新功能。要在扁平路由中使用可选段，只需将您的路由名称包装在 () 中。

parent.(optional).tsx   => parent/optional?

自定义应用程序目录

您可以覆盖默认的应用程序目录 app。

🛠 安装

npm install -D remix-flat-routes

⚙️ 配置

更新您的 *remix.config.js* 文件并使用自定义路由配置选项。

const { flatRoutes } = require('remix-flat-routes')

/**
 * @type {import("@remix-run/dev").AppConfig}
 */
module.exports = {
  // ignore all files in routes folder to prevent
  // default remix convention from picking up routes
  ignoredRouteFiles: ['**/*'],
  routes: async defineRoutes => {
    return flatRoutes('routes', defineRoutes)
  },
}

API

function flatRoutes(
  routeDir: string | string[],
  defineRoutes: DefineRoutesFunction,
  options: FlatRoutesOptions,
)

type FlatRoutesOptions = {
  appDir?: string // optional app directory (defaults to app)
  basePath?: string // optional base path (default is '/')
  paramPrefixChar?: string // optional param prefix (default is '$')
  ignoredRouteFiles?: string[] // optional files to ingore as routes (same as Remix config option)
  visitFiles?: VisitFilesFunction // optional visitor (useful for tests to provide files without file system)
}

注意：routeDir 应该相对于 app 文件夹。如果要使用 routes 文件夹，您将需要更新 ignoredRouteFiles 属性以忽略所有文件：**/*

🔨 扁平路由约定

示例（扁平文件）

routes/
  _auth.forgot-password.tsx
  _auth.login.tsx
  _auth.reset-password.tsx
  _auth.signup.tsx
  _auth.tsx
  _landing.about.tsx
  _landing.index.tsx
  _landing.tsx
  app.calendar.$day.tsx
  app.calendar.index.tsx
  app.calendar.tsx
  app.projects.$id.tsx
  app.projects.tsx
  app.tsx
  app_.projects.$id.roadmap.tsx
  app_.projects.$id.roadmap[.pdf].tsx

作为 React Router 路由

<Routes>
  <Route element={<Auth />}>
    <Route path="forgot-password" element={<Forgot />} />
    <Route path="login" element={<Login />} />
    <Route path="reset-password" element={<Reset />} />
    <Route path="signup" element={<Signup />} />
  </Route>
  <Route element={<Landing />}>
    <Route path="about" element={<About />} />
    <Route index element={<Index />} />
  </Route>
  <Route path="app" element={<App />}>
    <Route path="calendar" element={<Calendar />}>
      <Route path=":day" element={<Day />} />
      <Route index element={<CalendarIndex />} />
    </Route>
    <Route path="projects" element={<Projects />}>
      <Route path=":id" element={<Project />} />
    </Route>
  </Route>
  <Route path="app/projects/:id/roadmap" element={<Roadmap />} />
  <Route path="app/projects/:id/roadmap.pdf" />
</Routes>

单独解释

嵌套布局

默认匹配

默认情况下，flat-routes 会将当前路由嵌套到具有最长匹配前缀的父布局中。

给定布局路由 app.calendar.tsx，以下路由将嵌套在 app.calendar.tsx 下，因为 app.calendar 是最长的匹配前缀。

• app.calendar.index.tsx
• app.calendar.$day.tsx

覆盖匹配

有时您想使用路由层次结构中较高的父布局。使用默认的 Remix 约定，您将使用点（.）表示法而不是嵌套文件夹。使用 flat-routes，由于路由文件始终使用点，因此有一个不同的约定来指定要嵌套在哪个布局下。

假设您有一个 app.tsx 布局，并且您有一个不想与该布局共享的路由，而是想与 root.tsx 匹配。要覆盖默认的父匹配，请在要嵌套在其下的路由的直接子段后附加一个尾随下划线（_）。

app_.projects.$id.roadmap.tsx 将嵌套在 root 下，因为没有匹配的路由

• ❌ app_.projects.$id.tsx
• ❌ app_.projects.tsx
• ❌ app_.tsx
• ✅ root.tsx

约定

注意：索引路由的下划线前缀是可选的，但有助于将文件排序到目录列表的顶部。

理由

• 更容易查看应用程序定义的路由 - 只需打开 "routes/"，它们都在那里。由于文件系统通常先对文件夹进行排序，当您有数十个路由时，很难看到哪些文件夹具有布局，哪些没有。现在，所有相关的路由都排序在一起。

• 减少重构/重新设计的摩擦 - 虽然代码编辑器在您移动文件时非常擅长修复导入，并且 Remix 具有 "~" 导入别名，但重构没有一堆嵌套文件夹的代码库通常更容易。Remix 不再强制执行此操作。

  此外，在重新设计用户界面时，调整文件名称比创建/删除文件夹并移动路由来更改它们的嵌套方式更简单。

• 帮助应用迁移到 Remix - 现有的应用程序通常没有像现在约定俗成的嵌套路由文件夹结构。迁移到 Remix 很困难，因为你必须处理所有的导入。

并置

虽然示例中只使用了文件，但它们实际上只是“导入路径”。因此，你可以为路由创建一个文件夹，并且会导入 `index` 文件，从而使路由的所有模块彼此并存。这与上面详细介绍的 *扁平文件* 约定相反，是一种 *扁平文件夹* 约定。

示例 (扁平文件夹)

routes/
  _auth.forgot-password.tsx
  _auth.login.tsx
  _auth.tsx
  _landing.about.tsx
  _landing.index.tsx
  _landing.tsx
  app.projects.tsx
  app.projects.$id.tsx
  app.tsx
  app_.projects.$id.roadmap.tsx

每个路由都变成一个文件夹，文件夹名称为路由名称去掉文件扩展名。路由文件然后被命名为 *index.tsx*。

所以 *app.projects.tsx* 变为 *app.projects/index.tsx*

routes/
  _auth/
    index.tsx x <- route file (same as _auth.tsx)
  _auth.forgot-password/
    index.tsx  <- route file (same as _auth.forgot-password.tsx)
  _auth.login/
    index.tsx   <- route files (same as _auth.login.tsx)
  _landing.about/
    index.tsx   <- route file (same as _landing.about.tsx)
    employee-profile-card.tsx
    get-employee-data.server.tsx
    team-photo.jpg
  _landing.index/
    index.tsx   <- route file (same as _landing.index.tsx)
    scroll-experience.tsx
  _landing/
    index.tsx   <- route file (same as _landing.tsx)
    header.tsx
    footer.tsx
  app/
    index.tsx   <- route file (same as app.tsx)
    primary-nav.tsx
    footer.tsx
  app_.projects.$id.roadmap/
    index.tsx   <- route file (same as app_.projects.$id.roadmap.tsx)
    chart.tsx
    update-timeline.server.tsx
  app.projects/
    index.tsx <- layout file (sames as app.projects.tsx)
    project-card.tsx
    get-projects.server.tsx
    project-buttons.tsx
  app.projects.$id/
    index.tsx  <- route file (sames as app.projects.$id.tsx)

别名

由于路由文件现在命名为 *index.tsx*，并且你可以在同一个路由文件夹中并置其他文件，因此 *index.tsx* 文件可能会在文件列表中迷失。你还可以为 *index.tsx* 使用以下别名。下划线前缀会将文件排序到目录列表的顶部。

• _index.tsx
• _layout.tsx
• _route.tsx

注意：*_layout.tsx* 和 *_route.tsx* 文件只是对其作用更加明确。它们与 *index.tsx* 的工作方式相同。

与扁平文件一样，索引路由（不要与索引路由*文件*混淆）也可以使用下划线前缀。路由 `_landing.index` 可以保存为 `_landing.index/index.tsx` 或 `_landing._index/_index.tsx`。

这有点主观，但我认为这最终是大多数开发人员会喜欢的。每个路由都变成它自己的“迷你应用”，所有依赖项都在一起。使用 `ignoredRouteFiles` 选项，完全不清楚哪些文件是路由，哪些不是。

🚚 迁移现有路由

你现在可以将现有的路由迁移到新的 `flat-routes` 约定。只需运行

npx migrate-flat-routes <sourceDir> <targetDir> [options]

Example:
  npx migrate-flat-routes ./app/routes ./app/flatroutes --convention=flat-folders

NOTE:
  sourceDir and targetDir are relative to project root

Options:
  --convention=<convention>
    The convention to use when migrating.
      flat-files - Migrates to flat files
      flat-folders - Migrates to flat directories with route.tsx files
      hybrid - Keep folder structure with '+' suffix and _layout files
  --force
    Overwrite target directory if it exists

😍 贡献者

感谢这些优秀的人们（表情符号键）

Kiliman 💻 📖	Ryan Florence 📖	Brandon Pittman 📖 💻	Mehdi Achour 📖	Fidel González 📖	Andrew Haines 💻	Wonu Lee 💻
Markus Wolf 💻	Sarat Chandra Balla 💻

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！