feat(cli): restore router-only file-router compatibility mode

Author: tannerlinsley

cli-aliases/create-tsrouter-app/src/index.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-console.warn('\x1b[33m%s\x1b[0m', 'Warning: create-tsrouter-app is deprecated. Use "tanstack create" or "npx @tanstack/cli create" instead.')
-console.warn('\x1b[33m%s\x1b[0m', '         This will now create a TanStack Start app (with SSR). See: https://tanstack.com/start/latest/docs/framework/react/quick-start\n')
+console.warn('\x1b[33m%s\x1b[0m', 'Warning: create-tsrouter-app is deprecated. Use "tanstack create --router-only" or "npx @tanstack/cli create --router-only" instead.')
+console.warn('\x1b[33m%s\x1b[0m', '         This defaults to router-only compatibility mode (file-based routing, no Start-specific add-ons).\n')
 
 import { cli } from '@tanstack/cli'
 
 cli({
   name: 'create-tsrouter-app',
-  appName: 'TanStack Start',
+  appName: 'TanStack',
   legacyAutoCreate: true,
+  defaultRouterOnly: true,
 })

packages/cli/src/cli.ts

@@ -55,6 +55,7 @@ export function cli({
   frameworkDefinitionInitializers,
   showDeploymentOptions = false,
   legacyAutoCreate = false,
+  defaultRouterOnly = false,
 }: {
   name: string
   appName: string
@@ -65,6 +66,7 @@ export function cli({
   frameworkDefinitionInitializers?: Array<() => FrameworkDefinition>
   showDeploymentOptions?: boolean
   legacyAutoCreate?: boolean
+  defaultRouterOnly?: boolean
 }) {
   const environment = createUIEnvironment(appName, false)
 
@@ -307,6 +309,18 @@ export function cli({
         ...options,
       } as CliOptions
 
+      if (defaultRouterOnly && cliOptions.routerOnly === undefined) {
+        cliOptions.routerOnly = true
+      }
+
+      if (
+        cliOptions.routerOnly !== true &&
+        cliOptions.template &&
+        cliOptions.template.toLowerCase() !== 'file-router'
+      ) {
+        cliOptions.routerOnly = true
+      }
+
       cliOptions.framework = getFrameworkByName(
         options.framework || defaultFramework || 'React',
       )!.id
@@ -359,6 +373,9 @@ export function cli({
         throw new Error('No options were provided')
       }
 
+      ;(finalOptions as Options & { routerOnly?: boolean }).routerOnly =
+        !!cliOptions.routerOnly
+
       // Determine target directory:
       // 1. Use --target-dir if provided
       // 2. Use targetDir from normalizeOptions if set (handles "." case)
@@ -435,7 +452,7 @@ export function cli({
       )
       .option(
         '--router-only',
-        'Deprecated: compatibility flag from create-tsrouter-app',
+        'Use router-only compatibility mode (file-based routing without TanStack Start)',
       )
       .option(
         '--template <type>',

packages/cli/src/command-line.ts

@@ -33,10 +33,26 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
 
   if (cliOptions.routerOnly) {
     warnings.push(
-      'The --router-only flag is deprecated and ignored. `tanstack create` already creates router-based apps.',
+      'The --router-only flag enables router-only compatibility mode. Start-dependent add-ons, deployment adapters, and starters are disabled; only the base template and optional toolchain are supported.',
     )
   }
 
+  if (cliOptions.routerOnly && cliOptions.addOns) {
+    warnings.push(
+      'Ignoring --add-ons in router-only compatibility mode.',
+    )
+  }
+
+  if (cliOptions.routerOnly && cliOptions.deployment) {
+    warnings.push(
+      'Ignoring --deployment in router-only compatibility mode.',
+    )
+  }
+
+  if (cliOptions.routerOnly && cliOptions.starter) {
+    warnings.push('Ignoring --starter in router-only compatibility mode.')
+  }
+
   if (cliOptions.tailwind === true) {
     warnings.push(
       'The --tailwind flag is deprecated and ignored. Tailwind is always enabled in TanStack Start scaffolds.',
@@ -70,9 +86,7 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {
     }
   }
 
-  warnings.push(
-    'The --template flag is deprecated. TypeScript/TSX is the default and only supported template.',
-  )
+  warnings.push('The --template flag is deprecated and mapped for compatibility.')
 
   return { warnings }
 }
@@ -110,8 +124,14 @@ export async function normalizeOptions(
 
   // Mode is always file-router (TanStack Start)
   let mode = 'file-router'
+  let routerOnly = !!cliOptions.routerOnly
+
+  const template = cliOptions.template?.toLowerCase().trim()
+  if (template && template !== 'file-router') {
+    routerOnly = true
+  }
 
-  const starter = cliOptions.starter
+  const starter = !routerOnly && cliOptions.starter
     ? await loadStarter(cliOptions.starter)
     : undefined
 
@@ -143,10 +163,10 @@ export async function normalizeOptions(
       cliOptions.deployment
     ) {
       const selectedAddOns = new Set<string>([
-        ...(starter?.dependsOn || []),
-        ...(forcedAddOns || []),
+        ...(routerOnly ? [] : (starter?.dependsOn || [])),
+        ...(routerOnly ? [] : (forcedAddOns || [])),
       ])
-      if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+      if (!routerOnly && cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
         for (const a of cliOptions.addOns) {
           if (a.toLowerCase() === 'start') {
             continue
@@ -157,11 +177,11 @@ export async function normalizeOptions(
       if (cliOptions.toolchain) {
         selectedAddOns.add(cliOptions.toolchain)
       }
-      if (cliOptions.deployment) {
+      if (!routerOnly && cliOptions.deployment) {
         selectedAddOns.add(cliOptions.deployment)
       }
 
-      if (!cliOptions.deployment && opts?.forcedDeployment) {
+      if (!routerOnly && !cliOptions.deployment && opts?.forcedDeployment) {
         selectedAddOns.add(opts.forcedDeployment)
       }
 

packages/cli/src/options.ts

@@ -60,6 +60,9 @@ export async function promptForCreateOptions(
 
   // Mode is always file-router (TanStack Start)
   options.mode = 'file-router'
+  const template = cliOptions.template?.toLowerCase().trim()
+  const routerOnly =
+    !!cliOptions.routerOnly || (template ? template !== 'file-router' : false)
 
   // TypeScript is always enabled with file-router
   options.typescript = true
@@ -81,7 +84,9 @@ export async function promptForCreateOptions(
 
   // Deployment selection
   const deployment = showDeploymentOptions
-    ? await selectDeployment(options.framework, cliOptions.deployment)
+    ? routerOnly
+      ? undefined
+      : await selectDeployment(options.framework, cliOptions.deployment)
     : undefined
 
   // Add-ons selection
@@ -94,18 +99,20 @@ export async function promptForCreateOptions(
     addOns.add(deployment)
   }
 
-  for (const addOn of forcedAddOns) {
-    addOns.add(addOn)
+  if (!routerOnly) {
+    for (const addOn of forcedAddOns) {
+      addOns.add(addOn)
+    }
   }
 
-  if (Array.isArray(cliOptions.addOns)) {
+  if (!routerOnly && Array.isArray(cliOptions.addOns)) {
     for (const addOn of cliOptions.addOns) {
       if (addOn.toLowerCase() === 'start') {
         continue
       }
       addOns.add(addOn)
     }
-  } else {
+  } else if (!routerOnly) {
     for (const addOn of await selectAddOns(
       options.framework,
       options.mode,

packages/cli/tests/command-line.test.ts

@@ -291,6 +291,56 @@ describe('normalizeOptions', () => {
     expect(options?.typescript).toBe(true)
   })
 
+  it('should keep file-router mode in router-only compatibility mode', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+      routerOnly: true,
+    })
+
+    expect(options?.mode).toBe('file-router')
+  })
+
+  it('should ignore add-ons and deployment in router-only mode but keep toolchain', async () => {
+    __testRegisterFramework({
+      id: 'react-cra',
+      name: 'react',
+      getAddOns: () => [
+        {
+          id: 'form',
+          name: 'Form',
+          modes: ['file-router'],
+        },
+        {
+          id: 'nitro',
+          name: 'nitro',
+          modes: ['file-router'],
+          type: 'deployment',
+        },
+        {
+          id: 'biome',
+          name: 'Biome',
+          modes: ['file-router'],
+          type: 'toolchain',
+        },
+      ],
+    })
+
+    const options = await normalizeOptions(
+      {
+        projectName: 'test',
+        framework: 'react-cra',
+        routerOnly: true,
+        addOns: ['form'],
+        deployment: 'nitro',
+        toolchain: 'biome',
+      },
+      ['form'],
+      { forcedDeployment: 'nitro' },
+    )
+
+    expect(options?.chosenAddOns.map((a) => a.id)).toEqual(['biome'])
+  })
+
   it('should handle the funky Windows edge case with CLI parsing', async () => {
     __testRegisterFramework({
       id: 'react-cra',

packages/create/src/frameworks/react/project/base/index.html.ejs

@@ -0,0 +1,13 @@
+<% if (!routerOnly) { ignoreFile() } %>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

packages/create/src/frameworks/react/project/base/src/main.tsx.ejs

@@ -0,0 +1,24 @@
+<% if (!routerOnly) { ignoreFile() } %>
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { RouterProvider, createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  scrollRestoration: true,
+})
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById('app')!
+
+if (!rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement)
+  root.render(<RouterProvider router={router} />)
+}

packages/create/src/frameworks/react/project/base/src/routes/__root.tsx.ejs

@@ -1,3 +1,33 @@
+<% if (routerOnly) { %>
+import { Outlet, createRootRoute } from '@tanstack/react-router'
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
+import { TanStackDevtools } from '@tanstack/react-devtools'
+
+import '../styles.css'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <>
+      <Outlet />
+      <TanStackDevtools
+        config={{
+          position: 'bottom-right',
+        }}
+        plugins={[
+          {
+            name: 'TanStack Router',
+            render: <TanStackRouterDevtoolsPanel />,
+          },
+        ]}
+      />
+    </>
+  )
+}
+<% } else { %>
 <% let hasContext = addOnEnabled["apollo-client"] || addOnEnabled["tanstack-query"]; %>
 import {
   HeadContent, Scripts, <% if (hasContext) { %>createRootRouteWithContext<% } else { %>createRootRoute<% } %> } from '@tanstack/react-router'
@@ -93,3 +123,4 @@ function RootDocument({ children }: { children: React.ReactNode }) {
     </html>
   )
 }
+<% } %>

packages/create/src/frameworks/react/project/base/vite.config.ts.ejs

@@ -4,7 +4,11 @@ import tsconfigPaths from 'vite-tsconfig-paths'
 <% if (addOnEnabled.paraglide) { -%>
 import { paraglideVitePlugin } from "@inlang/paraglide-js"
 <% } -%>
+<% if (routerOnly) { %>
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+<% } else { %>
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+<% } %>
 import viteReact from '@vitejs/plugin-react'
 import tailwindcss from "@tailwindcss/vite"
 <% for(const integration of integrations.filter(i => i.type === 'vite-plugin')) { %><%- integrationImportContent(integration) %>
@@ -18,7 +22,7 @@ const config = defineConfig({
   }), <% } %><% for(const integration of integrations.filter(i => i.type === 'vite-plugin')) { %><%- integrationImportCode(integration) %>,<% } %>
     tsconfigPaths({ projects: ['./tsconfig.json'] }),
     tailwindcss(),
-    tanstackStart(),
+    <% if (routerOnly) { %>tanstackRouter({ target: 'react', autoCodeSplitting: true }),<% } else { %>tanstackStart(),<% } %>
     viteReact(<% if (addOnEnabled.compiler) { %>{
       babel: {
         plugins: ["babel-plugin-react-compiler"],

packages/create/src/frameworks/solid/project/base/index.html.ejs

@@ -0,0 +1,13 @@
+<% if (!routerOnly) { ignoreFile() } %>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>