diff --git a/.changeset/zod-v3-config-schema-docs.md b/.changeset/zod-v3-config-schema-docs.md new file mode 100644 index 0000000000..bcac1fa253 --- /dev/null +++ b/.changeset/zod-v3-config-schema-docs.md @@ -0,0 +1,5 @@ +--- +'@backstage/frontend-plugin-api': patch +--- + +Updated error messages and deprecation warnings to clarify that the `zod/v4` subpath export from the Zod v3 package is not supported by `configSchema`, since it does not include JSON Schema conversion. A full migration to the `zod` v4 package (`zod@^4.0.0`) is required. diff --git a/docs/frontend-system/architecture/20-extensions.md b/docs/frontend-system/architecture/20-extensions.md index 35bbd50489..a348909910 100644 --- a/docs/frontend-system/architecture/20-extensions.md +++ b/docs/frontend-system/architecture/20-extensions.md @@ -275,7 +275,7 @@ In addition to being able to access data passed through the input, you also have ## Extension configuration -With the `app-config.yaml` there is already the option to pass configuration to plugins or the app to e.g. define the `baseURL` of your app. For extensions this concept would be limiting as an extension can be independent of the plugin & initiated several times. Therefore we created a possibility to configure each extension individually through config. The extension config schema is created using any schema library that implements the [Standard Schema](https://github.com/standard-schema/standard-schema) interface with JSON Schema support, such as [`zod`](https://zod.dev/) v4 (or `import { z } from 'zod/v4'` from the zod v3 package). In addition to TypeScript type checking, the schema also provides runtime validation and coercion. If we continue with the example of the `navigationExtension` and now want it to contain a configurable title, we could make it available like the following: +With the `app-config.yaml` there is already the option to pass configuration to plugins or the app to e.g. define the `baseURL` of your app. For extensions this concept would be limiting as an extension can be independent of the plugin & initiated several times. Therefore we created a possibility to configure each extension individually through config. The extension config schema is created using any schema library that implements the [Standard Schema](https://github.com/standard-schema/standard-schema) interface with JSON Schema support, such as [`zod`](https://zod.dev/) v4 (`zod@^4.0.0`). In addition to TypeScript type checking, the schema also provides runtime validation and coercion. If we continue with the example of the `navigationExtension` and now want it to contain a configurable title, we could make it available like the following: ```tsx import { z } from 'zod'; diff --git a/docs/frontend-system/architecture/60-migrations.md b/docs/frontend-system/architecture/60-migrations.md index 634eeb271e..332b5b516b 100644 --- a/docs/frontend-system/architecture/60-migrations.md +++ b/docs/frontend-system/architecture/60-migrations.md @@ -17,7 +17,7 @@ This guide is intended for app and plugin authors who have already migrated thei The `config.schema` option for `createExtension` and `createExtensionBlueprint` is now deprecated in favor of a new top-level `configSchema` option. The new option accepts direct schema values from any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible library with JSON Schema support, rather than requiring factory functions. The `createSchemaFromZod` helper has also been removed. -The `configSchema` option requires schemas that implement the Standard Schema interface with JSON Schema support. This means you need to use [zod v4](https://zod.dev/) or the `zod/v4` subpath export from the zod v3 package (v3.25+). Direct zod v3 schemas are **not** supported by the new `configSchema` option — they are only supported through the deprecated `config.schema` callback format. +The `configSchema` option requires schemas that implement the Standard Schema interface with JSON Schema support. This means you need to use [zod v4](https://zod.dev/) (`zod@^4.0.0`). Note that the `zod/v4` subpath export from the zod v3 package does **not** work — while it exposes the Zod v4 API surface, the resulting schema objects do not support JSON Schema conversion, which `configSchema` requires. Direct zod v3 schemas are also **not** supported by the new `configSchema` option — they are only supported through the deprecated `config.schema` callback format. For example, an extension previously declared like this: @@ -36,13 +36,10 @@ createExtension({ }); ``` -Should now look like this, using zod v4 or the `zod/v4` subpath: +Should now look like this, using [zod v4](https://zod.dev/) (`zod@^4.0.0`): ```tsx -// Either import from zod v4 directly: import { z } from 'zod'; -// Or use the v4 subpath from the zod v3 package: -// import { z } from 'zod/v4'; createExtension({ // ... diff --git a/docs/releases/v1.50.0-changelog.md b/docs/releases/v1.50.0-changelog.md index e62068a40a..481abc7034 100644 --- a/docs/releases/v1.50.0-changelog.md +++ b/docs/releases/v1.50.0-changelog.md @@ -123,7 +123,7 @@ Upgrade Helper: [https://backstage.github.io/upgrade-helper/?to=1.50.0](https:// - 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 diff --git a/docs/releases/v1.50.0.md b/docs/releases/v1.50.0.md index 73b8d93813..f28a66d5d1 100644 --- a/docs/releases/v1.50.0.md +++ b/docs/releases/v1.50.0.md @@ -20,17 +20,13 @@ To get ownership info for the current user, code should use the `userInfo` core The new frontend system now uses [Standard Schema](https://github.com/standard-schema/standard-schema) for extension configuration. A new `configSchema` option has been added to `createExtension`, `createExtensionBlueprint`, as well as the `override` and `makeWithOverrides` methods on extension definitions and blueprints. This option accepts direct schema values from any Standard Schema compatible library with JSON Schema support, replacing the old `config.schema` callback format which is now deprecated. -To use the new `configSchema` option with Zod, you need Zod v4 or the `zod/v4` subpath export from the Zod v3 package. The `zod/v4` subpath requires a minimum Zod version of **3.25.0** — make sure to update your Zod dependency if needed: +To use the new `configSchema` option with Zod, you need Zod v4 (`zod@^4.0.0`): ```ts -// Either use Zod v4 directly (requires zod@^4.0.0): import { z } from 'zod'; - -// Or the v4 subpath from the Zod v3 package (requires zod@^3.25.0): -import { z } from 'zod/v4'; ``` -Note that direct Zod v3 schemas are **not** supported by the new `configSchema` option — they only work with the deprecated `config.schema` callback format. +Note that neither direct Zod v3 schemas nor the `zod/v4` subpath export from the Zod v3 package are supported by the new `configSchema` option. While the `zod/v4` subpath exposes the Zod v4 API surface, the resulting schema objects do not support the JSON Schema conversion that `configSchema` requires. A full migration to the `zod` v4 package is needed. Direct Zod v3 schemas only work with the deprecated `config.schema` callback format. The deprecated `createSchemaFromZod` helper has been removed from `@backstage/frontend-plugin-api`. diff --git a/packages/frontend-plugin-api/CHANGELOG.md b/packages/frontend-plugin-api/CHANGELOG.md index 714b32085a..27f044e266 100644 --- a/packages/frontend-plugin-api/CHANGELOG.md +++ b/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 diff --git a/packages/frontend-plugin-api/src/schema/createPortableSchema.test.ts b/packages/frontend-plugin-api/src/schema/createPortableSchema.test.ts index c42298585b..adceca4c5a 100644 --- a/packages/frontend-plugin-api/src/schema/createPortableSchema.test.ts +++ b/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.', ); }); }); diff --git a/packages/frontend-plugin-api/src/schema/createPortableSchema.ts b/packages/frontend-plugin-api/src/schema/createPortableSchema.ts index a6bb3340d7..f01cbff5ed 100644 --- a/packages/frontend-plugin-api/src/schema/createPortableSchema.ts +++ b/packages/frontend-plugin-api/src/schema/createPortableSchema.ts @@ -179,9 +179,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)) { @@ -357,8 +358,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}`, ); }