Route-level code splitting
Split route bundles so component code loads only when a file-based route is matched.
TanStack · Function
createLazyFileRoute
Creates a partial file-based route whose non-critical configuration is loaded lazily when the route matches. It is intended for route-level code splitting.
How it works
createLazyFileRoute creates a partial file-based route whose configuration is loaded when the route matches. It takes the route file path and returns a function accepting only the supported non-critical route options, such as rendering and fallback components.
Syntax
createLazyFileRoute(path)(options)Parameters
| Name | Type | Description |
|---|---|---|
path | string | The file route's path; it is required and is automatically inserted or updated by the tsr generate and tsr watch commands. |
options | Pick<RouteOptions, 'component' | 'pendingComponent' | 'errorComponent' | 'notFoundComponent'> | A partial RouteOptions object limited to component, pendingComponent, errorComponent, and notFoundComponent. |
Returns
A function that accepts the supported partial RouteOptions and creates the lazy file-route instance.
Key points
- It creates a partial file-based route that loads when its route match is activated.
- Its path identifies the source file from which the generated route is created.
- The path is maintained automatically by the tsr generate and tsr watch commands.
- The accepted lazy options are component, pendingComponent, errorComponent, and notFoundComponent.
- The call returns a function that accepts a partial RouteOptions object.
Common mistakes
- Do not place critical route configuration such as loaders or path matching behavior in this lazy route; use the main file route for that configuration.
- File-based route generation requires exporting the instance under the exact Route identifier.
Example: Lazy file route
import { createLazyFileRoute } from '@tanstack/react-router'
export const Route = createLazyFileRoute('/')({
component: IndexComponent,
})
function IndexComponent() {
const data = Route.useLoaderData()
return <div>{data}</div>
}Defines the lazily loaded, non-critical component configuration for the root file route.
When to use it
Lazy non-critical UI
Add a route's main, loading, error, or not-found UI in a lazy file.
Generated file routes
Use generated file-based routes while keeping the lazy instance discoverable by the router tooling.
Interview questions
QWhat is createLazyFileRoute used for?
It creates a partial file-based route that is loaded lazily when the route matches. The returned configuration is limited to non-critical options such as component, pendingComponent, errorComponent, and notFoundComponent.
Follow-up: How does it support code splitting? Put the non-critical configuration in a lazy route file, commonly using the .lazy.tsx suffix, and create that configuration with createLazyFileRoute instead of createFileRoute.
QWhat arguments does createLazyFileRoute use?
The function receives the file route path as a string and returns a function. Calling that function with route options creates the lazy file-route instance.
Follow-up: What must happen to the path value in generated file-based routing? The generator or watcher automatically inserts and updates it.
QWhy must the route be exported as Route?
The generated route instance should be exported as Route. This lets the file-based routing generator and watcher recognize the route correctly.
Follow-up: Which route options belong in the lazy configuration? The documented supported options are component, pendingComponent, errorComponent, and notFoundComponent.
Related
createFileRoutecreateLazyRoutelazyRouteComponentRoute.lazy