feat(create)!: rename manifest field to createConfig.templates

fengmk2 · fengmk2 · commit f4506d4eba16 · 2026-04-25T11:08:08.000+08:00
BREAKING (unpublished feature): the org-create manifest now lives at `createConfig.templates` in `@org/create`'s package.json, replacing the Vite+-specific `vp.templates` location. Rationale (fengmk2 + cpojer, PR #1398 review): the manifest metadata is tool-neutral (names, descriptions, template specifiers) and belongs under a neutral field name. Following the precedent of npm's `publishConfig`, `createConfig` reads as "configuration used specifically when this package is consumed as a create initializer", leaving room for other scaffolding tools to adopt the same convention later. Vite+-specific behavior, if/when it's needed, can sit at `createConfig.vp.*` without further schema changes. Schema shape unchanged (name / description / template / keywords / monorepo). Validation error messages now reference `createConfig.templates[...]` instead of `vp.templates[...]`. Updated: org-manifest reader and schema validator, RegistryVersionMeta type, org-resolve info note, bin.ts help text, define-config JSDoc, RFC manifest schema + field reference + resolution flow sections, docs guide + config pages, root README, all 7 snap-test mock manifests (and the bundled-fixture tarball + integrity hash), and the unit-test regex that asserts the error path name.
diff --git a/README.md b/README.md
@@ -153,7 +153,7 @@ 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 `vp.templates` manifest in its `package.json`.
+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
diff --git a/docs/config/create.md b/docs/config/create.md
@@ -4,7 +4,7 @@
 
 ## `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 `vp.templates` manifest — so bare `vp create` drops into the org picker.
+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';
diff --git a/docs/guide/create.md b/docs/guide/create.md
@@ -89,7 +89,7 @@ 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 `vp.templates` manifest. Once published, `vp create @org` opens an interactive picker over those 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
 
@@ -104,7 +104,7 @@ vp create @your-org/web
 vp create
 ```
 
-Behind the scenes, `vp create @org` maps to `@org/create` (the existing npm `create-*` convention). If that package has no `vp.templates` field, Vite+ falls back to running the package normally — so adopting the manifest is zero-risk for orgs that already publish `@org/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`.
 
 ### Authoring `@org/create`
 
@@ -114,7 +114,7 @@ There are two common layouts. Pick the one that matches the org's template count
 
 ```
 @your-org/create/
-├── package.json              # "vp": { "templates": [{ "template": "./templates/web" }, ...] }
+├── package.json              # "createConfig": { "templates": [{ "template": "./templates/web" }, ...] }
 ├── templates/
 │   ├── web/
 │   │   ├── package.json
@@ -127,7 +127,7 @@ There are two common layouts. Pick the one that matches the org's template count
 
 ```
 @your-org/create/
-├── package.json              # "vp": { "templates": [{ "template": "@your-org/template-web" }, ...] }
+├── package.json              # "createConfig": { "templates": [{ "template": "@your-org/template-web" }, ...] }
 └── README.md
 ```
 
@@ -137,13 +137,13 @@ Optionally, provide a `bin` script so `npm create @org` (the legacy path) keeps
 
 ### Manifest schema
 
