代码分割

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

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

TanStack Router 如何分割代码？

TanStack Router 将代码分为两类

关键路由配置 - 渲染当前路由并尽早启动数据加载过程所需的代码。
- 路径解析/序列化
- 搜索参数验证
- Loaders, Before Load
- 路由上下文
- 静态数据
- Links
- Scripts
- Styles
- 所有未在下面列出的其他路由配置
非关键/延迟路由配置 - 不需要匹配路由，可以按需加载的代码。
- 路由组件
- 错误组件
- Pending 组件
- Not-found 组件

🧠 为什么不分割 loader？

Loader 已经是一个异步边界，因此您需要双倍的代价来获取代码块并等待 loader 执行。

从类别上讲，与组件相比，它不太可能导致包大小过大。

Loader 是路由最重要的可预加载资源之一，特别是如果您使用默认的预加载意图（例如悬停在链接上），因此 loader 必须可用，而无需任何额外的异步开销。

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

将路由文件封装到目录中

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

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

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

之前

posts.tsx

之后

posts
- route.tsx

代码分割的方法

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

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

使用自动代码分割✨

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

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

重要提示

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

要启用自动代码分割，您只需将以下内容添加到 TanStack Router 打包器插件的配置中

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

export default defineConfig({
  plugins: [
    TanStackRouterVite({
      // ...
      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 { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    TanStackRouterVite({
      // ...
      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。

重要提示

__root.tsx 路由文件（使用 createRootRoute 或 createRootRouteWithContext）不支持代码分割，因为它始终渲染，无论当前路由如何。

以下是 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.tsx
export const Route = createLazyRoute('/posts')({
  component: MyComponent,
})

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

// src/posts.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 选项来代码分割数据加载逻辑。虽然此过程使维护传递给 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