fix: autoCodeSplitting` with destructured export

[schiller-manuel]

fixes #4787

Summary by CodeRabbit

• New Features

  • Enhanced code-splitting support for routes using destructured exports and bindings in configurations.
  • Improved handling of nested and complex destructuring patterns (object and array) in route options and exports.

• Tests

  • Added comprehensive test snapshots validating destructuring scenarios across multiple route configurations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds destructuring-aware code splitting to the router-plugin compiler, implementing tracking of original binding names, identifier collection from destructuring patterns (ObjectPattern, ArrayPattern), and correct import/export specifier generation for destructured bindings across split modules.

Changes

Cohort / File(s)	Summary
Core Compiler Logic packages/router-plugin/src/core/code-splitter/compilers.ts	Introduces collectIdentifiersFromPattern utility to recursively extract identifiers from destructuring patterns. Adds originalIdentName tracking for split nodes. Updates binding resolution, removal logic, and specifier generation to handle destructured ObjectPattern and ArrayPattern declarations. Extends hasExport, removeExports, and variable-to-import conversion logic with destructuring-aware paths.
Snapshot Tests — destructured-export-multiple packages/router-plugin/tests/code-splitter/snapshots/react/*/destructured-export-multiple.tsx, destructured-export-multiple@component*.tsx	Test fixtures for code splitting with destructured object exports from a getConfig() function, demonstrating array destructuring (first, second) and object destructuring (baseUrl, timeout) across split module boundaries.
Snapshot Tests — destructured-export-nested packages/router-plugin/tests/code-splitter/snapshots/react/*/destructured-export-nested.tsx, destructured-export-nested@component*.tsx	Test fixtures for nested destructuring patterns, including rest-element spread (...rest) from deeply nested config objects, validating correct handling of complex destructuring scenarios in code splitting.
Snapshot Tests — destructured-export packages/router-plugin/tests/code-splitter/snapshots/react/*/destructured-export.tsx, `destructured-export@(component	errorComponent
Snapshot Tests — destructured-route-options-defaults packages/router-plugin/tests/code-splitter/snapshots/react/*/destructured-route-options-defaults.tsx, `destructured-route-options-defaults@(component	loader)*.tsx`
Snapshot Tests — retain-exports-destructured packages/router-plugin/tests/code-splitter/snapshots/react/*/retain-exports-destructured.tsx, retain-exports-destructured@loader*.tsx	Test fixtures for destructuring exports from factory functions with renamed public exports, validating correct re-export of destructured bindings (AboutComponent, loader) in split scenarios.
Test Input Files packages/router-plugin/tests/code-splitter/test-files/react/destructured-*.tsx, retain-exports-destructured.tsx	Source test files demonstrating destructured export patterns (multiple, nested, simple objects, route-option defaults, factory-based exports) that serve as inputs to the code splitter to generate the snapshot files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• fix: enable dead code elimination in split-route to remove unused imports #5711: Modifies the same compilers.ts file to implement import-specifier collection logic for dead-code elimination; shares overlapping concerns with identifier/specifier tracking during split-module transforms.
• fix: only transform files in codesplitter if changes were made #5460: Updates compilers.ts with modification-tracking and early-return patterns in compileCodeSplitReferenceRoute; touches the same AST transformation paths affected by destructuring-aware binding logic.

Suggested labels

package: router-plugin

Suggested reviewers

• nlynzaad
• Sheraff

Poem

🐰 A rabbit hops through destructured gains,
Patterns split across the chains,
ObjectPattern, ArrayPattern too—
Identifiers collected, specifiers flew!
No more undefined in binding's way,
The splitter works both night and day. 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.17% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Merge Conflict Detection	⚠️ Warning	⚠️ Unable to check for merge conflicts: Failed to fetch base branch: From https://github.com/TanStack/router ! [rejected] main -> main (non-fast-forward) + f212098...fb139e8 main -> origin/main (forced update)

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: autoCodeSplitting with destructured export' clearly describes the main change, addressing the core issue of fixing destructured exports with autoCodeSplitting enabled.
Linked Issues check	✅ Passed	The PR successfully addresses issue #4787 by implementing comprehensive fixes for destructured export handling in the code-splitter compiler and adding extensive test coverage for various destructuring patterns.
Out of Scope Changes check	✅ Passed	All changes are scoped to handling destructured exports in the code-splitting plugin, which is directly aligned with the issue requirements. No unrelated changes were introduced.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-4787

⚔️ Resolve merge conflicts (beta)

• Auto-commit resolved conflicts to branch fix-4787
• Create stacked PR with resolved conflicts
• Post resolved changes as copyable diffs in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 1f4b2dc

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	11m 12s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	32s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-02-14 01:17:40 UTC

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6656

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6656

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6656

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6656

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6656

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6656

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6656

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6656

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6656

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6656

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6656

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6656

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6656

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6656

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6656

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6656

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6656

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6656

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6656

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6656

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6656

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6656

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6656

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6656

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6656

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6656

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6656

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6656

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6656

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6656

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6656

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6656

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6656

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6656

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6656

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6656

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6656

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6656

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6656

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6656

commit: 1f4b2dc

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

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

637-648: ⚠️ Potential issue | 🟡 Minor

Add ArrayPattern support for split bindings.

Variable declarators only handle Identifier and ObjectPattern. Array destructuring patterns (e.g., const [Component] = createBits()) will trigger the unexpected-type error. This is inconsistent with other parts of the code (e.g., hasExport() at line 1095–1097 handles both patterns). Add t.isArrayPattern handling alongside ObjectPattern, preserving positional elements.

Additionally, update removeIdentifierLiteral() to handle array-destructured bindings so that matched elements are removed without shifting indices.

💡 Suggested patch

} else if (t.isVariableDeclarator(splitNode)) {
  if (t.isIdentifier(splitNode.id)) {
    splitMeta.localExporterIdent = splitNode.id.name
    splitMeta.shouldRemoveNode = false
  } else if (t.isObjectPattern(splitNode.id)) {
    // Destructured binding like `const { component: MyComp } = createBits()`
    // Use the original identifier name that was tracked before resolving
    if (originalIdentName) {
      splitMeta.localExporterIdent = originalIdentName
    }
    splitMeta.shouldRemoveNode = false
+  } else if (t.isArrayPattern(splitNode.id)) {
+    if (originalIdentName) {
+      splitMeta.localExporterIdent = originalIdentName
+    }
+    splitMeta.shouldRemoveNode = false
  } else {
    throw new Error(
      `Unexpected splitNode type ☝️: ${splitNode.type}`,
    )
  }
}