-The manifest lives at `vp.templates` in `@org/create`'s `package.json`:
+The manifest lives at `createConfig.templates` in `@org/create`'s `package.json`:
 
 ```json
 {
   "name": "@your-org/create",
   "version": "1.0.0",
-  "vp": {
+  "createConfig": {
     "templates": [
       {
         "name": "monorepo",
@@ -177,7 +177,7 @@ Each entry supports:
 | `keywords`    | no       | Filter terms for picker search.                                                                                                                                                                                                              |
 | `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: vp.templates[2].template must be a non-empty string`.
+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
 
@@ -224,7 +224,7 @@ Examples:
 ### Publishing checklist
 
 1. Create `@org/create` (scoped npm package) if you don't already have one.
-2. Add a `vp.templates` array to `package.json`. (Bundle the templates under `./templates/...` or point at external packages.)
+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.
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -151,7 +151,7 @@ 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 `vp.templates` manifest in its `package.json`.
+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
diff --git a/packages/cli/snap-tests/create-org-bundled-escape-check/mock-manifest.json b/packages/cli/snap-tests/create-org-bundled-escape-check/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "escape",
diff --git a/packages/cli/snap-tests/create-org-bundled-escape-check/snap.txt b/packages/cli/snap-tests/create-org-bundled-escape-check/snap.txt
@@ -1,3 +1,3 @@
 [1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org --no-interactive # `../outside` path rejected at schema-validation, before any tarball fetch
 
-@your-org/create: vp.templates[0].template escapes the package root: ../outside
+@your-org/create: createConfig.templates[0].template escapes the package root: ../outside
diff --git a/packages/cli/snap-tests/create-org-bundled/mock-manifest.json b/packages/cli/snap-tests/create-org-bundled/mock-manifest.json
@@ -7,9 +7,9 @@
         "version": "1.0.0",
         "dist": {
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
-          "integrity": "sha512-h4Q9x+aUa2RUJGBe7JCZnWpGMyd8VHXPfL9+EBxrA2EWRV8rlmMCP45B3woZ8xA2fmkE/jUy1W7OM2GCjoPWQA=="
+          "integrity": "sha512-swwZCXG8RDBJNTmiw3zCOBCQx9bCg7wHqoW37aV7BgGYfBUU7n7c+efbSCg0+FpdLhgeUjEMP5IAO+8exmeFKg=="
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "demo",
diff --git a/packages/cli/snap-tests/create-org-bundled/tarballs/create-1.0.0.tgz b/packages/cli/snap-tests/create-org-bundled/tarballs/create-1.0.0.tgz
diff --git a/packages/cli/snap-tests/create-org-config-default/mock-manifest.json b/packages/cli/snap-tests/create-org-config-default/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "web",
diff --git a/packages/cli/snap-tests/create-org-invalid-manifest/mock-manifest.json b/packages/cli/snap-tests/create-org-invalid-manifest/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "broken-entry",
diff --git a/packages/cli/snap-tests/create-org-invalid-manifest/snap.txt b/packages/cli/snap-tests/create-org-invalid-manifest/snap.txt
@@ -1,3 +1,3 @@
 [1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org --no-interactive # invalid manifest -> schema error
 
-@your-org/create: vp.templates[0].template must be a non-empty string
+@your-org/create: createConfig.templates[0].template must be a non-empty string
diff --git a/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/mock-manifest.json b/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "monorepo",
diff --git a/packages/cli/snap-tests/create-org-monorepo-filter/mock-manifest.json b/packages/cli/snap-tests/create-org-monorepo-filter/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "monorepo",
diff --git a/packages/cli/snap-tests/create-org-no-interactive-error/mock-manifest.json b/packages/cli/snap-tests/create-org-no-interactive-error/mock-manifest.json
@@ -9,7 +9,7 @@
           "tarball": "http://placeholder/@your-org/create/-/create-1.0.0.tgz",
           "integrity": "sha512-fake"
         },
-        "vp": {
+        "createConfig": {
           "templates": [
             {
               "name": "web",
diff --git a/packages/cli/src/create/__tests__/org-manifest.spec.ts b/packages/cli/src/create/__tests__/org-manifest.spec.ts
@@ -65,7 +65,7 @@ function packument(vpTemplates: unknown, extra: Record<string, unknown> = {}) {
           tarball: 'https://registry.npmjs.org/@your-org/create/-/create-1.0.0.tgz',
           integrity: 'sha512-fake',
         },
-        vp: vpTemplates !== undefined ? { templates: vpTemplates } : undefined,
+        createConfig: vpTemplates !== undefined ? { templates: vpTemplates } : undefined,
         ...extra,
       },
     },
@@ -92,12 +92,12 @@ describe('readOrgManifest', () => {
     expect(await readOrgManifest('@your-org')).toBeNull();
   });
 
-  it('returns null when the package has no vp.templates field', async () => {
+  it('returns null when the package has no createConfig.templates field', async () => {
     mockFetchJson(packument(undefined));
     expect(await readOrgManifest('@your-org')).toBeNull();
   });
 
-  it('returns null when vp.templates is an empty array', async () => {
+  it('returns null when createConfig.templates is an empty array', async () => {
     mockFetchJson(packument([]));
     expect(await readOrgManifest('@your-org')).toBeNull();
   });
@@ -119,14 +119,16 @@ describe('readOrgManifest', () => {
     expect(manifest?.templates[1].monorepo).toBe(true);
   });
 
-  it('throws on non-array vp.templates', async () => {
+  it('throws on non-array createConfig.templates', async () => {
     mockFetchJson(packument('nope'));
     await expect(readOrgManifest('@your-org')).rejects.toBeInstanceOf(OrgManifestSchemaError);
   });
 
   it('throws on an entry missing required fields', async () => {
     mockFetchJson(packument([{ name: 'web', description: 'no template yet' }]));
-    await expect(readOrgManifest('@your-org')).rejects.toThrow(/vp\.templates\[0]\.template/);
+    await expect(readOrgManifest('@your-org')).rejects.toThrow(
+      /createConfig\.templates\[0]\.template/,
+    );
   });
 
   it('throws on duplicate entry names', async () => {
@@ -166,7 +168,7 @@ describe('readOrgManifest', () => {
         '1.0.0': {
           version: '1.0.0',
           dist: {},
-          vp: { templates: [{ name: 'a', description: 'a', template: '@a/a' }] },
+          createConfig: { templates: [{ name: 'a', description: 'a', template: '@a/a' }] },
         },
       },
     });
diff --git a/packages/cli/src/create/bin.ts b/packages/cli/src/create/bin.ts
@@ -81,7 +81,7 @@ const helpMessage = renderCliDoc({
             '- 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: ${accent('@your-org')} → picker from ${accent('@your-org/create')}'s ${accent('vp.templates')} manifest`,
