@tanstack/router-plugin 1.20.3-alpha.1

package/src/core/code-splitter/framework-options.ts

@@ -0,0 +1,41 @@
+type FrameworkOptions = {
+  package: string
+  idents: {
+    createFileRoute: string
+    lazyFn: string
+    lazyRouteComponent: string
+  }
+}
+
+export function getFrameworkOptions(framework: string): FrameworkOptions {
+  let frameworkOptions: FrameworkOptions
+
+  switch (framework) {
+    case 'react':
+      frameworkOptions = {
+        package: '@tanstack/react-router',
+        idents: {
+          createFileRoute: 'createFileRoute',
+          lazyFn: 'lazyFn',
+          lazyRouteComponent: 'lazyRouteComponent',
+        },
+      }
+      break
+    case 'solid':
+      frameworkOptions = {
+        package: '@tanstack/solid-router',
+        idents: {
+          createFileRoute: 'createFileRoute',
+          lazyFn: 'lazyFn',
+          lazyRouteComponent: 'lazyRouteComponent',
+        },
+      }
+      break
+    default:
+      throw new Error(
+        `[getFrameworkOptions] - Unsupported framework: ${framework}`,
+      )
+  }
+
+  return frameworkOptions
+}

package/src/core/code-splitter/path-ids.ts

@@ -0,0 +1,39 @@
+export function createIdentifier(strings: Array<string>): string {
+  if (strings.length === 0) {
+    throw new Error('Cannot create an identifier from an empty array')
+  }
+
+  const sortedStrings = [...strings].sort()
+  const combinedString = sortedStrings.join('---') // Delimiter
+
+  // Replace unsafe characters
+  let safeString = combinedString.replace(/\//g, '--slash--')
+  safeString = safeString.replace(/\\/g, '--backslash--')
+  safeString = safeString.replace(/\?/g, '--question--')
+  safeString = safeString.replace(/%/g, '--percent--')
+  safeString = safeString.replace(/#/g, '--hash--')
+  safeString = safeString.replace(/\+/g, '--plus--')
+  safeString = safeString.replace(/=/g, '--equals--')
+  safeString = safeString.replace(/&/g, '--ampersand--')
+  safeString = safeString.replace(/\s/g, '_') // Replace spaces with underscores
+
+  return safeString
+}
+
+export function decodeIdentifier(identifier: string): Array<string> {
+  if (!identifier) {
+    return []
+  }
+
+  let combinedString = identifier.replace(/--slash--/g, '/')
+  combinedString = combinedString.replace(/--backslash--/g, '\\')
+  combinedString = combinedString.replace(/--question--/g, '?')
+  combinedString = combinedString.replace(/--percent--/g, '%')
+  combinedString = combinedString.replace(/--hash--/g, '#')
+  combinedString = combinedString.replace(/--plus--/g, '+')
+  combinedString = combinedString.replace(/--equals--/g, '=')
+  combinedString = combinedString.replace(/--ampersand--/g, '&')
+  combinedString = combinedString.replace(/_/g, ' ') // Restore spaces
+
+  return combinedString.split('---')
+}

package/src/core/config.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod'
+import {
+  configSchema as generatorConfigSchema,
+  getConfig as getGeneratorConfig,
+} from '@tanstack/router-generator'
+import type { RegisteredRouter, RouteIds } from '@tanstack/router-core'
+import type { CodeSplitGroupings } from './constants'
+
+export const splitGroupingsSchema = z
+  .array(
+    z.array(
+      z.union([
+        z.literal('loader'),
+        z.literal('component'),
+        z.literal('pendingComponent'),
+        z.literal('errorComponent'),
+        z.literal('notFoundComponent'),
+      ]),
+    ),
+    {
+      message:
+        "  Must be an Array of Arrays containing the split groupings. i.e. [['component'], ['pendingComponent'], ['errorComponent', 'notFoundComponent']]",
+    },
+  )
+  .superRefine((val, ctx) => {
+    const flattened = val.flat()
+    const unique = [...new Set(flattened)]
+
+    // Elements must be unique,
+    // ie. this shouldn't be allows [['component'], ['component', 'loader']]
+    if (unique.length !== flattened.length) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          "  Split groupings must be unique and not repeated. i.e. i.e. [['component'], ['pendingComponent'], ['errorComponent', 'notFoundComponent']]." +
+          `\n  You input was: ${JSON.stringify(val)}.`,
+      })
+    }
+  })
+
+export type CodeSplittingOptions = {
+  /**
+   * Use this function to programmatically control the code splitting behavior
+   * based on the `routeId` for each route.
+   *
+   * If you just need to change the default behavior, you can use the `defaultBehavior` option.
+   * @param params
+   */
+  splitBehavior?: (params: {
+    routeId: RouteIds<RegisteredRouter['routeTree']>
+  }) => CodeSplitGroupings | undefined | void
+
+  /**
+   * The default/global configuration to control your code splitting behavior per route.
+   * @default [['component'],['pendingComponent'],['errorComponent'],['notFoundComponent']]
+   */
+  defaultBehavior?: CodeSplitGroupings
+}
+
+const codeSplittingOptionsSchema = z.object({
+  splitBehavior: z.function().optional(),
+  defaultBehavior: splitGroupingsSchema.optional(),
+})
+
+export const configSchema = generatorConfigSchema.extend({
+  enableRouteGeneration: z.boolean().optional(),
+  codeSplittingOptions: z
+    .custom<CodeSplittingOptions>((v) => {
+      return codeSplittingOptionsSchema.parse(v)
+    })
+    .optional(),
+})
+
+export const getConfig = (inlineConfig: Partial<Config>, root: string) => {
+  const config = getGeneratorConfig(inlineConfig, root)
+
+  return configSchema.parse({ ...config, ...inlineConfig })
+}
+
+export type Config = z.infer<typeof configSchema>

