代码分割

代码分割和按需加载是提高应用程序捆绑包大小和加载性能的强大技术。

减少初始页面加载时需要加载的代码量
代码在需要时按需加载
产生更多更小的代码块，浏览器更容易缓存。

TanStack Router 如何进行代码分割？

TanStack Router 将代码分为两类

关键路由配置 - 渲染当前路由并尽可能早地启动数据加载过程所需的代码。
- 路径解析/序列化
- 搜索参数验证
- 加载器，加载前
- 路由上下文
- 静态数据
- 链接
- 脚本
- 样式
- 未列出的所有其他路由配置
非关键/延迟路由配置 - 匹配路由不需要的代码，可以按需加载。
- 路由组件
- 错误组件
- 加载中组件
- 未找到组件

🧠 为什么加载器不分割？

加载器本身就是一个异步边界，因此您需要支付双倍的成本才能获取代码块并等待加载器执行。

从分类上讲，它比组件对大型捆绑包大小的贡献可能性较小。

加载器是路由最重要的预加载资产之一，特别是如果您使用默认的预加载意图（例如悬停在链接上），因此加载器在没有任何额外异步开销的情况下可用非常重要。

了解分割加载器的缺点后，如果您仍然想继续，请前往数据加载器分割部分。

将路由文件封装到目录中

由于 TanStack Router 的基于文件的路由系统旨在支持扁平文件结构和嵌套文件结构，因此可以在没有任何额外配置的情况下将路由文件封装到单个目录中。

要将路由的文件封装到目录中，请将路由文件本身移动到与路由文件同名的目录中的 .route 文件中。

例如，如果您有一个名为 posts.tsx 的路由文件，您将创建一个名为 posts 的新目录，并将 posts.tsx 文件移动到该目录中，并将其重命名为 route.tsx。

之前

posts.tsx

之后

posts
- route.tsx

代码分割的方法

TanStack Router 支持多种代码分割方法。如果您使用的是基于代码的路由，请跳到基于代码的分割部分。

当您使用基于文件的路由时，可以使用以下方法进行代码分割

使用自动代码分割 ✨
使用 .lazy.tsx 后缀
使用虚拟路由

使用自动代码分割✨

这是代码分割路由文件最简单、最强大的方法。

使用 autoCodeSplitting 功能时，TanStack Router 将根据上面提到的非关键路由配置自动分割您的路由文件。

重要

自动代码分割功能仅在您使用基于文件的路由和我们的支持的捆绑器之一时可用。如果您仅使用 CLI (@tanstack/router-cli)，这将不起作用。

要启用自动代码分割，您只需在 TanStack Router Bundler 插件的配置中添加以下内容

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      // ...
      autoCodeSplitting: true,
    }),
    react(), // Make sure to add this plugin after the TanStack Router Bundler plugin
  ],
})

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      // ...
      autoCodeSplitting: true,
    }),
    react(), // Make sure to add this plugin after the TanStack Router Bundler plugin
  ],
})

就是这样！TanStack Router 将根据其关键和非关键路由配置自动分割所有路由文件。

如果您希望对代码分割过程有更多控制，请前往自动代码分割指南了解更多可用选项。

使用 .lazy.tsx 后缀

如果您无法使用自动代码分割功能，您仍然可以使用 .lazy.tsx 后缀分割路由文件。它只需将您的代码移动到带有 .lazy.tsx 后缀的单独文件中，并使用 createLazyFileRoute 函数而不是 createFileRoute 即可轻松实现。

重要

无论是使用 createRootRoute 还是 createRootRouteWithContext，__root.tsx 路由文件都不支持代码分割，因为它总是被渲染，无论当前路由是什么。

这些是 createLazyFileRoute 支持的唯一选项

导出名称	描述
component	用于渲染路由的组件。
errorComponent	在加载路由时发生错误时渲染的组件。
pendingComponent	在路由加载时渲染的组件。
notFoundComponent	如果抛出未找到错误，则渲染的组件。

使用 .lazy.tsx 进行代码分割的示例

当您使用 .lazy.tsx 时，您可以将路由拆分为两个文件以启用代码分割

之前（单个文件）

tsx

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
  component: Posts,
})

function Posts() {
  // ...
}

之后（拆分为两个文件）

此文件将包含关键路由配置

tsx

// src/routes/posts.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
})

