--- title: Code Splitting --- Code splitting and lazy loading is a powerful technique for improving the bundle size and load performance of an application. - Reduces the amount of code that needs to be loaded on initial page load - Code is loaded on-demand when it is needed - Results in more chunks that are smaller in size that can be cached more easily by the browser. ## How does TanStack Router split code? TanStack Router separates code into two categories: - **Critical Route Configuration** - The code that is required to render the current route and kick off the data loading process as early as possible. - Path Parsing/Serialization - Search Param Validation - Loaders, Before Load - Route Context - Static Data - Links - Scripts - Styles - All other route configuration not listed below - **Non-Critical/Lazy Route Configuration** - The code that is not required to match the route, and can be loaded on-demand. - Route Component - Error Component - Pending Component - Not-found Component > 🧠 **Why is the loader not split?** > > - The loader is already an asynchronous boundary, so you pay double to both get the chunk _and_ wait for the loader to execute. > - Categorically, it is less likely to contribute to a large bundle size than a component. > - The loader is one of the most important preloadable assets for a route, especially if you're using a default preload intent, like hovering over a link, so it's important for the loader to be available without any additional async overhead. > > Knowing the disadvantages of splitting the loader, if you still want to go ahead with it, head over to the [Data Loader Splitting](#data-loader-splitting) section. ## Approaches to code splitting TanStack Router supports multiple approaches to code splitting. If you are using code-based routing, skip to the [Code-Based Splitting](#code-based-splitting) section. When you are using file-based routing, you can use the following approaches to code splitting: - [Using the `.lazy.tsx` suffix](#using-the-lazytsx-suffix) - [Using Virtual Routes](#using-virtual-routes) - [Using automatic code-splitting ✨](#using-automatic-code-splitting) ## Encapsulating a route's files into a directory Since TanStack Router's file-based routing system is designed to support both flat and nested file structures, it's possible to encapsulate a route's files into a single directory without any additional configuration. To encapsulate a route's files into a directory, move the route file itself into a `.route` file within a directory with the same name as the route file. For example, if you have a route file named `posts.tsx`, you would create a new directory named `posts` and move the `posts.tsx` file into that directory, renaming it to `route.tsx`. **Before** - `posts.tsx` - `posts.lazy.tsx` **After** - `posts` - `route.tsx` - `route.lazy.tsx` ## Using the `.lazy.tsx` suffix If you're using the recommended [File-Based Routing](./route-trees.md) approach, code splitting is **as easy as moving your code into a separate file with a `.lazy.tsx` suffix** and use the `createLazyFileRoute` function instead of the `FileRoute` class or `createFileRoute` function. Here are the options currently supported by the `createLazyFileRoute` function: | Export Name | Description | | ------------------- | --------------------------------------------------------------------- | | `component` | The component to render for the route. | | `errorComponent` | The component to render when an error occurs while loading the route. | | `pendingComponent` | The component to render while the route is loading. | | `notFoundComponent` | The component to render if a not-found error gets thrown. | ### Exceptions to the `.lazy.tsx` rule - The `__root.tsx` route file does not support code splitting, since it's always rendered regardless of the current route. ### Example code splitting with `.lazy.tsx` When you are using `.lazy.tsx` you can split your route into two files to enable code splitting: **Before (Single File)** ```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() { // ... } ``` **After (Split into two files)** This file would contain the critical route configuration: ```tsx // src/routes/posts.tsx import { createFileRoute } from '@tanstack/react-router' import { fetchPosts } from './api' export const Route = createFileRoute('/posts')({ loader: fetchPosts, }) ``` With the non-critical route configuration going into the file with the `.lazy.tsx` suffix: ```tsx // src/routes/posts.lazy.tsx import { createLazyFileRoute } from '@tanstack/react-router' export const Route = createLazyFileRoute('/posts')({ component: Posts, }) function Posts() { // ... } ``` ## Using Virtual Routes You might run into a situation where you end up splitting out everything from a route file, leaving it empty! In this case, simply **delete the route file entirely**! A virtual route will automatically be generated for you to serve as an anchor for your code split files. This virtual route will live directly in the generated route tree file. **Before (Virtual Routes)** ```tsx // 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() { // ... } ``` **After (Virtual Routes)** ```tsx // src/routes/posts.lazy.tsx import { createLazyFileRoute } from '@tanstack/react-router' export const Route = createLazyFileRoute('/posts')({ component: Posts, }) function Posts() { // ... } ``` Tada! 🎉 ## Using automatic code-splitting When using the `autoCodeSplitting` feature, TanStack Router will automatically code split your route files based on the non-critical route configuration mentioned above. > [!IMPORTANT] > The automatic code-splitting feature is **ONLY** available when you are using file-based routing with one of our [supported bundlers](./file-based-routing.md#installation). > This will **NOT** work if you are **only** using the CLI (`@tanstack/router-cli`). If this is your first time using TanStack Router, then you can skip the following steps and head over to [Enabling automatic code-splitting](#enabling-automatic-code-splitting). If you've already been using TanStack Router, then you might need to make some changes to your route files to enable automatic code-splitting. ### Preparing your route files for automatic code-splitting When using automatic code-splitting, you should **not** use the `.lazy.tsx` suffix. Instead, any routes that are split into two using the `.lazy.tsx` suffix should be merged back into a single file. **Before using the `.lazy` suffix** ```tsx // src/routes/posts.tsx import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/posts')({ loader: fetchPosts, }) ``` ```tsx // src/routes/posts.lazy.tsx import { createLazyFileRoute } from '@tanstack/react-router' export const Route = createLazyFileRoute('/posts')({ component: Posts, }) function Posts() { // ... } ``` **After removing the `.lazy` suffix** ```tsx // src/routes/posts.tsx import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/posts')({ loader: fetchPosts, component: Posts, }) function Posts() { // ... } ``` Also, if you were previously using virtual routes, you should then have their `.lazy.tsx` suffixes removed. **Before using Virtual Routes** ```tsx // src/routes/posts.lazy.tsx import { createLazyFileRoute } from '@tanstack/react-router' export const Route = createLazyFileRoute('/posts')({ /* ... */ }) ``` **After without Virtual Routes** ```tsx // src/routes/posts.tsx import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/posts')({ /* ... */ }) ``` Once you've done this, your route files are ready for automatic code-splitting. ### Enabling automatic code-splitting > [!IMPORTANT] > At this time, when using automatic code-splitting, ALL of your route files will be code-split. This means that you should only use this feature if you are sure that you want to code-split all of your route files. To enable automatic code-splitting, you can add the following to your `tsr.config.json`: ```jsonc { // ... "autoCodeSplitting": true, } ``` That's it! TanStack Router will automatically code-split all your route files by their critical and non-critical route configurations. ## Code-Based Splitting ### Manually Splitting Using `route.lazy()` and `createLazyRoute` If you're not using the file-based routing system, you can still manually split your code using the `route.lazy()` method and the `createLazyRoute` function. You'd need to: Create a lazy route using the `createLazyRoute` function. ```tsx // src/posts.tsx export const Route = createLazyRoute('/posts')({ component: MyComponent, }) function MyComponent() { return