package/src/core/constants.ts

@@ -0,0 +1,17 @@
+export const tsrSplit = 'tsr-split'
+
+export const splitRouteIdentNodes = [
+  'loader',
+  'component',
+  'pendingComponent',
+  'errorComponent',
+  'notFoundComponent',
+] as const
+export type SplitRouteIdentNodes = (typeof splitRouteIdentNodes)[number]
+export type CodeSplitGroupings = Array<Array<SplitRouteIdentNodes>>
+
+export const defaultCodeSplitGroupings: CodeSplitGroupings = [
+  ['component'],
+  ['errorComponent'],
+  ['notFoundComponent'],
+]

package/src/core/route-autoimport-plugin.ts

@@ -0,0 +1,102 @@
+import { generateFromAst, logDiff, parseAst } from '@tanstack/router-utils'
+import babel from '@babel/core'
+import * as template from '@babel/template'
+import { getConfig } from './config'
+import { debug, fileIsInRoutesDirectory } from './utils'
+import type { Config } from './config'
+import type { UnpluginFactory } from 'unplugin'
+
+/**
+ * This plugin adds imports for createFileRoute and createLazyFileRoute to the file route.
+ */
+export const unpluginRouteAutoimportFactory: UnpluginFactory<
+  Partial<Config> | undefined
+> = (options = {}) => {
+  let ROOT: string = process.cwd()
+  let userConfig = options as Config
+
+  return {
+    name: 'router-autoimport-plugin',
+    enforce: 'pre',
+
+    transform(code, id) {
+      let routeType: 'createFileRoute' | 'createLazyFileRoute'
+      if (code.includes('export const Route = createFileRoute(')) {
+        routeType = 'createFileRoute'
+      } else if (code.includes('export const Route = createLazyFileRoute(')) {
+        routeType = 'createLazyFileRoute'
+      } else {
+        return null
+      }
+
+      const routerImportPath = `@tanstack/${userConfig.target}-router`
+
+      const ast = parseAst({ code })
+
+      let isCreateRouteFunctionImported = false as boolean
+
+      babel.traverse(ast, {
+        Program: {
+          enter(programPath) {
+            programPath.traverse({
+              ImportDeclaration(path) {
+                const importedSpecifiers = path.node.specifiers.map(
+                  (specifier) => specifier.local.name,
+                )
+                if (
+                  importedSpecifiers.includes(routeType) &&
+                  path.node.source.value === routerImportPath
+                ) {
+                  isCreateRouteFunctionImported = true
+                }
+              },
+            })
+          },
+        },
+      })
+
+      if (!isCreateRouteFunctionImported) {
+        if (debug) console.info('Adding autoimports to route ', id)
+
+        const autoImportStatement = template.statement(
+          `import { ${routeType} } from '${routerImportPath}'`,
+        )()
+        ast.program.body.unshift(autoImportStatement)
+
+        const result = generateFromAst(ast, {
+          sourceMaps: true,
+          filename: id,
+          sourceFileName: id,
+        })
+        if (debug) {
+          logDiff(code, result.code)
+          console.log('Output:\n', result.code + '\n\n')
+        }
+        return result
+      }
+
+      return null
+    },
+
+    transformInclude(id) {
+      return fileIsInRoutesDirectory(id, userConfig.routesDirectory)
+    },
+
+    vite: {
+      configResolved(config) {
+        ROOT = config.root
+        userConfig = getConfig(options, ROOT)
+      },
+    },
+
+    rspack() {
+      ROOT = process.cwd()
+      userConfig = getConfig(options, ROOT)
+    },
+
+    webpack() {
+      ROOT = process.cwd()
+      userConfig = getConfig(options, ROOT)
+    },
+  }
+}

