code-splitting — скилл для Claude Code: ленивая загрузка компонентов маршрутов
Скилл code-splitting разделяет код маршрутов TanStack Router на критичную и ленивую части: автоматически создаёт отдельные чанки или позволяет настроить разделение вручную.
MIT 212 установок ★ 15 341 обновлён 2026-10-25
npx skills add TanStack/router --skill code-splitting -a claude-codeЧто делает code-splitting
TanStack Router различает две части кода маршрута: критичную (парсинг пути, validateSearch, loader, контекст) и ленивую (компоненты, errorComponent, pendingComponent). Скилл включает автоматическое разделение (autoCodeSplitting: true) в плагин Vite, так что вся логика хранится в одном файле routes/posts.tsx, а компоненты автоматически выделяются в отдельный чанк.
Для CLI-приложений без плагина bundler'а работает ручное разделение: критичная часть в routes/posts.tsx, ленивая — в routes/posts.lazy.tsx с помощью createLazyFileRoute. Чтобы типизированные хуки работали в отдельных файлах, используй getRouteApi('/posts') — это даёт доступ к useLoaderData, useParams, useSearch без импорта самого объекта Route, который помешал бы сплиттингу.
Пер-маршрутные переопределения (codeSplitGroupings) позволяют объединить loader и component в один чанк, если отдельная загрузка даёт двойной async-штраф. Глобальная конфигурация defaultBehavior и splitBehavior в vite.config.ts помогают тонко настроить группировку по паттернам маршрутов. КРИТИЧНО: если компонент экспортирован обычной функцией, он попадёт в основной bundle и сплиттинг не сработает.
Какие задачи решает
- Разделить компоненты маршрутов в отдельные чанки без дублирования кода
- Оставить loader в основном bundle, чтобы маршрут загружался параллельно компоненту
- Получить типизированные хуки в файле
.lazy.tsxбез разрушения сплиттинга - Переопределить логику сплиттинга для отдельного маршрута или группы маршрутов
- Настроить автоматический сплиттинг в Vite или сделать ручное разделение для других bundler'ов
Примеры запросов агенту
- Включи автоматический code-splitting в
vite.config.ts: укажиautoCodeSplitting: trueв плагинеtanstackRouter - Используй
getRouteApi('/posts')в компоненте из файлаposts.lazy.tsxдля типизированного доступа кuseLoaderDataиuseParams - Объедини loader с компонентом в один чанк через
codeSplitGroupings: [['loader', 'component']]в маршруте с тяжёлой логикой
Как установить code-splitting
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill code-splitting -a claude-code2Вручную: положить файлы
~/.claude/skills/code-splitting/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/code-splitting/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill code-splitting -a codex2Вручную: положить файлы
.agents/skills/code-splitting/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill code-splitting -a cursor2Вручную: положить файлы
.cursor/skills/code-splitting/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/code-splitting2Вручную: положить файлы
.github/skills/code-splitting/SKILL.md1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill code-splitting -a gemini-cli2Командой платформы
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/code-splittingВручную: положить файлы
.devin/skills/code-splitting/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add TanStack/router --skill code-splitting -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о code-splitting
Как установить code-splitting в Claude Code?
Выполни npx skills add TanStack/router --skill code-splitting -a claude-code, затем обрати внимание на файл ~/.claude/skills/code-splitting/SKILL.md с полной инструкцией для твоего проекта.
Что делает code-splitting?
Разделяет код маршрутов на части: критичные (config, loader) остаются в основном bundle, ленивые (компоненты) загружаются отдельно. Это уменьшает размер начального bundle и ускоряет первый вывод страницы.
Почему компонент остаётся в основном bundle, если я его экспортировал?
Экспортированные функции-компоненты не сплиттятся — они становятся частью основного bundle автоматически. Оставь компонент как обычную функцию внутри файла маршрута или используй createLazyFileRoute в отдельном .lazy.tsx файле.
Исходный текст
SKILL.md · MIT
---
name: code-splitting
description: >-
Automatic code splitting (autoCodeSplitting), .lazy.tsx convention,
createLazyFileRoute, createLazyRoute, lazyRouteComponent, getRouteApi
for typed hooks in split files, codeSplitGroupings per-route override,
splitBehavior programmatic config, critical vs non-critical properties.
metadata:
type: sub-skill
library: tanstack-router
library_version: '1.171.15'
requires:
- router-core
sources:
- TanStack/router:docs/router/guide/code-splitting.md
- TanStack/router:docs/router/guide/automatic-code-splitting.md
---
# Code Splitting
TanStack Router separates route code into **critical** (required to match and start loading) and **non-critical** (can be lazy-loaded). The bundler plugin can split automatically, or you can split manually with `.lazy.tsx` files.
> **CRITICAL**: Never `export` component functions from route files — exported functions are included in the main bundle and bypass code splitting entirely.
> **CRITICAL**: Use `getRouteApi('/path')` in code-split files, NOT `import { Route } from './route'`. Importing Route defeats code splitting.
## What Stays in the Main Bundle (Critical)
- Path parsing/serialization
- `validateSearch`
- `loader`, `beforeLoad`
- Route context, static data
- Links, scripts, styles
## What Gets Split (Non-Critical)
- `component`
- `errorComponent`
- `pendingComponent`
- `notFoundComponent`
> The `loader` is NOT split by default. It is already async, so splitting it adds a double async cost: fetch the chunk, then execute the loader. Only split the loader if you have a specific reason.
## Setup: Automatic Code Splitting
Enable `autoCodeSplitting: true` in the bundler plugin. This is the recommended approach.
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
export default defineConfig({
plugins: [
// TanStack Router plugin MUST come before the framework plugin
tanstackRouter({
autoCodeSplitting: true,
}),
react(),
],
})
```
With this enabled, route files are automatically transformed. Components are split into separate chunks; loaders stay in the main bundle. No `.lazy.tsx` files needed.
```tsx
// src/routes/posts.tsx — everything in one file, splitting is automatic
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from '../api'
export const Route = createFileRoute('/posts')({
loader: fetchPosts,
component: PostsComponent,
})
// NOT exported — this is critical for automatic code splitting to work
function PostsComponent() {
const posts = Route.useLoaderData()
return (
<ul>
{posts.map((post) => (
<li key={post.id}>{post.title}</li>
))}
</ul>
)
}
```
## Manual Splitting with `.lazy.tsx`
If you cannot use automatic code splitting (e.g. CLI-only, no bundler plugin), split manually into two files:
```tsx
// src/routes/posts.tsx — critical route config only
import { createFileRoute } from '@tanstack/react-router'
import { fetchPosts } from '../api'
export const Route = createFileRoute('/posts')({
loader: fetchPosts,
})
```
```tsx
// src/routes/posts.lazy.tsx — non-critical (lazy-loaded)
import { createLazyFileRoute } from '@tanstack/react-router'
export const Route = createLazyFileRoute('/posts')({
component: PostsComponent,
})
function PostsComponent() {
// Use getRouteApi to access typed hooks without importing Route
return <div>Posts</div>
}
```
`createLazyFileRoute` supports only: `component`, `errorComponent`, `pendingComponent`, `notFoundComponent`.
## Virtual Routes
If splitting leaves the critical route file empty, delete it entirely. A virtual route is auto-generated in `routeTree.gen.ts`:
```tsx
// src/routes/about.lazy.tsx — no about.tsx needed
import { createLazyFileRoute } from '@tanstack/react-router'
export const Route = createLazyFileRoute('/about')({
component: () => <h1>About Us</h1>,
})
```
## Code-Based Splitting
For code-based (non-file-based) routing, use `createLazyRoute` and the `.lazy()` method:
```tsx
// src/posts.lazy.tsx
import { createLazyRoute } from '@tanstack/react-router'
export const Route = createLazyRoute('/posts')({
component: PostsComponent,
})
function PostsComponent() {
return <div>Posts</div>
}
```
```tsx
// src/app.tsx
import { createRoute } from '@tanstack/react-router'
const postsRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/posts',
}).lazy(() => import('./posts.lazy').then((d) => d.Route))
```
## Accessing Typed Hooks in Split Files: `getRouteApi`
When your component lives in a separate file, use `getRouteApi` to get typed access to route hooks without importing the Route object:
```tsx
// src/routes/posts.lazy.tsx
import { createLazyFileRoute, getRouteApi } from '@tanstack/react-router'
const routeApi = getRouteApi('/posts')
export const Route = createLazyFileRoute('/posts')({
component: PostsComponent,
})
function PostsComponent() {
const posts = routeApi.useLoaderData()
const { page } = routeApi.useSearch()
const params = routeApi.useParams()
const context = routeApi.useRouteContext()
return <div>Posts page {page}</div>
}
```
`getRouteApi` provides: `useLoaderData`, `useLoaderDeps`, `useMatch`, `useParams`, `useRouteContext`, `useSearch`.
## Per-Route Split Overrides: `codeSplitGroupings`
Override split behavior for a specific route by adding `codeSplitGroupings` directly in the route file:
```tsx
// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { loadPostsData } from './-heavy-posts-utils'
export const Route = createFileRoute('/posts')({
// Bundle loader and component together for this route
codeSplitGroupings: [['loader', 'component']],
loader: () => loadPostsData(),
component: PostsComponent,
})
function PostsComponent() {
const data = Route.useLoaderData()
return <div>{data.title}</div>
}
```
## Global Split Configuration
### `defaultBehavior` — Change Default Groupings
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
export default defineConfig({
plugins: [
tanstackRouter({
autoCodeSplitting: true,
codeSplittingOptions: {
defaultBehavior: [
// Bundle all UI components into one chunk
[
'component',
'pendingComponent',
'errorComponent',
'notFoundComponent',
],
],
},
}),
],
})
```
### `splitBehavior` — Programmatic Per-Route Logic
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
export default defineConfig({
plugins: [
tanstackRouter({
autoCodeSplitting: true,
codeSplittingOptions: {
splitBehavior: ({ routeId }) => {
if (routeId.startsWith('/posts')) {
return [['loader', 'component']]
}
// All other routes use defaultBehavior
},
},
}),
],
})
```
### Precedence Order
1. Per-route `codeSplitGroupings` (highest)
2. `splitBehavior` function
3. `defaultBehavior` option (lowest)
## Common Mistakes
### 1. HIGH: Exporting component functions prevents code splitting
```tsx
// WRONG — export puts PostsComponent in the main bundle
export function PostsComponent() {
return <div>Posts</div>
}
// CORRECT — no export, function stays in the split chunk
function PostsComponent() {
return <div>Posts</div>
}
```
### 2. MEDIUM: Trying to code-split the root route
`__root.tsx` does not support code splitting. It is always rendered regardless of the current route. Do not create `__root.lazy.tsx`.
### 3. MEDIUM: Splitting the loader adds double async cost
```tsx
// AVOID unless you have a specific reason
codeSplittingOptions: {
defaultBehavior: [
['loader'], // Fetch chunk THEN execute loader = two network waterfalls
['component'],
],
}
// PREFERRED — loader stays in main bundle (default behavior)
codeSplittingOptions: {
defaultBehavior: [
['component'],
['errorComponent'],
['notFoundComponent'],
],
}
```
### 4. HIGH: Importing Route in code-split files for typed hooks
```tsx
// WRONG — importing Route pulls route config into the lazy chunk
import { Route } from './posts.tsx'
const data = Route.useLoaderData()
// CORRECT — getRouteApi gives typed hooks without pulling in the route
import { getRouteApi } from '@tanstack/react-router'
const routeApi = getRouteApi('/posts')
const data = routeApi.useLoaderData()
```
## Cross-References
- **router-core/data-loading** — Loader splitting decisions affect data loading performance. Splitting the loader adds latency before data can be fetched.
- **router-core/type-safety** — `getRouteApi` is the type-safe way to access hooks from split files.
© TanStack · MIT · TanStack/router