fix(router-plugin): show warning for non-splittable items (#5145)

Author: SeanCassiere

docs/router/framework/react/guide/automatic-code-splitting.md

@@ -74,6 +74,38 @@ This means that it creates three separate lazy-loaded chunks for each route. Res
 - One for the error component
 - And one for the not-found component.
 
+### Rules of Splitting
+
+For automatic code splitting to work, there are some rules in-place to make sure that this process can reliably and predictably happen.
+
+#### Do not export route properties
+
+Route properties like `component`, `loader`, etc., should not be exported from the route file. Exporting these properties results in them being bundled into the main application bundle, which means that they will not be code-split.
+
+```tsx
+import { createRoute } from '@tanstack/react-router'
+
+export const Route = createRoute('/posts')({
+  // ...
+  notFoundComponent: PostsNotFoundComponent,
+})
+
+// ❌ Do NOT do this!
+// Exporting the notFoundComponent will prevent it from being code-split
+// and will be included in the main bundle.
+export function PostsNotFoundComponent() {
+  // ❌
+  // ...
+}
+
+function PostsNotFoundComponent() {
+  // ✅
+  // ...
+}
+```
+
+**That's it!** There are no other restrictions. You can use any other JavaScript or TypeScript features in your route files as you normally would. If you run into any issues, please [open an issue](https://github.com/tanstack/router/issues) on GitHub.
+
 ## Granular control
 
 For most applications, the default behavior of using `autoCodeSplitting: true` is sufficient. However, TanStack Router provides several options to customize how your routes are split into chunks, allowing you to optimize for specific use cases or performance needs.

packages/router-plugin/src/core/code-splitter/compilers.ts

@@ -84,7 +84,8 @@ function addSplitSearchParamToFilename(
   const params = new URLSearchParams()
   params.append(tsrSplit, createIdentifier(grouping))
 
-  return `${bareFilename}?${params.toString()}`
+  const result = `${bareFilename}?${params.toString()}`
+  return result
 }
 
 function removeSplitSearchParamFromFilename(filename: string) {
@@ -116,6 +117,8 @@ export function compileCodeSplitReferenceRoute(
 
   const refIdents = findReferencedIdentifiers(ast)
 
+  const knownExportedIdents = new Set<string>()
+
   function findIndexForSplitNode(str: string) {
     return opts.codeSplitGroupings.findIndex((group) =>
       group.includes(str as any),
@@ -251,6 +254,9 @@ export function compileCodeSplitReferenceRoute(
                           // since they are already being imported
                           // and need to be retained in the compiled file
                           const isExported = hasExport(ast, value)
+                          if (isExported) {
+                            knownExportedIdents.add(value.name)
+                          }
                           shouldSplit = !isExported
 
                           if (shouldSplit) {
@@ -320,6 +326,9 @@ export function compileCodeSplitReferenceRoute(
                           // since they are already being imported
                           // and need to be retained in the compiled file
                           const isExported = hasExport(ast, value)
+                          if (isExported) {
+                            knownExportedIdents.add(value.name)
+                          }
                           shouldSplit = !isExported
 
                           if (shouldSplit) {
@@ -410,6 +419,26 @@ export function compileCodeSplitReferenceRoute(
 
   deadCodeElimination(ast, refIdents)
 
+  // if there are exported identifiers, then we need to add a warning
+  // to the file to let the user know that the exported identifiers
+  // will not in the split file but in the original file, therefore
+  // increasing the bundle size
+  if (knownExportedIdents.size > 0) {
+    const warningMessage = createNotExportableMessage(
+      opts.filename,
+      knownExportedIdents,
+    )
+    console.warn(warningMessage)
+
+    // append this warning to the file using a template
+    if (process.env.NODE_ENV !== 'production') {
+      const warningTemplate = template.statement(
+        `console.warn(${JSON.stringify(warningMessage)})`,
+      )()
+      ast.program.body.unshift(warningTemplate)
+    }
+  }
+
   return generateFromAst(ast, {
     sourceMaps: true,
     sourceFileName: opts.filename,
@@ -712,28 +741,6 @@ export function compileCodeSplitVirtualRoute(
 
   deadCodeElimination(ast, refIdents)
 
-  // if there are exported identifiers, then we need to add a warning
-  // to the file to let the user know that the exported identifiers
-  // will not in the split file but in the original file, therefore
-  // increasing the bundle size
-  if (knownExportedIdents.size > 0) {
-    const list = Array.from(knownExportedIdents).reduce((str, ident) => {
-      str += `\n- ${ident}`
-      return str
-    }, '')
-
-    const warningMessage = `These exports from "${opts.filename}" are not being code-split and will increase your bundle size: ${list}\nThese should either have their export statements removed or be imported from another file that is not a route.`
-    console.warn(warningMessage)
-
-    // append this warning to the file using a template
-    if (process.env.NODE_ENV !== 'production') {
-      const warningTemplate = template.statement(
-        `console.warn(${JSON.stringify(warningMessage)})`,
-      )()
-      ast.program.body.unshift(warningTemplate)
-    }
-  }
-
   return generateFromAst(ast, {
     sourceMaps: true,
     sourceFileName: opts.filename,
@@ -837,6 +844,21 @@ export function detectCodeSplitGroupingsFromRoute(opts: ParseAstOptions): {
   return { groupings: codeSplitGroupings }
 }
 
+function createNotExportableMessage(
+  filename: string,
+  idents: Set<string>,
+): string {
+  const list = Array.from(idents).map((d) => `- ${d}`)
+
+  const message = [
+    `[tanstack-router] These exports from "${filename}" will not be code-split and will increase your bundle size:`,
+    ...list,
+    'For the best optimization, these items should either have their export statements removed, or be imported from another location that is not a route file.',
+  ].join('\n')
+
+  return message
+}
+
 function getImportSpecifierAndPathFromLocalName(
   programPath: babel.NodePath<t.Program>,
   name: string,

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component-and-normal-notFound.tsx

@@ -1,3 +1,4 @@
+console.warn("[tanstack-router] These exports from \"export-default-component-and-normal-notFound.tsx\" will not be code-split and will increase your bundle size:\n- Home\nFor the best optimization, these items should either have their export statements removed, or be imported from another location that is not a route file.");
 const $$splitNotFoundComponentImporter = () => import('export-default-component-and-normal-notFound.tsx?tsr-split=notFoundComponent');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import React, { useState } from 'react';

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component-and-normal-notFound@component.tsx

@@ -1,3 +1,2 @@
-console.warn("These exports from \"export-default-component-and-normal-notFound.tsx?component\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component-and-normal-notFound.tsx";

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component-and-normal-notFound@errorComponent.tsx

@@ -1,3 +1,2 @@
-console.warn("These exports from \"export-default-component-and-normal-notFound.tsx?errorComponent\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component-and-normal-notFound.tsx";

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component-and-normal-notFound@notFoundComponent.tsx

@@ -1,4 +1,3 @@
-console.warn("These exports from \"export-default-component-and-normal-notFound.tsx?notFoundComponent\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component-and-normal-notFound.tsx";
 function NotFoundComponent() {

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component.tsx

@@ -1,3 +1,4 @@
+console.warn("[tanstack-router] These exports from \"export-default-component.tsx\" will not be code-split and will increase your bundle size:\n- Home\nFor the best optimization, these items should either have their export statements removed, or be imported from another location that is not a route file.");
 import React, { useState } from 'react';
 import { createFileRoute } from '@tanstack/react-router';
 export const Route = createFileRoute('/home')({

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component@component.tsx

@@ -1,3 +1,2 @@
-console.warn("These exports from \"export-default-component.tsx?component\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component.tsx";

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component@errorComponent.tsx

@@ -1,3 +1,2 @@
-console.warn("These exports from \"export-default-component.tsx?errorComponent\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component.tsx";

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/export-default-component@notFoundComponent.tsx

@@ -1,3 +1,2 @@
-console.warn("These exports from \"export-default-component.tsx?notFoundComponent\" are not being code-split and will increase your bundle size: \n- Home\nThese should either have their export statements removed or be imported from another file that is not a route.");
 import React from 'react';
 import { Route } from "export-default-component.tsx";