paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Update error messages, deprecation warnings, migration docs, release
notes, and changelogs to reflect that the zod/v4 subpath export from
the Zod v3 package does not support JSON Schema conversion via the
Standard Schema interface. Users must fully migrate to the zod v4
package (zod@^4.0.0) to use configSchema.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
2026-04-16 17:23:54 +02:00
parent ebfa023123
commit 72a552f0db
8 changed files with 22 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/zod-v3-config-schema-docs.md
+5
View File
@@ -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.
docs/frontend-system/architecture/20-extensions.md
+1 -1
View File
@@ -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';
docs/frontend-system/architecture/60-migrations.md
+2 -5
View File
@@ -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({
// ...
docs/releases/v1.50.0-changelog.md
+1 -1
View File
@@ -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
docs/releases/v1.50.0.md
+2 -6
View File
@@ -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`.
packages/frontend-plugin-api/CHANGELOG.md
+1 -1
View File
@@ -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/src/schema/createPortableSchema.test.ts
+4 -3
View File
@@ -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
+6 -6
View File
@@ -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}`,
);
}