package/src/core/route-hmr-statement.ts

@@ -0,0 +1,13 @@
+import * as template from '@babel/template'
+
+export const routeHmrStatement = template.statement(
+  `
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (newModule.Route && typeof newModule.Route.clone === 'function') {
+      newModule.Route.clone(Route)
+    }
+   })
+}
+`,
+)()

package/src/core/router-code-splitter-plugin.ts

@@ -0,0 +1,253 @@
+/**
+ * It is important to familiarize yourself with how the code-splitting works in this plugin.
+ * https://github.com/TanStack/router/pull/3355
+ */
+
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { logDiff } from '@tanstack/router-utils'
+import { getConfig, splitGroupingsSchema } from './config'
+import {
+  compileCodeSplitReferenceRoute,
+  compileCodeSplitVirtualRoute,
+  detectCodeSplitGroupingsFromRoute,
+} from './code-splitter/compilers'
+import {
+  defaultCodeSplitGroupings,
+  splitRouteIdentNodes,
+  tsrSplit,
+} from './constants'
+import { decodeIdentifier } from './code-splitter/path-ids'
+import { debug, fileIsInRoutesDirectory } from './utils'
+import type { CodeSplitGroupings, SplitRouteIdentNodes } from './constants'
+
+import type { Config } from './config'
+import type {
+  UnpluginContextMeta,
+  UnpluginFactory,
+  TransformResult as UnpluginTransformResult,
+} from 'unplugin'
+
+function capitalizeFirst(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+type BannedBeforeExternalPlugin = {
+  identifier: string
+  pkg: string
+  usage: string
+  frameworks: Array<UnpluginContextMeta['framework']>
+}
+
+const bannedBeforeExternalPlugins: Array<BannedBeforeExternalPlugin> = [
+  {
+    identifier: '@react-refresh',
+    pkg: '@vitejs/plugin-react',
+    usage: 'viteReact()',
+    frameworks: ['vite'],
+  },
+]
+
+class FoundPluginInBeforeCode extends Error {
+  constructor(externalPlugin: BannedBeforeExternalPlugin, framework: string) {
+    super(`We detected that the '${externalPlugin.pkg}' was passed before '@tanstack/router-plugin'. Please make sure that '@tanstack/router-plugin' is passed before '${externalPlugin.pkg}' and try again: 
+e.g.
+plugins: [
+  TanStackRouter${capitalizeFirst(framework)}(), // Place this before ${externalPlugin.usage}
+  ${externalPlugin.usage},
+]
+`)
+  }
+}
+
+const PLUGIN_NAME = 'unplugin:router-code-splitter'
+
+export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
+  Partial<Config> | undefined
+> = (options = {}, { framework }) => {
+  let ROOT: string = process.cwd()
+  let userConfig = options as Config
+
+  const isProduction = process.env.NODE_ENV === 'production'
+
+  const getGlobalCodeSplitGroupings = () => {
+    return (
+      userConfig.codeSplittingOptions?.defaultBehavior ||
+      defaultCodeSplitGroupings
+    )
+  }
+  const getShouldSplitFn = () => {
+    return userConfig.codeSplittingOptions?.splitBehavior
+  }
+
+  const handleCompilingReferenceFile = (
+    code: string,
+    id: string,
+  ): UnpluginTransformResult => {
+    if (debug) console.info('Compiling Route: ', id)
+
+    const fromCode = detectCodeSplitGroupingsFromRoute({
+      code,
+    })
+
+    if (fromCode.groupings) {
+      const res = splitGroupingsSchema.safeParse(fromCode.groupings)
+      if (!res.success) {
+        const message = res.error.errors.map((e) => e.message).join('. ')
+        throw new Error(
+          `The groupings for the route "${id}" are invalid.\n${message}`,
+        )
+      }
+    }
+
+    const userShouldSplitFn = getShouldSplitFn()
+
+    const pluginSplitBehavior = userShouldSplitFn?.({
+      routeId: fromCode.routeId,
+    }) as CodeSplitGroupings | undefined
+
+    if (pluginSplitBehavior) {
+      const res = splitGroupingsSchema.safeParse(pluginSplitBehavior)
+      if (!res.success) {
+        const message = res.error.errors.map((e) => e.message).join('. ')
+        throw new Error(
+          `The groupings returned when using \`splitBehavior\` for the route "${id}" are invalid.\n${message}`,
+        )
+      }
+    }
+
+    const splitGroupings: CodeSplitGroupings =
+      fromCode.groupings || pluginSplitBehavior || getGlobalCodeSplitGroupings()
+
+    const compiledReferenceRoute = compileCodeSplitReferenceRoute({
+      code,
+      runtimeEnv: isProduction ? 'prod' : 'dev',
+      codeSplitGroupings: splitGroupings,
+      targetFramework: userConfig.target,
+      filename: id,
+      id,
+    })
+
+    if (debug) {
+      logDiff(code, compiledReferenceRoute.code)
+      console.log('Output:\n', compiledReferenceRoute.code + '\n\n')
+    }
+
+    return compiledReferenceRoute
+  }
+
+  const handleCompilingVirtualFile = (
+    code: string,
+    id: string,
+  ): UnpluginTransformResult => {
+    if (debug) console.info('Splitting Route: ', id)
+
+    const [_, ...pathnameParts] = id.split('?')
+
+    const searchParams = new URLSearchParams(pathnameParts.join('?'))
+    const splitValue = searchParams.get(tsrSplit)
+
+    if (!splitValue) {
+      throw new Error(
+        `The split value for the virtual route "${id}" was not found.`,
+      )
+    }
+
+    const rawGrouping = decodeIdentifier(splitValue)
+    const grouping = [...new Set(rawGrouping)].filter((p) =>
+      splitRouteIdentNodes.includes(p as any),
+    ) as Array<SplitRouteIdentNodes>
+
+    const result = compileCodeSplitVirtualRoute({
+      code,
+      filename: id,
+      splitTargets: grouping,
+    })
+
+    if (debug) {
+      logDiff(code, result.code)
+      console.log('Output:\n', result.code + '\n\n')
+    }
+
+    return result
+  }
+
+  return {
+    name: 'router-code-splitter-plugin',
+    enforce: 'pre',
+
+    transform(code, id) {
+      if (!userConfig.autoCodeSplitting) {
+        return null
+      }
+
+      const url = pathToFileURL(id)
+      url.searchParams.delete('v')
+      id = fileURLToPath(url).replace(/\\/g, '/')
+
+      if (id.includes(tsrSplit)) {
+        return handleCompilingVirtualFile(code, id)
+      } else if (
+        fileIsInRoutesDirectory(id, userConfig.routesDirectory) &&
+        (code.includes('createRoute(') || code.includes('createFileRoute('))
+      ) {
+        for (const externalPlugin of bannedBeforeExternalPlugins) {
+          if (!externalPlugin.frameworks.includes(framework)) {
+            continue
+          }
+
+          if (code.includes(externalPlugin.identifier)) {
+            throw new FoundPluginInBeforeCode(externalPlugin, framework)
+          }
+        }
+
+        return handleCompilingReferenceFile(code, id)
+      }
+
+      return null
+    },
+
+    transformInclude(id) {
+      if (!userConfig.autoCodeSplitting) {
+        return undefined
+      }
+
+      if (
+        fileIsInRoutesDirectory(id, userConfig.routesDirectory) ||
+        id.includes(tsrSplit)
+      ) {
+        return true
+      }
+      return false
+    },
+
+    vite: {
+      configResolved(config) {
+        ROOT = config.root
+
+        userConfig = getConfig(options, ROOT)
+      },
+    },
+
+    rspack(_compiler) {
+      ROOT = process.cwd()
+      userConfig = getConfig(options, ROOT)
+    },
+
+    webpack(compiler) {
+      ROOT = process.cwd()
+      userConfig = getConfig(options, ROOT)
+
+      if (
+        userConfig.autoCodeSplitting &&
+        compiler.options.mode === 'production'
+      ) {
+        compiler.hooks.done.tap(PLUGIN_NAME, () => {
+          console.info('✅ ' + PLUGIN_NAME + ': code-splitting done!')
+          setTimeout(() => {
+            process.exit(0)
+          })
+        })
+      }
+    },
+  }
+}

package/src/core/router-composed-plugin.ts

@@ -0,0 +1,32 @@
+import { unpluginRouterGeneratorFactory } from './router-generator-plugin'
+import { unpluginRouterCodeSplitterFactory } from './router-code-splitter-plugin'
+import { unpluginRouterHmrFactory } from './router-hmr-plugin'
+import { unpluginRouteAutoimportFactory } from './route-autoimport-plugin'
+import type { Config } from './config'
+import type { UnpluginFactory } from 'unplugin'
+
+export const unpluginRouterComposedFactory: UnpluginFactory<
+  Partial<Config> | undefined
+> = (options = {}, meta) => {
+  const getPlugin = (pluginFactory: UnpluginFactory<Partial<Config>>) => {
+    const plugin = pluginFactory(options, meta)
+    if (!Array.isArray(plugin)) {
+      return [plugin]
+    }
+    return plugin
+  }
+
+  const routerGenerator = getPlugin(unpluginRouterGeneratorFactory)
+  const routerCodeSplitter = getPlugin(unpluginRouterCodeSplitterFactory)
+  const routeAutoImport = getPlugin(unpluginRouteAutoimportFactory)
+
+  const result = [...routerGenerator, ...routerCodeSplitter, ...routeAutoImport]
+
+  const isProduction = process.env.NODE_ENV === 'production'
+
+  if (!isProduction && !options.autoCodeSplitting) {
+    const routerHmr = getPlugin(unpluginRouterHmrFactory)
+    result.push(...routerHmr)
+  }
+  return result
+}