+            `- Org scope: ${accent('@your-org')} → picker from ${accent('@your-org/create')}'s ${accent('createConfig.templates')} manifest`,
             `- Org entry: ${accent('@your-org/web')} → manifest entry "web" (falls back to ${accent('@your-org/create-web')})`,
             `When omitted, uses \`create.defaultTemplate\` from vite.config.ts if set.`,
           ],
@@ -145,7 +145,7 @@ const helpMessage = renderCliDoc({
         `  ${accent('vp create github:user/repo')}`,
         `  ${accent('vp create https://github.com/user/template-repo')}`,
         '',
-        `  ${muted('# Pick from an org that publishes @scope/create with vp.templates')}`,
+        `  ${muted('# Pick from an org that publishes @scope/create with createConfig.templates')}`,
         `  ${accent('vp create @your-org')} ${muted('# interactive picker')}`,
         `  ${accent('vp create @your-org/web')} ${muted('# direct selection')}`,
       ],
diff --git a/packages/cli/src/create/org-manifest.ts b/packages/cli/src/create/org-manifest.ts
@@ -73,14 +73,17 @@ export function isRelativePath(spec: string): boolean {
 
 function validateEntry(entry: unknown, index: number, packageName: string): OrgTemplateEntry {
   if (!entry || typeof entry !== 'object') {
-    throw new OrgManifestSchemaError(`vp.templates[${index}] must be an object`, packageName);
+    throw new OrgManifestSchemaError(
+      `createConfig.templates[${index}] must be an object`,
+      packageName,
+    );
   }
   const raw = entry as Record<string, unknown>;
   const requireString = (field: string): string => {
     const value = raw[field];
     if (typeof value !== 'string' || value.length === 0) {
       throw new OrgManifestSchemaError(
-        `vp.templates[${index}].${field} must be a non-empty string`,
+        `createConfig.templates[${index}].${field} must be a non-empty string`,
         packageName,
       );
     }
@@ -94,7 +97,7 @@ function validateEntry(entry: unknown, index: number, packageName: string): OrgT
   if (raw.keywords !== undefined) {
     if (!Array.isArray(raw.keywords) || raw.keywords.some((k) => typeof k !== 'string')) {
       throw new OrgManifestSchemaError(
-        `vp.templates[${index}].keywords must be an array of strings`,
+        `createConfig.templates[${index}].keywords must be an array of strings`,
         packageName,
       );
     }
@@ -105,7 +108,7 @@ function validateEntry(entry: unknown, index: number, packageName: string): OrgT
   if (raw.monorepo !== undefined) {
     if (typeof raw.monorepo !== 'boolean') {
       throw new OrgManifestSchemaError(
-        `vp.templates[${index}].monorepo must be a boolean`,
+        `createConfig.templates[${index}].monorepo must be a boolean`,
         packageName,
       );
     }
@@ -119,7 +122,7 @@ function validateEntry(entry: unknown, index: number, packageName: string): OrgT
     const resolved = path.posix.resolve('/root', template.replaceAll('\\', '/'));
     if (resolved !== '/root' && !resolved.startsWith('/root/')) {
       throw new OrgManifestSchemaError(
-        `vp.templates[${index}].template escapes the package root: ${template}`,
+        `createConfig.templates[${index}].template escapes the package root: ${template}`,
         packageName,
       );
     }
@@ -138,16 +141,16 @@ function validateManifest(raw: unknown, packageName: string): OrgTemplateEntry[]
   if (!raw || typeof raw !== 'object') {
     return null;
   }
-  const vp = (raw as { vp?: unknown }).vp;
-  if (!vp || typeof vp !== 'object') {
+  const createConfig = (raw as { createConfig?: unknown }).createConfig;
+  if (!createConfig || typeof createConfig !== 'object') {
     return null;
   }
-  const templates = (vp as { templates?: unknown }).templates;
+  const templates = (createConfig as { templates?: unknown }).templates;
   if (templates === undefined) {
     return null;
   }
   if (!Array.isArray(templates)) {
-    throw new OrgManifestSchemaError('vp.templates must be an array', packageName);
+    throw new OrgManifestSchemaError('createConfig.templates must be an array', packageName);
   }
   if (templates.length === 0) {
     // Treat empty array as "no manifest" — fall through to normal @org/create behavior.
@@ -159,7 +162,7 @@ function validateManifest(raw: unknown, packageName: string): OrgTemplateEntry[]
     const entry = validateEntry(templates[index], index, packageName);
     if (seen.has(entry.name)) {
       throw new OrgManifestSchemaError(
-        `vp.templates[${index}].name duplicates an earlier entry: "${entry.name}"`,
+        `createConfig.templates[${index}].name duplicates an earlier entry: "${entry.name}"`,
         packageName,
       );
     }
@@ -177,7 +180,7 @@ interface RegistryPackument {
 
 interface RegistryVersionMeta {
   version?: string;
-  vp?: unknown;
+  createConfig?: unknown;
   dist?: {
     tarball?: string;
     integrity?: string;
@@ -203,15 +206,15 @@ async function fetchPackument(packageName: string): Promise<RegistryPackument |
 }
 
 /**
- * Fetch `@scope/create` from the npm registry and parse its `vp.templates`
+ * Fetch `@scope/create` from the npm registry and parse its `createConfig.templates`
  * manifest.
  *
  * Returns `null` when:
  * - the package does not exist on the registry (404), or
- * - the package exists but has no `vp.templates` field
+ * - the package exists but has no `createConfig.templates` field
  *
  * Throws when:
- * - the `vp.templates` field is present but malformed (`OrgManifestSchemaError`), or
+ * - the `createConfig.templates` field is present but malformed (`OrgManifestSchemaError`), or
  * - the registry request fails for any non-404 reason
  */
 export async function readOrgManifest(scope: string): Promise<OrgManifest | null> {
diff --git a/packages/cli/src/create/org-resolve.ts b/packages/cli/src/create/org-resolve.ts
@@ -100,7 +100,7 @@ async function resolveEntry(
 
 /**
  * If `selectedTemplateName` points at an `@scope[/name]` org whose
- * `@scope/create` package publishes a `vp.templates` manifest, apply the
+ * `@scope/create` package publishes a `createConfig.templates` manifest, apply the
  * manifest rules (picker / direct lookup / escape hatch / bundled
  * extraction) and report the outcome.
  *
@@ -137,7 +137,7 @@ export async function resolveOrgManifestForCreate(args: {
     // Per-entry `vp create @org/name` stays silent since it's ambiguous.
     if (orgSpec.name === undefined) {
       prompts.log.info(
-        `No \`vp.templates\` manifest in ${orgSpec.scope}/create — running it as a normal package.`,
+        `No \`createConfig.templates\` manifest in ${orgSpec.scope}/create — running it as a normal package.`,
       );
     }
     return { kind: 'passthrough' };
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
@@ -35,7 +35,7 @@ declare module '@voidzero-dev/vite-plus-core' {
        * When `vp create` is invoked with no template argument, use this
        * value as if the user had typed it — typically a scope like
        * `'@your-org'` paired with a `@your-org/create` package that exposes a
-       * `vp.templates` manifest.
+       * `createConfig.templates` manifest.
        */
       defaultTemplate?: string;
     };
diff --git a/rfcs/create-org-default-templates.md b/rfcs/create-org-default-templates.md

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`"tarball": "{REGISTRY}/@your-org/create/-/create-1.0.0.tgz",`
`10`	`10`	`"integrity": "sha512-fake"`
`11`	`11`	`},`
`12`		`- "vp": {`
	`12`	`+ "createConfig": {`
`13`	`13`	`"templates": [`
`14`	`14`	`{`
`15`	`15`	`"name": "escape",`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	[1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org --no-interactive # `../outside` path rejected at schema-validation, before any tarball fetch
`2`	`2`
`3`		`-@your-org/create: vp.templates[0].template escapes the package root: ../outside`
	`3`	`+@your-org/create: createConfig.templates[0].template escapes the package root: ../outside`