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

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

Browse Source 
frontend-plugin-api: clarify that zod v3 does not support configSchema
This commit is contained in:
Patrik Oldsberg
2026-04-17 10:34:20 +02:00
committed by GitHub
parent d33ab2aa24 085133fde0
commit d9264ed271
20 changed files with 54 additions and 42 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. The `zod` dependency has been bumped to `^4.0.0`.
.changeset/zod-v4-dep-bump.md
+12
View File
@@ -0,0 +1,12 @@
---
'@backstage/plugin-app': patch
'@backstage/plugin-catalog': patch
'@backstage/plugin-catalog-react': patch
'@backstage/plugin-catalog-graph': patch
'@backstage/plugin-techdocs': patch
'@backstage/plugin-search': patch
'@backstage/plugin-search-react': patch
'@backstage/plugin-org': patch
---
The `zod` dependency has been bumped from `^3.25.76 || ^4.0.0` to `^4.0.0`, since `configSchema` requires the full Zod v4 package for JSON Schema support.
.patches/pr-33952.txt
+1
View File
@@ -0,0 +1 @@
Bump zod dependency to v4 for packages using configSchema and clarify that zod/v4 subpath from v3 is not supported
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/package.json
+1 -1
View File
@@ -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
+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
@@ -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}`,
);
}
plugins/app/package.json
+1 -1
View File
@@ -72,7 +72,7 @@
"react-stately": "^3.46.0",
"react-use": "^17.2.4",
"zen-observable": "^0.10.0",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/catalog-graph/package.json
+1 -1
View File
@@ -65,7 +65,7 @@
"lodash": "^4.17.15",
"qs": "^6.9.4",
"react-use": "^17.2.4",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/catalog-react/package.json
+1 -1
View File
@@ -87,7 +87,7 @@
"react-use": "^17.2.4",
"yaml": "^2.0.0",
"zen-observable": "^0.10.0",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/catalog/package.json
+1 -1
View File
@@ -88,7 +88,7 @@
"react-helmet": "6.1.0",
"react-use": "^17.2.4",
"zen-observable": "^0.10.0",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/org/package.json
+1 -1
View File
@@ -67,7 +67,7 @@
"pluralize": "^8.0.0",
"qs": "^6.10.1",
"react-use": "^17.2.4",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/catalog-client": "workspace:^",
plugins/search-react/package.json
+1 -1
View File
@@ -70,7 +70,7 @@
"qs": "^6.9.4",
"react-use": "^17.3.2",
"uuid": "^11.0.2",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/search/package.json
+1 -1
View File
@@ -72,7 +72,7 @@
"@material-ui/icons": "^4.9.1",
"qs": "^6.9.4",
"react-use": "^17.2.4",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/techdocs/package.json
+1 -1
View File
@@ -87,7 +87,7 @@
"lodash": "^4.17.21",
"react-helmet": "6.1.0",
"react-use": "^17.2.4",
"zod": "^3.25.76 || ^4.0.0"
"zod": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
yarn.lock
+10 -10
View File
@@ -3826,7 +3826,7 @@ __metadata:
react: "npm:^18.0.2"
react-dom: "npm:^18.0.2"
react-router-dom: "npm:^6.30.2"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
zod-to-json-schema: "npm:^3.25.1"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
@@ -4191,7 +4191,7 @@ __metadata:
react-stately: "npm:^3.46.0"
react-use: "npm:^17.2.4"
zen-observable: "npm:^0.10.0"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -5266,7 +5266,7 @@ __metadata:
react-dom: "npm:^18.0.2"
react-router-dom: "npm:^6.30.2"
react-use: "npm:^17.2.4"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -5402,7 +5402,7 @@ __metadata:
react-use: "npm:^17.2.4"
yaml: "npm:^2.0.0"
zen-observable: "npm:^0.10.0"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@backstage/frontend-test-utils": "workspace:^"
"@types/react": ^17.0.0 || ^18.0.0
@@ -5513,7 +5513,7 @@ __metadata:
react-use: "npm:^17.2.4"
swr: "npm:^2.2.5"
zen-observable: "npm:^0.10.0"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -6419,7 +6419,7 @@ __metadata:
react-dom: "npm:^18.0.2"
react-router-dom: "npm:^6.30.2"
react-use: "npm:^17.2.4"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -7327,7 +7327,7 @@ __metadata:
react-router-dom: "npm:^6.30.2"
react-use: "npm:^17.3.2"
uuid: "npm:^11.0.2"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -7370,7 +7370,7 @@ __metadata:
react-dom: "npm:^18.0.2"
react-router-dom: "npm:^6.30.2"
react-use: "npm:^17.2.4"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -7716,7 +7716,7 @@ __metadata:
react-helmet: "npm:6.1.0"
react-router-dom: "npm:^6.30.2"
react-use: "npm:^17.2.4"
zod: "npm:^3.25.76 || ^4.0.0"
zod: "npm:^4.0.0"
peerDependencies:
"@types/react": ^17.0.0 || ^18.0.0
react: ^17.0.0 || ^18.0.0
@@ -49155,7 +49155,7 @@ __metadata:
languageName: node
linkType: hard
"zod@npm:^3.25 || ^4.0, zod@npm:^3.25.76 || ^4.0.0, zod@npm:^4.1.11":
"zod@npm:^3.25 || ^4.0, zod@npm:^3.25.76 || ^4.0.0, zod@npm:^4.0.0, zod@npm:^4.1.11":
version: 4.3.6
resolution: "zod@npm:4.3.6"
checksum: 10/25fc0f62e01b557b4644bf0b393bbaf47542ab30877c37837ea8caf314a8713d220c7d7fe51f68ffa72f0e1018ddfa34d96f1973d23033f5a2a5a9b6b9d9da01