Skip to content
Open
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
6 changes: 6 additions & 0 deletions .changeset/router-only-addon-selection.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@tanstack/cli": minor
"@tanstack/create": minor
---

Allow compatible add-ons during Router-only app creation, including interactive selection. Declare Router-only support explicitly and reject Start-dependent add-ons instead of silently dropping requested integrations.
2 changes: 1 addition & 1 deletion docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ tanstack create [project-name] [options]
| `--package-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun`, `deno` |
| `--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-only` | Create file-based Router-only app without TanStack Start (compatible add-ons supported; deployment/template 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 |
Expand Down
5 changes: 5 additions & 0 deletions docs/creating-add-ons.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,11 @@ If you are actively editing templates, run `tanstack add-on dev` to auto-refresh
- Publish `.add-on` contents to a stable URL.
- Prefer immutable/versioned URLs for production use.


## Router-only compatibility

Set `"supportsRouterOnly": true` in `info.json` only when the add-on works without TanStack Start. This makes it available during Router-only creation. Every dependency must also support Router-only apps. Toolchains remain available without this flag; deployment adapters and templates remain disabled.

## Maintenance Checklist

When you update a custom add-on:
Expand Down
7 changes: 3 additions & 4 deletions packages/cli/skills/create-app-scaffold/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,15 +138,14 @@ Templates, examples, and `--tailwind` replace the output constraints that
toolchain, and add-on selections remain supported; a selected styling add-on
can opt the generated app back into Tailwind when it requires it.

### CRITICAL Combine router-only with template/deployment/add-ons
### CRITICAL Combine router-only with a template or deployment

Wrong:
```bash
npx @tanstack/cli create my-app \
--router-only \
--template some-template \
--deployment cloudflare \
--add-ons clerk \
-y
```

Expand All @@ -155,13 +154,13 @@ Correct:
npx @tanstack/cli create my-app --router-only --framework react -y
```

Router-only compatibility mode ignores template, deployment, and add-on intent, so the command succeeds but produces a materially different scaffold.
Router-only compatibility mode ignores template and deployment intent. Compatible add-ons can be selected interactively or passed with `--add-ons`; unsupported Start-dependent add-ons are rejected.

Source: packages/cli/src/command-line.ts:343

### HIGH Tension: Compatibility mode vs explicit intent

This domain's patterns conflict with choose-ecosystem-integrations. Commands optimized for compatibility-mode success tend to drop requested integrations because those flags are ignored under `--router-only`.
This domain's patterns conflict with choose-ecosystem-integrations. Template and deployment flags are ignored under `--router-only`, so those requests need a full scaffold. Compatible add-on selections are retained; unsupported Start-dependent add-ons are rejected.

See also: choose-ecosystem-integrations/SKILL.md § Common Mistakes

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Targets `@tanstack/cli` v0.71.0.
| `--framework` | yes | yes | Framework is still honored in both modes. |
| `--build-tool` | yes | yes | `vite` is the default; `rsbuild` supports React and Solid. |
| `--toolchain` | yes | yes | Toolchain selection remains available. |
| `--add-ons` | yes | no | Ignored in router-only mode. |
| `--add-ons` | yes | compatible only | Requires explicit Router-only support; unsupported add-ons are rejected. |
| `--deployment` | yes | no | Ignored in router-only mode. |
| `--template` / `--starter` | yes | no | Ignored in router-only mode. |
| `--template-id` | yes | no | Ignored in router-only mode. |
Expand Down
14 changes: 4 additions & 10 deletions packages/cli/src/command-line.ts
Original file line number Diff line number Diff line change
Expand Up @@ -391,13 +391,7 @@ export function validateLegacyCreateFlags(cliOptions: CliOptions): {

if (cliOptions.routerOnly) {
warnings.push(
'The --router-only flag enables router-only compatibility mode. Start-dependent add-ons, deployment adapters, and templates 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.',
'The --router-only flag enables router-only compatibility mode. Only compatible add-ons and toolchains are supported; deployment adapters and templates are disabled.',
)
}

Expand Down Expand Up @@ -572,9 +566,9 @@ export async function normalizeOptions(
) {
const selectedAddOns = new Set<string>([
...(routerOnly ? [] : (starter?.dependsOn || [])),
...(routerOnly ? [] : (forcedAddOns || [])),
...(forcedAddOns || []),
])
if (!routerOnly && cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
for (const a of cliOptions.addOns) {
if (a.toLowerCase() === 'start') {
continue
Expand All @@ -593,7 +587,7 @@ export async function normalizeOptions(
selectedAddOns.add(opts.forcedDeployment)
}

return await finalizeAddOns(framework, mode, Array.from(selectedAddOns), bundler)
return await finalizeAddOns(framework, mode, Array.from(selectedAddOns), bundler, routerOnly)
}

return []
Expand Down
15 changes: 9 additions & 6 deletions packages/cli/src/options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -211,34 +211,37 @@ export async function promptForCreateOptions(
addOns.add(deployment)
}

if (!routerOnly && options.bundler !== 'rsbuild') {
for (const addOn of starter?.dependsOn || []) {
if (options.bundler !== 'rsbuild') {
for (const addOn of (!routerOnly && starter?.dependsOn) || []) {
addOns.add(addOn)
}
for (const addOn of forcedAddOns) {
addOns.add(addOn)
}
}

if (!routerOnly && options.bundler !== 'rsbuild' && Array.isArray(cliOptions.addOns)) {
if (options.bundler !== 'rsbuild' && Array.isArray(cliOptions.addOns)) {
for (const addOn of cliOptions.addOns) {
if (addOn.toLowerCase() === 'start') {
continue
}
addOns.add(addOn)
}
} else if (!routerOnly && options.bundler !== 'rsbuild' && !blank) {
} else if (options.bundler !== 'rsbuild' && !blank) {
for (const addOn of await selectAddOns(
options.framework,
options.mode,
'add-on',
'What add-ons would you like for your project?',
forcedAddOns,
true,
options.bundler,
routerOnly,
)) {
addOns.add(addOn)
}

if (includeExamples) {
if (includeExamples && !routerOnly) {
for (const addOn of await selectAddOns(
options.framework,
options.mode,
Expand All @@ -253,7 +256,7 @@ export async function promptForCreateOptions(
}

const chosenAddOns = Array.from(
await finalizeAddOns(options.framework, options.mode, Array.from(addOns), options.bundler),
await finalizeAddOns(options.framework, options.mode, Array.from(addOns), options.bundler, routerOnly),
)
options.chosenAddOns = includeExamples
? chosenAddOns
Expand Down
3 changes: 2 additions & 1 deletion packages/cli/src/ui-prompts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -182,8 +182,9 @@ export async function selectAddOns(
forcedAddOns: Array<string> = [],
allowMultiple: boolean = true,
bundlerId?: string,
routerOnly = false,
): Promise<Array<string>> {
const allAddOns = await getAllAddOns(framework, mode, bundlerId)
const allAddOns = await getAllAddOns(framework, mode, bundlerId, routerOnly)
const addOns = allAddOns.filter((addOn) => addOn.type === type)
if (addOns.length === 0) {
return []
Expand Down
50 changes: 50 additions & 0 deletions packages/cli/tests-e2e/router-addons-smoke.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
import { readFile, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { expect, test } from '@playwright/test'
import { attachRuntimeGuards, createAppFixture, optimizePageForFastE2E } from './helpers'

const scenarios = [
{ framework: 'react', addOns: ['tanstack-query'], tag: '@blocking' },
{ framework: 'solid', addOns: ['tanstack-query'], tag: '@blocking' },
{ framework: 'react', addOns: ['shadcn', 't3env', 'tanstack-query', 'paraglide', 'compiler'], tag: '@matrix' },
] as const

for (const { framework, addOns, tag } of scenarios) {
test(`${tag} creates a ${framework} Router-only app with ${addOns.length} add-ons and a working Query provider`, async ({ page }) => {
const fixture = await createAppFixture({
appName: `${framework}-router-query-${addOns.length}`,
framework,
routerOnly: true,
addOns: [...addOns],
runQualityGatesChecks: true,
afterCreate: async (appDir) => {
const config = JSON.parse(await readFile(join(appDir, '.cta.json'), 'utf8'))
expect(config.routerOnly).toBe(true)
expect(config.chosenAddOns).toEqual(expect.arrayContaining([...addOns]))
const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'))
expect(pkg.dependencies[`@tanstack/${framework}-query`]).toBeTruthy()
expect(pkg.dependencies[`@tanstack/${framework}-start`]).toBeUndefined()
await writeFile(join(appDir, 'src/routes/index.tsx'), `
import { createFileRoute } from '@tanstack/${framework}-router'
import { useQueryClient } from '@tanstack/${framework}-query'
export const Route = createFileRoute('/')({ component: Probe })
function Probe() {
const client = useQueryClient()
return <h1>{client ? 'Query provider ready' : 'Missing provider'}</h1>
}
`)
},
})
const guards = attachRuntimeGuards(page, fixture.url)
try {
await optimizePageForFastE2E(page)
await page.goto(fixture.url)
await expect(page.getByRole('heading', { name: 'Query provider ready' })).toBeVisible()
guards.assertClean()
} finally {
guards.dispose()
await fixture.stop()
await fixture.cleanup()
}
})
}
6 changes: 4 additions & 2 deletions packages/cli/tests/command-line.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -737,14 +737,16 @@ describe('normalizeOptions', () => {
])
})

it('should ignore add-ons and deployment in router-only mode but keep toolchain', async () => {
it('preserves compatible Router-only add-ons and toolchains while skipping deployment', async () => {
__testRegisterFramework({
id: 'react',
name: 'react',
getAddOns: () => [
{
id: 'form',
name: 'Form',
type: 'add-on',
supportsRouterOnly: true,
modes: ['file-router'],
},
{
Expand Down Expand Up @@ -775,7 +777,7 @@ describe('normalizeOptions', () => {
{ forcedDeployment: 'nitro' },
)

expect(options?.chosenAddOns.map((a) => a.id)).toEqual(['biome'])
expect(options?.chosenAddOns.map((a) => a.id)).toEqual(['form', 'biome'])
})

it('should handle the funky Windows edge case with CLI parsing', async () => {
Expand Down
14 changes: 14 additions & 0 deletions packages/cli/tests/options.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ beforeEach(() => {
getAddOns: () => [
{
id: 'react-query',
supportsRouterOnly: true,
type: 'add-on',
modes: ['file-router'],
},
Expand Down Expand Up @@ -306,6 +307,19 @@ describe('promptForCreateOptions', () => {
expect(prompts.selectTemplate).not.toHaveBeenCalled()
})

it('offers compatible add-ons during Router-only creation', async () => {
setBasicSpies()
vi.mocked(prompts.selectAddOns).mockResolvedValue(['react-query'])
const options = await promptForCreateOptions(
{ ...baseCliOptions, addOns: undefined, routerOnly: true }, {},
)
expect(prompts.selectAddOns).toHaveBeenCalledWith(
expect.anything(), 'file-router', 'add-on', expect.any(String), [], true, 'vite', true,
)
expect(options?.chosenAddOns.map((a) => a.id)).toEqual(['react-query'])
expect(options?.routerOnly).toBe(true)
})

it('skips template prompt in router-only mode', async () => {
setBasicSpies()

Expand Down
37 changes: 33 additions & 4 deletions packages/create/src/add-ons.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,19 @@ import {

import type { AddOn, Framework } from './types.js'

export function getAllAddOns(framework: Framework, mode: string, bundlerId?: string): Array<AddOn> {
export function getAllAddOns(
framework: Framework,
mode: string,
bundlerId?: string,
routerOnly = false,
): Array<AddOn> {
const bundler = resolveBundler(framework, bundlerId).id
return framework
.getAddOns()
const addOns = framework.getAddOns().filter((addOn) => addOn.modes.includes(mode))
return addOns
.filter(
(addOn) =>
addOn.modes.includes(mode) && isAddOnSupportedByBundler(addOn, bundler),
isAddOnSupportedByBundler(addOn, bundler) &&
(!routerOnly || supportsRouterOnly(addOn, addOns)),
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
)
.sort((a, b) => {
const aPriority = a.priority ?? 0
Expand All @@ -22,12 +28,32 @@ export function getAllAddOns(framework: Framework, mode: string, bundlerId?: str
})
}

function supportsRouterOnly(
addOn: AddOn,
allAddOns: Array<AddOn>,
seen = new Set<string>(),
): boolean {
if (
addOn.type !== 'toolchain' &&
!(addOn.type === 'add-on' && addOn.supportsRouterOnly === true)
) {
return false
}
if (seen.has(addOn.id)) return true
seen.add(addOn.id)
return (addOn.dependsOn || []).every((id) => {
const dependency = allAddOns.find((candidate) => candidate.id === id)
return dependency !== undefined && supportsRouterOnly(dependency, allAddOns, seen)
})
}

// Turn the list of chosen add-on IDs into a final list of add-ons by resolving dependencies
export async function finalizeAddOns(
framework: Framework,
mode: string,
chosenAddOnIDs: Array<string>,
bundlerId?: string,
routerOnly = false,
): Promise<Array<AddOn>> {
const bundler = resolveBundler(framework, bundlerId).id
const finalAddOnIDs = new Set(chosenAddOnIDs)
Expand Down Expand Up @@ -58,6 +84,9 @@ export async function finalizeAddOns(
)
}

if (routerOnly && !supportsRouterOnly(addOn, addOns)) {
throw new Error(`Add-on "${addOn.id}" does not support Router-only apps.`)
}
assertAddOnSupportedByBundler(addOn, bundler)

for (const dependsOn of addOn.dependsOn || []) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"link": "https://react.dev/learn/react-compiler",
"modes": ["code-router", "file-router"],
"type": "add-on",
"supportsRouterOnly": true,
"category": "tooling",
"color": "#61DAFB",
"priority": 50,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<% if (addOnEnabled.vercel && addOnEnabled.sentry) { ignoreFile(); return; } -%>
<% if (routerOnly || (addOnEnabled.vercel && addOnEnabled.sentry)) { ignoreFile(); return; } -%>
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
import { paraglideMiddleware } from './paraglide/server.js'

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"phase": "add-on",
"modes": ["file-router"],
"type": "add-on",
"supportsRouterOnly": true,
"category": "i18n",
"color": "#14B8A6",
"priority": 30,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"modes": ["file-router", "code-router"],
"link": "https://ui.shadcn.com/",
"type": "add-on",
"supportsRouterOnly": true,
"category": "styling",
"tailwind": true,
"color": "#000000",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
"description": "Validate process.env at build time (catch missing/wrong env vars before runtime).",
"phase": "add-on",
"type": "add-on",
"supportsRouterOnly": true,
"category": "tooling",
"color": "#6366F1",
"priority": 29,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"phase": "add-on",
"modes": ["file-router", "code-router"],
"type": "add-on",
"supportsRouterOnly": true,
"category": "tanstack",
"color": "#EF4444",
"priority": 10,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"phase": "add-on",
"modes": ["file-router"],
"type": "add-on",
"supportsRouterOnly": true,
"category": "tanstack",
"color": "#EF4444",
"link": "https://tanstack.com/query/latest",
Expand Down
Loading
Loading