Merge pull request #33952 from backstage/rugvip/zod-v3-config-schema-docs

frontend-plugin-api: clarify that zod v3 does not support configSchema

packages/frontend-plugin-api/CHANGELOG.md

@@ -12,7 +12,7 @@
 - 4c09967: Fixed the duplicate extension error message in `createFrontendModule` to correctly say "Module" instead of "Plugin".
 - e4804ab: Added `open` method to `DialogApi` that renders dialogs without any built-in dialog chrome, giving the caller full control over the dialog presentation. This avoids focus trap conflicts that occur when mixing components from different design libraries. The existing `show` and `showModal` methods are now deprecated in favor of `open`.
 - ddc5247: Fixed `FlattenedMessages` type to avoid excessive type instantiation depth in TypeScript 6 when using `createTranslationRef` with the `translations` option.
-- a2a6c3b: Added a new `configSchema` option for `createExtension` and `createExtensionBlueprint` that accepts direct schema values from any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible library with JSON Schema support, such as zod v4 or the `zod/v4` subpath from zod v3. The old `config.schema` option is now deprecated. Note that direct zod v3 schemas are not supported by the new `configSchema` option — use `import { z } from 'zod/v4'` from the zod v3 package, or upgrade to zod v4. See the [1.50 migration documentation](https://backstage.io/docs/frontend-system/architecture/migrations#150) for more information.
+- a2a6c3b: Added a new `configSchema` option for `createExtension` and `createExtensionBlueprint` that accepts direct schema values from any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible library with JSON Schema support, such as zod v4 (`zod@^4.0.0`). The old `config.schema` option is now deprecated. Note that Zod v3 is not supported by the new `configSchema` option, including the `zod/v4` subpath export which does not include JSON Schema conversion support. You must upgrade to the `zod` v4 package. See the [1.50 migration documentation](https://backstage.io/docs/frontend-system/architecture/migrations#150) for more information.
 - d66a3ec: Added `titleLink` prop to `PageLayoutProps` so the plugin header title can link back to the plugin root.
 - e220589: Removed the unnecessary need to use `defineParams` callback from `PluginHeaderActionBlueprint`. It still works, but is no longer required.
 - Updated dependencies

packages/frontend-plugin-api/package.json

@@ -49,7 +49,7 @@
     "@backstage/types": "workspace:^",
     "@backstage/version-bridge": "workspace:^",
     "@standard-schema/spec": "^1.1.0",
-    "zod": "^3.25.76 || ^4.0.0",
+    "zod": "^4.0.0",
     "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {

packages/frontend-plugin-api/src/schema/createPortableSchema.test.ts

@@ -92,9 +92,10 @@ describe('createConfigSchema', () => {
     it('should reject a direct zod v3 schema', () => {
       expect(() => createConfigSchema({ name: zodV3.string() as any })).toThrow(
         "Config schema for field 'name' uses a Zod v3 schema, which is " +
-          'not supported by the `configSchema` option. Either use ' +
-          "`import { z } from 'zod/v4'` from the zod v3 package, or " +
-          'upgrade to zod v4.',
+          'not supported by the `configSchema` option. Upgrade to the ' +
+          '`zod` v4 package (`zod@^4.0.0`). Note that the `zod/v4` ' +
+          'subpath export from the zod v3 package is also not supported, ' +
+          'as it does not include JSON Schema conversion.',
       );
     });
   });

packages/frontend-plugin-api/src/schema/createPortableSchema.ts

@@ -172,9 +172,10 @@ function resolveField(key: string, schema: unknown): ResolvedField {
   if (isZodV3Type(schema)) {
     throw new Error(
       `Config schema for field '${key}' uses a Zod v3 schema, which is ` +
-        `not supported by the \`configSchema\` option. Either use ` +
-        `\`import { z } from 'zod/v4'\` from the zod v3 package, or ` +
-        `upgrade to zod v4.`,
+        `not supported by the \`configSchema\` option. Upgrade to the ` +
+        `\`zod\` v4 package (\`zod@^4.0.0\`). Note that the \`zod/v4\` ` +
+        `subpath export from the zod v3 package is also not supported, ` +
+        `as it does not include JSON Schema conversion.`,
     );
   }
   if (isStandardSchema(schema)) {
@@ -350,8 +351,7 @@ export function warnConfigSchemaPropDeprecation(callSite: string) {
   console.warn(
     `DEPRECATION WARNING: The \`config.schema\` option for extension config is deprecated. ` +
       `Use the \`configSchema\` option instead with Standard Schema values, for example ` +
-      `\`configSchema: { title: z.string() }\` using zod v4 ` +
-      `(or \`import { z } from 'zod/v4'\` from the zod v3 package). ` +
-      `Declared at ${callSite}`,
+      `\`configSchema: { title: z.string() }\` using the \`zod\` v4 package ` +
+      `(\`zod@^4.0.0\`). Declared at ${callSite}`,
   );
 }