feat(create): support @org default templates (#1398)

Extends `vp create` so an organization can expose a curated set of templates through a single entry point. `vp create @your-org` fetches `@your-org/create`'s `vp.templates` manifest from npm and renders an interactive picker over the listed entries. A `create.defaultTemplate` option in `vite.config.ts` makes an org the default for bare `vp create`. Zero-risk for orgs without a manifest — vp falls back to running `@your-org/create` as today.

**Highlights**

- `vp create @org` → picker (with a `Vite+ built-in templates` escape hatch that stays reachable).
- `vp create @org/<name>` → direct selection; falls back to the existing `@org/create-<name>` shorthand on miss.
- `vp create --no-interactive` inside a repo with `create.defaultTemplate` set → prints the manifest as a machine-parseable table and exits 1.
- Manifest entries accept npm specifiers, GitHub URLs, `vite:*` builtins, local workspace packages, or **bundled subdirectories** (`./templates/foo` extracted from the `@org/create` tarball with SHA-512 integrity into `$VP_HOME/tmp/create-org/...`).
- `monorepo: true` entries are hidden in existing monorepos; direct selection refused with the same message as `vite:monorepo`.

**Spec**: [`rfcs/create-org-default-templates.md`](./rfcs/create-org-default-templates.md) (4 review rounds). **Docs**: [`docs/guide/create.md`](./docs/guide/create.md) § Organization Templates + new [`docs/config/create.md`](./docs/config/create.md).

**Testing**: 264 unit tests pass, 8 snap-test fixtures under `packages/cli/snap-tests/create-org-*` (shared mock-registry helper at `.shared/mock-npm-registry.mjs`).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds new `vp create` resolution paths that fetch and extract `@scope/create` tarballs and read `.npmrc` auth/registry settings; mistakes could break scaffolding flows or introduce edge-case security/file-path issues despite added validation and size/integrity checks.
>
> **Overview**
> **`vp create` now supports organization template catalogs.** `vp create @scope` can fetch `@scope/create`’s `createConfig.templates` manifest from the npm registry, show an interactive picker (with a built-in-templates escape hatch), and allow direct selection via `@scope:<name>` including `--no-interactive` table output.
>
> **Adds bundled-template support and safer registry handling.** Manifest entries can point at relative `./...` paths inside the `@scope/create` tarball, which is downloaded (with registry/`.npmrc` resolution + auth retry), integrity-checked, size-capped, extracted to a cache, and then scaffolded by directory copy; monorepo-only entries are filtered/blocked appropriately.
>
> **Introduces repo defaults and docs/tests.** Adds `create.defaultTemplate` to `vite.config.ts` typing and `vp create` resolution precedence, updates help text and docs (new `docs/config/create.md`, expanded create guide), and adds extensive unit + snap tests plus a mock npm registry harness.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 7cdcde4. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: fengmk2

README.md

@@ -152,6 +152,16 @@ vp create
 
 You can run `vp create` inside of a project to add new apps or libraries to your project.
 
+Organizations can expose a curated set of templates under their npm scope by
+publishing `@org/create` with a `createConfig.templates` manifest in its `package.json`.
+Once published, `vp create @org` opens an interactive picker over those
+templates, and setting `create: { defaultTemplate: '@org' }` in
+`vite.config.ts` makes it the default for bare `vp create`. See the
+[Organization Templates guide](https://viteplus.dev/guide/create#organization-templates)
+for the authoring workflow and
+[`create.defaultTemplate`](https://viteplus.dev/config/create) for the
+config reference.
+
 ### Migrating an existing project
 
 You can migrate an existing project to Vite+:

docs/.vitepress/config.mts

@@ -168,6 +168,7 @@ export default extendConfig(
               text: 'Configuration',
               items: [
                 { text: 'Configuring Vite+', link: '/config/' },
+                { text: 'Create', link: '/config/create' },
                 { text: 'Run', link: '/config/run' },
                 { text: 'Format', link: '/config/fmt' },
                 { text: 'Lint', link: '/config/lint' },

docs/config/create.md

@@ -0,0 +1,35 @@
+# Create Config
+
+`vp create` reads the `create` block in `vite.config.ts` to set per-repo defaults. See the [Creating a Project guide](/guide/create#organization-templates) for the full `@org` template workflow.
+
+## `create.defaultTemplate`
+
+When `vp create` is invoked with no `TEMPLATE` argument, Vite+ uses this value as if the user had typed it. Typically set to an npm scope whose `@scope/create` package publishes a `createConfig.templates` manifest — so bare `vp create` drops into the org picker.
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  create: {
+    defaultTemplate: '@your-org',
+  },
+});
+```
+
+Any value accepted by `vp create` as a first argument works here — `@your-org` for an org picker, `@your-org:web` for a direct manifest entry, `vite:application` for a built-in, etc.
+
+## Precedence
+
+CLI argument > `create.defaultTemplate` > the standard built-in picker.
+
+Explicit specifiers always win, so scripts and CI can bypass the configured default:
+
+```bash
+# Uses create.defaultTemplate
+vp create
+
+# Explicitly ignores the default
+vp create vite:library
+```
+
+The org picker also appends a trailing "Vite+ built-in templates" entry — selecting it routes to the `vite:monorepo` / `vite:application` / `vite:library` / `vite:generator` flow, so built-ins stay reachable interactively even when a default is configured.

docs/guide/create.md

@@ -35,7 +35,7 @@ Vite+ ships with these built-in templates:
 
 - Use shorthand templates like `vite`, `@tanstack/start`, `svelte`, `next-app`, `nuxt`, `react-router`, and `vue`
 - Use full package names like `create-vite` or `create-next-app`
-- Use local templates such as `./tools/create-ui-component` or `@acme/generator-*`
+- Use local templates such as `./tools/create-ui-component` or `@your-org/generator-*`
 - Use remote templates such as `github:user/repo` or `https://github.com/user/template-repo`
 
 Run `vp create --list` to see the built-in templates and the common shorthand templates Vite+ recognizes.
@@ -86,3 +86,150 @@ vp create create-next-app
 vp create github:user/repo
 vp create https://github.com/user/template-repo
 ```
+
+## Organization Templates
+
+An organization can publish a curated set of templates under a single npm scope by shipping an `@org/create` package whose `package.json` carries a `createConfig.templates` manifest. Once published, `vp create @org` opens an interactive picker over those templates.
+
+### Pick from an org
+
+```bash
+# Open an interactive picker over @your-org/create's manifest
+vp create @your-org
+
+# Run a specific manifest entry directly
+vp create @your-org:web
+
+# Pin to an exact version or a dist-tag
+vp create @your-org@1.2.3
+vp create @your-org:web@next
+
+# Set the org as the default for a repo (see create.defaultTemplate config)
+vp create
+```
+
+Behind the scenes, `vp create @org` maps to `@org/create` (the existing npm `create-*` convention). If that package has no `createConfig.templates` field, Vite+ falls back to running the package normally — so adopting the manifest is zero-risk for orgs that already publish `@org/create`.
+
+Private registries work automatically: Vite+ reads `.npmrc` files from the project root and `~/`, honoring `@your-org:registry=...` scope mappings and `//host/:_authToken=...` credentials.
+
+### Authoring `@org/create`
+
+There are two common layouts. Pick the one that matches the org's template count and release cadence.
+
+**Bundled (recommended for most orgs).** All templates live as subdirectories of `@org/create` itself. Manifest entries use relative `./path` values. One repo, one publish, one versioning story — the same pattern used by `create-vite` and `create-next-app`.
+
+```
+@your-org/create/
+├── package.json              # "createConfig": { "templates": [{ "template": "./templates/web" }, ...] }
+├── templates/
+│   ├── web/
+│   │   ├── package.json
+│   │   └── src/...
+│   └── library/...
+└── README.md
+```
+
+**Manifest-only.** When the org already publishes independent `@org/template-*` packages (or hosts them on GitHub), `@org/create` stays a thin index.
+
+```
+@your-org/create/
+├── package.json              # "createConfig": { "templates": [{ "template": "@your-org/template-web" }, ...] }
+└── README.md
+```
+
+The two layouts can be mixed — a manifest can point most entries at external packages and keep a few as bundled subdirectories.
+
+Optionally, provide a `bin` script so `npm create @org` (the legacy path) keeps working for non-Vite+ users. `vp create @org` reads the manifest directly and never runs the `bin`.
+
+### Manifest schema
+
+The manifest lives at `createConfig.templates` in `@org/create`'s `package.json`:
+
+```json
+{
+  "name": "@your-org/create",
+  "version": "1.0.0",
+  "createConfig": {
+    "templates": [
+      {
+        "name": "monorepo",
+        "description": "Monorepo",
+        "template": "@your-org/template-monorepo",
+        "monorepo": true
+      },
+      {
+        "name": "web",
+        "description": "Web app template (Vite + React)",
+        "template": "@your-org/template-web"
+      },
+      {
+        "name": "demo",
+        "description": "Bundled demo template",
+        "template": "./templates/demo"
+      }
+    ]
+  }
+}
+```
+
+Each entry supports:
+
+| Field         | Required | Notes                                                                                                                                                                                                                                        |
+| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | yes      | Kebab-case identifier. Used by `vp create @org:<name>` for direct selection. Must be unique within the array.                                                                                                                                |
+| `description` | yes      | One-line description shown in the picker.                                                                                                                                                                                                    |
+| `template`    | yes      | An npm specifier (`@org/template-foo`, optionally `@version`), a GitHub URL (`github:user/repo`), a `vite:*` builtin, a local workspace package name, or a relative path (`./templates/foo`) that resolves against the `@org/create` root. |
+| `monorepo`    | no       | If `true`, marks this entry as a monorepo-creating template. Hidden from the picker when `vp create` runs inside an existing monorepo, mirroring the built-in `vite:monorepo` filter.                                                        |
+
+An invalid manifest is a hard error, not a silent fall-through — a maintainer who shipped a manifest should hear about the offending field, e.g. `@your-org/create: createConfig.templates[2].template must be a non-empty string`.
+
+### Bundled subdirectory templates
+
+Relative `./...` paths resolve against the enclosing `@org/create` package root — **not** the user's cwd. The referenced directory is copied verbatim into the target project (no template-engine processing). Paths that escape the package root are rejected.
+
+### Make the org the default in a repo
+
+Commit this in `vite.config.ts` at the project root:
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  create: { defaultTemplate: '@your-org' },
+});
+```
+
+Now `vp create` (with no argument) drops straight into the `@your-org` picker. See [`create.defaultTemplate`](/config/create) for details.
+
+The picker always appends a trailing **Vite+ built-in templates** entry so `vite:monorepo` / `vite:application` / `vite:library` / `vite:generator` stay reachable from the picker — selecting it routes to the standard built-in flow. For scripts and CI, explicit specifiers (`vp create vite:library`) bypass the configured default.
+
+### Non-interactive inspection
+
+`vp create @org --no-interactive` prints the manifest as a table and exits 1:
+
+```
+A template name is required when running `vp create @your-org` in non-interactive mode.
+
+Available templates in @your-org/create:
+
+  NAME     DESCRIPTION                          TEMPLATE
+  web      Web app template (Vite + React)      @your-org/template-web
+  library  TypeScript library template          @your-org/template-library
+  demo     Bundled demo template                ./templates/demo
+
+Examples:
+  # Scaffold a specific template from the org
+  vp create @your-org:web --no-interactive
+
+  # Or use a Vite+ built-in template
+  vp create vite:application --no-interactive
+```
+
+### Publishing checklist
+
+1. Create `@org/create` (scoped npm package) if you don't already have one.
+2. Add a `createConfig.templates` array to `package.json`. (Bundle the templates under `./templates/...` or point at external packages.)
+3. (Optional) Provide a `bin` launcher for `npm create @org` compatibility.
+4. Publish.
+5. Verify: `vp create @org --no-interactive` prints the manifest table; `vp create @org` opens the picker.
+6. (Optional) Commit `create: { defaultTemplate: '@org' }` in your internal template repos.

packages/cli/README.md

@@ -150,6 +150,16 @@ vp create
 
 You can run `vp create` inside of a project to add new apps or libraries to your project.
 
+Organizations can expose a curated set of templates under their npm scope by
+publishing `@org/create` with a `createConfig.templates` manifest in its `package.json`.
+Once published, `vp create @org` opens an interactive picker over those
+templates, and setting `create: { defaultTemplate: '@org' }` in
+`vite.config.ts` makes it the default for bare `vp create`. See the
+[Organization Templates guide](https://viteplus.dev/guide/create#organization-templates)
+for the authoring workflow and
+[`create.defaultTemplate`](https://viteplus.dev/config/create) for the
+config reference.
+
 ### Migrating an existing project
 
 You can migrate an existing project to Vite+:

packages/cli/package.json

@@ -353,6 +353,7 @@
     "lint-staged": "catalog:",
     "minimatch": "catalog:",
     "mri": "catalog:",
+    "nanotar": "catalog:",
     "picocolors": "catalog:",
     "rolldown-plugin-dts": "catalog:",
     "semver": "catalog:",

packages/cli/snap-tests-global/command-create-help/snap.txt

@@ -9,6 +9,9 @@ Arguments:
             - Remote: vite, @tanstack/start, create-next-app,
               create-nuxt, github:user/repo, https://github.com/user/template-repo, etc.
             - Local: @company/generator-*, ./tools/create-ui-component
+            - Org scope: @your-org → picker from @your-org/create's createConfig.templates manifest
+            - Org entry: @your-org:web → manifest entry "web" from @your-org/create
+            When omitted, uses `create.defaultTemplate` from vite.config.ts if set.
 
 Options:
   --directory DIR         Target directory for the generated project.
@@ -49,6 +52,10 @@ Examples:
   vp create github:user/repo
   vp create https://github.com/user/template-repo
 
+  # Pick from an org that publishes @scope/create with createConfig.templates
+  vp create @your-org # interactive picker
+  vp create @your-org:web # direct manifest-entry selection
+
 Documentation: https://viteplus.dev/guide/create
 
 
@@ -63,6 +70,9 @@ Arguments:
             - Remote: vite, @tanstack/start, create-next-app,
               create-nuxt, github:user/repo, https://github.com/user/template-repo, etc.
             - Local: @company/generator-*, ./tools/create-ui-component
+            - Org scope: @your-org → picker from @your-org/create's createConfig.templates manifest
+            - Org entry: @your-org:web → manifest entry "web" from @your-org/create
+            When omitted, uses `create.defaultTemplate` from vite.config.ts if set.
 
 Options:
   --directory DIR         Target directory for the generated project.
@@ -103,6 +113,10 @@ Examples:
   vp create github:user/repo
   vp create https://github.com/user/template-repo
 
+  # Pick from an org that publishes @scope/create with createConfig.templates
+  vp create @your-org # interactive picker
+  vp create @your-org:web # direct manifest-entry selection
+
 Documentation: https://viteplus.dev/guide/create
 
 
@@ -117,6 +131,9 @@ Arguments:
             - Remote: vite, @tanstack/start, create-next-app,
               create-nuxt, github:user/repo, https://github.com/user/template-repo, etc.
             - Local: @company/generator-*, ./tools/create-ui-component
+            - Org scope: @your-org → picker from @your-org/create's createConfig.templates manifest
+            - Org entry: @your-org:web → manifest entry "web" from @your-org/create
+            When omitted, uses `create.defaultTemplate` from vite.config.ts if set.
 
 Options:
   --directory DIR         Target directory for the generated project.
@@ -157,5 +174,9 @@ Examples:
   vp create github:user/repo
   vp create https://github.com/user/template-repo
 
+  # Pick from an org that publishes @scope/create with createConfig.templates
+  vp create @your-org # interactive picker
+  vp create @your-org:web # direct manifest-entry selection
+
 Documentation: https://viteplus.dev/guide/create
 

packages/cli/snap-tests-global/new-check/snap.txt

@@ -9,6 +9,9 @@ Arguments:
             - Remote: vite, @tanstack/start, create-next-app,
               create-nuxt, github:user/repo, https://github.com/user/template-repo, etc.
             - Local: @company/generator-*, ./tools/create-ui-component
+            - Org scope: @your-org → picker from @your-org/create's createConfig.templates manifest
+            - Org entry: @your-org:web → manifest entry "web" from @your-org/create
+            When omitted, uses `create.defaultTemplate` from vite.config.ts if set.
 
 Options:
   --directory DIR         Target directory for the generated project.
@@ -49,6 +52,10 @@ Examples:
   vp create github:user/repo
   vp create https://github.com/user/template-repo
 
+  # Pick from an org that publishes @scope/create with createConfig.templates
+  vp create @your-org # interactive picker
+  vp create @your-org:web # direct manifest-entry selection
+
 Documentation: https://viteplus.dev/guide/create