// src/routes/posts.tsx

import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from './api'

export const Route = createFileRoute('/posts')({
  loader: fetchPosts,
})

非关键路由配置将放入带有 .lazy.tsx 后缀的文件中

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

使用虚拟路由

您可能会遇到将所有内容从路由文件中拆分出去，导致其为空的情况！在这种情况下，只需完全删除路由文件！将自动为您生成一个虚拟路由，作为代码分割文件的锚点。此虚拟路由将直接存在于生成的路由树文件中。

之前（虚拟路由）

tsx

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  // Hello?
})

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  // Hello?
})

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

之后（虚拟路由）

tsx

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

// src/routes/posts.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/posts')({
  component: Posts,
})

function Posts() {
  // ...
}

嗒哒！🎉

基于代码的分割

如果您正在使用基于代码的路由，您仍然可以使用 Route.lazy() 方法和 createLazyRoute 函数来分割您的路由。您需要将路由配置拆分为两部分

使用 createLazyRoute 函数创建一个延迟路由。

tsx

// src/posts.lazy.tsx
export const Route = createLazyRoute('/posts')({
  component: MyComponent,
})

function MyComponent() {
  return <div>My Component</div>
}

// src/posts.lazy.tsx
export const Route = createLazyRoute('/posts')({
  component: MyComponent,
})

function MyComponent() {
  return <div>My Component</div>
}

然后，在您的 app.tsx 中调用路由定义上的 .lazy 方法，以导入带有非关键路由配置的延迟/代码分割路由。

tsx

// src/app.tsx
const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
}).lazy(() => import('./posts.lazy').then((d) => d.Route))

// src/app.tsx
const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
}).lazy(() => import('./posts.lazy').then((d) => d.Route))

数据加载器分割

请注意！！！ 分割路由加载器是一项危险的操作。

它可能是减少捆绑包大小的强大工具，但正如TanStack Router 如何进行代码分割？部分所述，它会带来一定的成本。

您可以使用路由的 loader 选项来分割数据加载逻辑。虽然这个过程使得难以保持传递给加载器的参数的类型安全，但您始终可以使用通用 LoaderContext 类型来完成大部分工作

tsx

import { lazyFn } from '@tanstack/react-router'

const route = createRoute({
  path: '/my-route',
  component: MyComponent,
  loader: lazyFn(() => import('./loader'), 'loader'),
})

// In another file...a
export const loader = async (context: LoaderContext) => {
  /// ...
}

import { lazyFn } from '@tanstack/react-router'

const route = createRoute({
  path: '/my-route',
  component: MyComponent,
  loader: lazyFn(() => import('./loader'), 'loader'),
})

// In another file...a
export const loader = async (context: LoaderContext) => {
  /// ...
}

如果您使用的是基于文件的路由，则只有在使用带有自定义捆绑选项的自动代码分割时才能分割您的 loader。

使用 getRouteApi 辅助函数在其他文件中手动访问路由 API

您可能已经猜到，将组件代码放在与路由分开的文件中会使其难以使用路由本身。为了解决这个问题，TanStack Router 导出一个方便的 getRouteApi 函数，您可以使用它在不导入路由本身的情况下访问文件中路由的类型安全 API。

my-route.tsx

tsx

import { createRoute } from '@tanstack/react-router'
import { MyComponent } from './MyComponent'

const route = createRoute({
  path: '/my-route',
  loader: () => ({
    foo: 'bar',
  }),
  component: MyComponent,
})

import { createRoute } from '@tanstack/react-router'
import { MyComponent } from './MyComponent'

const route = createRoute({
  path: '/my-route',
  loader: () => ({
    foo: 'bar',
  }),
  component: MyComponent,
})

MyComponent.tsx

tsx

import { getRouteApi } from '@tanstack/react-router'

const route = getRouteApi('/my-route')

export function MyComponent() {
  const loaderData = route.useLoaderData()
  //    ^? { foo: string }

  return <div>...</div>
}

import { getRouteApi } from '@tanstack/react-router'

const route = getRouteApi('/my-route')

export function MyComponent() {
  const loaderData = route.useLoaderData()
  //    ^? { foo: string }

  return <div>...</div>
}

getRouteApi 函数对于访问其他类型安全 API很有用

useLoaderData
useLoaderDeps
useMatch
useParams
useRouteContext
useSearch