feat(cli): add include-examples toggle for demo content

Author: tannerlinsley

docs/cli-reference.md

@@ -17,9 +17,10 @@ tanstack create [project-name] [options]
 | `--starter <url>` | Starter URL or local path |
 | `--package-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun`, `deno` |
 | `--framework <name>` | `React`, `Solid` |
-| `--router-only` | Create Router-only SPA without TanStack Start (no SSR) |
+| `--router-only` | Create file-based Router-only app without TanStack Start (add-ons/deployment/starter disabled) |
 | `--toolchain <id>` | Toolchain add-on (use `--list-add-ons` to see options) |
 | `--deployment <id>` | Deployment add-on (use `--list-add-ons` to see options) |
+| `--examples` / `--no-examples` | Include or exclude demo/example pages |
 | `--tailwind` / `--no-tailwind` | Deprecated compatibility flags; accepted but ignored (Tailwind is always enabled) |
 | `--no-git` | Skip git init |
 | `--no-install` | Skip dependency install |
@@ -36,7 +37,7 @@ tanstack create [project-name] [options]
 # Examples
 tanstack create my-app -y
 tanstack create my-app --add-ons clerk,drizzle,tanstack-query
-tanstack create my-app --router-only --add-ons tanstack-query
+tanstack create my-app --router-only --toolchain eslint --no-examples
 tanstack create my-app --starter https://example.com/starter.json
 ```
 

packages/cli/src/cli.ts

@@ -466,6 +466,8 @@ export function cli({
         '--no-tailwind',
         'Deprecated: compatibility flag; Tailwind opt-out is ignored',
       )
+      .option('--examples', 'include demo/example pages')
+      .option('--no-examples', 'exclude demo/example pages')
 
     if (deployments.size > 0) {
       cmd.option<string>(

packages/cli/src/command-line.ts

@@ -191,7 +191,11 @@ export async function normalizeOptions(
     return []
   }
 
-  const chosenAddOns = await selectAddOns()
+  const includeExamples = cliOptions.examples ?? !routerOnly
+  const chosenAddOnsRaw = await selectAddOns()
+  const chosenAddOns = includeExamples
+    ? chosenAddOnsRaw
+    : chosenAddOnsRaw.filter((addOn) => addOn.type !== 'example')
 
   // Handle add-on configuration option
   let addOnOptionsFromCLI = {}
@@ -204,7 +208,7 @@ export async function normalizeOptions(
     }
   }
 
-  return {
+  const normalized = {
     projectName: projectName,
     targetDir,
     framework,
@@ -224,6 +228,11 @@ export async function normalizeOptions(
     },
     starter: starter,
   }
+
+  ;(normalized as Options & { includeExamples?: boolean }).includeExamples =
+    includeExamples
+
+  return normalized
 }
 
 export function validateDevWatchOptions(cliOptions: CliOptions): {

packages/cli/src/options.ts

@@ -13,6 +13,7 @@ import {
   promptForAddOnOptions,
   selectAddOns,
   selectDeployment,
+  selectExamples,
   selectGit,
   selectPackageManager,
   selectToolchain,
@@ -92,6 +93,12 @@ export async function promptForCreateOptions(
   // Add-ons selection
   const addOns: Set<string> = new Set()
 
+  // Examples/demo pages are enabled by default
+  const includeExamples =
+    cliOptions.examples ?? (routerOnly ? false : await selectExamples())
+  ;(options as Required<Options> & { includeExamples?: boolean }).includeExamples =
+    includeExamples
+
   if (toolchain) {
     addOns.add(toolchain)
   }
@@ -123,21 +130,26 @@ export async function promptForCreateOptions(
       addOns.add(addOn)
     }
 
-    for (const addOn of await selectAddOns(
-      options.framework,
-      options.mode,
-      'example',
-      'Would you like an example?',
-      forcedAddOns,
-      false,
-    )) {
-      addOns.add(addOn)
+    if (includeExamples) {
+      for (const addOn of await selectAddOns(
+        options.framework,
+        options.mode,
+        'example',
+        'Would you like an example?',
+        forcedAddOns,
+        false,
+      )) {
+        addOns.add(addOn)
+      }
     }
   }
 
-  options.chosenAddOns = Array.from(
+  const chosenAddOns = Array.from(
     await finalizeAddOns(options.framework, options.mode, Array.from(addOns)),
   )
+  options.chosenAddOns = includeExamples
+    ? chosenAddOns
+    : chosenAddOns.filter((addOn) => addOn.type !== 'example')
 
   // Tailwind is always enabled
   options.tailwind = true

packages/cli/src/types.ts

@@ -23,4 +23,5 @@ export interface CliOptions {
   routerOnly?: boolean
   template?: string
   tailwind?: boolean
+  examples?: boolean
 }

packages/cli/src/ui-prompts.ts

@@ -151,6 +151,18 @@ export async function selectGit(): Promise<boolean> {
   return git
 }
 
+export async function selectExamples(): Promise<boolean> {
+  const includeExamples = await confirm({
+    message: 'Would you like to include demo/example pages?',
+    initialValue: true,
+  })
+  if (isCancel(includeExamples)) {
+    cancel('Operation cancelled.')
+    process.exit(0)
+  }
+  return includeExamples
+}
+
 export async function selectToolchain(
   framework: Framework,
   toolchain?: string | false,

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

@@ -300,6 +300,23 @@ describe('normalizeOptions', () => {
     expect(options?.mode).toBe('file-router')
   })
 
+  it('includes examples by default in non-router-only mode', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+    })
+
+    expect((options as any)?.includeExamples).toBe(true)
+  })
+
+  it('supports disabling examples from the CLI', async () => {
+    const options = await normalizeOptions({
+      projectName: 'test',
+      examples: false,
+    })
+
+    expect((options as any)?.includeExamples).toBe(false)
+  })
+
   it('should ignore add-ons and deployment in router-only mode but keep toolchain', async () => {
     __testRegisterFramework({
       id: 'react-cra',

packages/create/src/create-app.ts

@@ -16,6 +16,51 @@ import { runSpecialSteps } from './special-steps/index.js'
 
 import type { Environment, FileBundleHandler, Options } from './types.js'
 
+function isDemoRoutePath(path?: string) {
+  if (!path) return false
+  const normalized = path.replace(/\\/g, '/')
+  return (
+    normalized.includes('/routes/demo/') ||
+    normalized.includes('/routes/demo.') ||
+    normalized.includes('/routes/example/') ||
+    normalized.includes('/routes/example.')
+  )
+}
+
+function stripExamplesFromOptions(options: Options): Options {
+  if (options.includeExamples !== false) {
+    return options
+  }
+
+  const chosenAddOns = options.chosenAddOns
+    .filter((addOn) => addOn.type !== 'example')
+    .map((addOn) => {
+      const filteredRoutes = (addOn.routes || []).filter(
+        (route) =>
+          !isDemoRoutePath(route.path) &&
+          !(route.url && route.url.startsWith('/demo')),
+      )
+
+      return {
+        ...addOn,
+        routes: filteredRoutes,
+        getFiles: async () => {
+          const files = await addOn.getFiles()
+          return files.filter((file) => !isDemoRoutePath(file))
+        },
+        getDeletedFiles: async () => {
+          const deletedFiles = await addOn.getDeletedFiles()
+          return deletedFiles.filter((file) => !isDemoRoutePath(file))
+        },
+      }
+    })
+
+  return {
+    ...options,
+    chosenAddOns,
+  }
+}
+
 async function writeFiles(environment: Environment, options: Options) {
   const templateFileFromContent = createTemplateFile(environment, options)
 
@@ -282,10 +327,12 @@ Please read the README.md file for information on testing, styling, adding route
 }
 
 export async function createApp(environment: Environment, options: Options) {
+  const effectiveOptions = stripExamplesFromOptions(options)
+
   environment.startRun()
-  await writeFiles(environment, options)
-  await runCommandsAndInstallDependencies(environment, options)
+  await writeFiles(environment, effectiveOptions)
+  await runCommandsAndInstallDependencies(environment, effectiveOptions)
   environment.finishRun()
 
-  report(environment, options)
+  report(environment, effectiveOptions)
 }

packages/create/src/types.ts

@@ -207,6 +207,7 @@ export interface Options {
   addOnOptions: Record<string, Record<string, any>>
   starter?: Starter | undefined
   routerOnly?: boolean
+  includeExamples?: boolean
 }
 
 export type SerializedOptions = Omit<