Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/interactive-router-mode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@tanstack/cli": minor
---

Offer Router-only scaffolding interactively and add `--router-and-start` to choose Start explicitly. Preserve requested Start integrations when selecting the app mode or using legacy template aliases.
1 change: 1 addition & 0 deletions docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ tanstack create [project-name] [options]
| `--framework <name>` | `React`, `Solid` |
| `--build-tool <name>` | `vite` (default), `rsbuild` |
| `--router-only` | Create file-based Router-only app without TanStack Start (add-ons/deployment/template disabled) |
| `--router-and-start` | Use TanStack Start explicitly (skips the interactive router-only prompt) |
| `--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 |
Expand Down
29 changes: 29 additions & 0 deletions packages/cli/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@ export function getCreateTelemetryProperties(projectName: string, options: CliOp
package_manager: options.packageManager,
project_name_provided: Boolean(projectName),
router_only: !!options.routerOnly,
router_and_start: !!options.routerAndStart,
target_dir_flag: Boolean(options.targetDir),
toolchain:
typeof options.toolchain === 'string' ? sanitizeId(options.toolchain) : undefined,
Expand Down Expand Up @@ -233,6 +234,7 @@ export function getResolvedCreateTelemetryProperties(
intent: finalOptions.intent,
package_manager: finalOptions.packageManager,
router_only: !!cliOptions.routerOnly,
router_and_start: !!cliOptions.routerAndStart,
toolchain: toolchain ? sanitizeId(toolchain.id) : undefined,
}
}
Expand Down Expand Up @@ -826,6 +828,29 @@ export function cli({
...options,
} as CliOptions

if (cliOptions.routerAndStart) {
if (cliOptions.routerOnly) {
throw new Error(
'Cannot combine --router-only with --router-and-start.',
)
}
if (
cliOptions.template &&
['typescript', 'tsx', 'javascript', 'js', 'jsx'].includes(
cliOptions.template.trim().toLowerCase(),
)
) {
console.warn(
styleText(
'yellow',
'Ignoring --template in favor of --router-and-start (TanStack Start).',
),
)
cliOptions.template = undefined
}
cliOptions.routerOnly = false
}

if (defaultRouterOnly && cliOptions.routerOnly === undefined) {
cliOptions.routerOnly = true
}
Expand Down Expand Up @@ -1025,6 +1050,10 @@ export function cli({
'--router-only',
'Use router-only compatibility mode (file-based routing without TanStack Start)',
)
.option(
'--router-and-start',
'Use TanStack Start explicitly (skips the interactive router-only prompt)',
)
.option(
'--blank',
'Create a minimal one-route app without default starter UI, Tailwind, devtools, or tests',
Expand Down
20 changes: 19 additions & 1 deletion packages/cli/src/options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import {
selectGit,
selectInstall,
selectPackageManager,
selectRouterOnly,
selectTemplate,
selectToolchain,
} from './ui-prompts.js'
Expand Down Expand Up @@ -121,9 +122,26 @@ export async function promptForCreateOptions(
['file-router', 'typescript', 'tsx', 'javascript', 'js', 'jsx'].includes(
template,
)
const hasStartIntent = Boolean(
cliOptions.template ||
cliOptions.templateId ||
cliOptions.starter ||
cliOptions.blank ||
(Array.isArray(cliOptions.addOns) && cliOptions.addOns.length > 0) ||
cliOptions.deployment ||
forcedAddOns.length > 0 ||
forcedDeployment,
)
const routerOnly =
!!cliOptions.routerOnly ||
(isLegacyTemplate ? template !== 'file-router' : false)
(isLegacyTemplate ? template !== 'file-router' : false) ||
(cliOptions.routerOnly === undefined &&
!isLegacyTemplate &&
!hasStartIntent &&
(await selectRouterOnly()))
if (routerOnly) {
cliOptions.routerOnly = true
}

if (!cliOptions.starter) {
if (cliOptions.template && !isLegacyTemplate) {
Expand Down
1 change: 1 addition & 0 deletions packages/cli/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ export interface CliOptions {
addOnConfig?: string
force?: boolean
routerOnly?: boolean
routerAndStart?: boolean
blank?: boolean
template?: string
tailwind?: boolean
Expand Down
12 changes: 12 additions & 0 deletions packages/cli/src/ui-prompts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,18 @@ export async function selectFramework(
return framework
}

export async function selectRouterOnly(): Promise<boolean> {
const routerOnly = await confirm({
message: 'Use Tanstack Router without Start?',
initialValue: false,
})
if (isCancel(routerOnly)) {
cancel('Operation cancelled.')
process.exit(0)
}
return routerOnly
}

export async function selectInstall(): Promise<boolean> {
const install = await confirm({
message: 'Would you like to install dependencies now?',
Expand Down
48 changes: 48 additions & 0 deletions packages/cli/tests-e2e/blank-smoke.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -251,3 +251,51 @@ test('@blocking creates a production-valid blank React app', async ({
}
}
})


for (const template of [' tsx ', ' TypeScript ']) {
test(`@blocking preserves explicit Start integrations with legacy alias ${JSON.stringify(template)}`, async () => {
const rootDir = await mkdtemp(join(tmpdir(), 'tanstack-explicit-start-'))
try {
await execFileAsync(
process.execPath,
[
getRepoPath('packages/cli/dist/index.js'),
'create',
'start-app',
'--router-and-start',
'--template',
template,
'--add-ons',
'tanstack-query',
'--deployment',
'cloudflare',
'--toolchain',
'biome',
'--package-manager',
'npm',
'--yes',
'--no-install',
'--no-git',
'--no-intent',
],
{ cwd: rootDir, encoding: 'utf8' },
)
const appDir = join(rootDir, 'start-app')
const config = JSON.parse(
await readFile(join(appDir, '.cta.json'), 'utf8'),
)
const pkg = JSON.parse(
await readFile(join(appDir, 'package.json'), 'utf8'),
)
expect(config.routerOnly).toBe(false)
expect(config.chosenAddOns).toEqual(
expect.arrayContaining(['tanstack-query', 'cloudflare']),
)
expect(pkg.dependencies['@tanstack/react-start']).toBeDefined()
expect(pkg.dependencies['@tanstack/react-query']).toBeDefined()
} finally {
await rm(rootDir, { recursive: true, force: true })
}
})
}
81 changes: 81 additions & 0 deletions packages/cli/tests/options.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,11 @@ beforeEach(() => {
modes: ['file-router'],
exclusive: ['linter'],
},
{
id: 'cloudflare',
type: 'deployment',
modes: ['file-router'],
},
{
id: 'eslint',
type: 'toolchain',
Expand Down Expand Up @@ -93,6 +98,7 @@ const baseCliOptions: CliOptions = {
}

function setBasicSpies() {
vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(false)
vi.spyOn(prompts, 'selectBundler').mockImplementation(async () => 'vite')
vi.spyOn(commandLine, 'listTemplateChoices').mockImplementation(async () => [])
vi
Expand Down Expand Up @@ -453,3 +459,78 @@ describe('promptForAddOns', () => {
expect(prompts.selectAddOns).not.toHaveBeenCalled()
})
})

describe('interactive Router-only selection', () => {
it.each([
{
label: 'explicit add-ons',
flags: { addOns: ['react-query'] },
defaults: {},
expected: ['react-query'],
},
{
label: 'explicit deployment',
flags: { deployment: 'cloudflare' },
defaults: {},
expected: ['cloudflare'],
},
{
label: 'legacy template id',
flags: { templateId: 'blog' },
defaults: {},
expected: [],
},
{
label: 'blank preset',
flags: { blank: true },
defaults: {},
expected: [],
},
{
label: 'forced add-ons',
flags: {},
defaults: { forcedAddOns: ['react-query'] },
expected: ['react-query'],
},
{
label: 'forced deployment',
flags: {},
defaults: { forcedDeployment: 'cloudflare' },
expected: ['cloudflare'],
},
])('keeps Start mode for $label', async ({ flags, defaults, expected }) => {
setBasicSpies()
vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(true)
vi.spyOn(prompts, 'selectDeployment').mockImplementation(
async (_framework, provided, forced) => provided ?? forced,
)
const cliOptions: CliOptions = {
...baseCliOptions,
projectName: 'start-intent',
git: false,
install: false,
...flags,
}
const result = await promptForCreateOptions(cliOptions, defaults)
expect(prompts.selectRouterOnly).not.toHaveBeenCalled()
expect(cliOptions.routerOnly).not.toBe(true)
expect(result?.chosenAddOns.map((addOn) => addOn.id)).toEqual(expected)
})

it('still offers Router-only when only a toolchain is requested', async () => {
setBasicSpies()
vi.spyOn(prompts, 'selectRouterOnly').mockResolvedValue(true)
vi.spyOn(prompts, 'selectToolchain').mockResolvedValue('biome')
const cliOptions: CliOptions = {
...baseCliOptions,
projectName: 'router-choice',
toolchain: 'biome',
git: false,
install: false,
}
const result = await promptForCreateOptions(cliOptions, {})
expect(prompts.selectRouterOnly).toHaveBeenCalledOnce()
expect(cliOptions.routerOnly).toBe(true)
expect(result?.chosenAddOns.map((addOn) => addOn.id)).toEqual(['biome'])
})
})
Loading