Skip to content

Commit fe040c0

Browse files
committed
docs(rfc): keep Vite+ built-in templates reachable via org picker
When `create.defaultTemplate: '@org'` is set, bare `vp create` now drops into the org picker with a trailing "Vite+ built-in templates" escape-hatch entry that routes to the existing `getInitialTemplateOptions` flow. This preserves interactive discovery of `vite:monorepo` / `vite:application` / `vite:library` / `vite:generator` without adding a new CLI flag; explicit specifiers (e.g. `vp create vite:application`) remain the scripted bypass. Addresses @cpojer's review feedback on #1398.
1 parent 6c8c134 commit fe040c0

1 file changed

Lines changed: 72 additions & 5 deletions

File tree

rfcs/create-org-default-templates.md

Lines changed: 72 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# RFC: Organization Default Templates for `vp create`
22

3-
> Status: Draft (Round 2) — all initial open questions resolved. See the
4-
> "Resolved Decisions" section at the bottom for the settled list.
3+
> Status: Draft (Round 3) — addresses PR #1398 review feedback on keeping
4+
> Vite+ built-in templates reachable when `create.defaultTemplate` is set.
5+
> See the "Resolved Decisions" section at the bottom for the settled list.
56
67
## Summary
78

@@ -293,6 +294,57 @@ export default defineConfig({
293294
prompt for template name (today's behavior when bare `vp create` is typed with
294295
no argument and no default).
295296

297+
### Keeping access to the Vite+ built-in templates
298+
299+
Setting `create.defaultTemplate` should never _hide_ the Vite+ built-in
300+
defaults (`vite:monorepo`, `vite:application`, `vite:library`,
301+
`vite:generator`) from an engineer who needs them. Without an escape hatch,
302+
a repo that ships this config would force every contributor to remember the
303+
exact `vite:*` specifier name, which defeats the purpose of interactive
304+
discovery.
305+
306+
The org picker therefore always appends a trailing "Vite+ built-in
307+
templates" entry. Selecting it drops the user into the existing
308+
`getInitialTemplateOptions` picker
309+
(`packages/cli/src/create/initial-template-options.ts:9-31`) unchanged:
310+
311+
```
312+
? Pick a template from @nkzw
313+
❯ monorepo Full Nakazawa Tech monorepo scaffold
314+
web Web app template (Vite + React)
315+
mobile Mobile app (React Native) template
316+
server Server template (Node + Fastify)
317+
library TypeScript library template
318+
──────────────────
319+
› Vite+ built-in templates Use defaults (monorepo / application / library / generator)
320+
```
321+
322+
Rules:
323+
324+
- The escape-hatch entry is appended by Vite+, not by the org manifest. It
325+
cannot be suppressed by the org — this is an intentional
326+
"user-agency-trumps-config" decision, similar to how most modern package
327+
managers always expose `--help` regardless of project config.
328+
- Selecting it re-enters the standard flow: the picker shown is identical
329+
to what `vp create` renders in a repo without `defaultTemplate` set, and
330+
is itself already context-aware (omits `vite:monorepo` inside a monorepo,
331+
requires a monorepo for `vite:generator`, etc.).
332+
- The entry is placed last, below a separator, so the org's own templates
333+
remain the visually dominant choice.
334+
335+
For scripted / non-interactive use, engineers can bypass the configured
336+
default by passing any template argument directly — `vp create vite:library`,
337+
`vp create vite:application`, etc. No new CLI flag is added; the existing
338+
"pass an explicit specifier" escape hatch is sufficient for CI and scripts.
339+
340+
The `--no-interactive` error output for `vp create @org` mentions this in
341+
the hint line, so an agent reading the table can pivot:
342+
343+
```
344+
hint: rerun with an explicit selection, e.g. `vp create @nkzw/web`,
345+
or use a Vite+ built-in template like `vp create vite:application`.
346+
```
347+
296348
### Intentionally out of scope
297349

298350
- **User-level default** at `~/.vite-plus/config.json`. Deferred to a future
@@ -308,14 +360,17 @@ no argument and no default).
308360

309361
When `@org/create`'s manifest is found, `vp create @org` displays a list
310362
prompt over the **context-filtered** entries (see "Context-aware filtering"
311-
below). Sketch:
363+
below), followed by a trailing **Vite+ built-in templates** entry (see
364+
"Keeping access to the Vite+ built-in templates" above). Sketch:
312365

313366
```
314367
? Pick a template from @nkzw
315368
❯ web Web app template (Vite + React)
316369
mobile Mobile app (React Native) template
317370
server Server template (Node + Fastify)
318371
library TypeScript library template
372+
──────────────────
373+
› Vite+ built-in templates Use defaults (monorepo / application / library / generator)
319374
```
320375

321376
### Context-aware filtering
@@ -374,7 +429,8 @@ available templates from @nkzw/create:
374429
server Server template (Node + Fastify) github:nkzw-tech/template-server
375430
library TypeScript library template @nkzw/template-library
376431
377-
hint: rerun with an explicit selection, e.g. `vp create @nkzw/web`.
432+
hint: rerun with an explicit selection, e.g. `vp create @nkzw/web`,
433+
or use a Vite+ built-in template like `vp create vite:application`.
378434
```
379435

380436
Notes:
@@ -584,6 +640,7 @@ Fixture additions under `packages/cli/snap-tests-global/create-org-*`:
584640
| `create-org-invalid-manifest` | Invalid `vp.templates` produces a schema error |
585641
| `create-org-monorepo-filter` | `monorepo: true` entries hidden from picker and `--no-interactive` output when run inside a monorepo |
586642
| `create-org-monorepo-direct-in-monorepo` | `vp create @org/<monorepo-entry>` errors with "cannot create a monorepo inside an existing monorepo" |
643+
| `create-org-builtin-escape-hatch` | Org picker always ends with a "Vite+ built-in templates" entry that routes to `getInitialTemplateOptions` |
587644

588645
Unit tests:
589646

@@ -658,7 +715,11 @@ export default defineConfig({
658715
```bash
659716
# Inside that repo: engineers just type `vp create`
660717
vp create
661-
# → picker from @acme/create
718+
# → picker from @acme/create, plus a trailing
719+
# "Vite+ built-in templates" entry for users who need vite:library etc.
720+
721+
# Explicit builtin (bypasses the configured default)
722+
vp create vite:library
662723
```
663724

664725
### Mixed-specifier manifest
@@ -700,6 +761,12 @@ vp create
700761
user explicitly typed `@org`. Users on flaky networks get a clear,
701762
actionable error instead of mysteriously running a single-template
702763
fallback.
764+
- **Built-in templates always reachable from the org picker**: when
765+
`create.defaultTemplate` is set, the org picker appends a trailing "Vite+
766+
built-in templates" entry that routes to the existing
767+
`getInitialTemplateOptions` flow. No new CLI flag; explicit specifiers
768+
like `vp create vite:application` remain the scripted escape hatch.
769+
(Resolves review feedback on #1398.)
703770
- **Local test fixtures only**: snap-tests and unit tests use a local mock
704771
registry / stubbed `fetch`. No dedicated published fixture package —
705772
registry-surface regressions are low-frequency and caught downstream.

0 commit comments

Comments
 (0)