From a2a6c3b72e30dff7f5ca024f7d01644fcbb9102f Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 10 Apr 2026 11:51:22 +0200
Subject: [PATCH] Add migration docs and changeset for new configSchema option

Add 1.50 migration section documenting the config.schema to configSchema
migration with examples for createExtension, createExtensionBlueprint,
and makeWithOverrides. Add a separate changeset for the new feature and
update the existing breaking changeset to reference the migration docs.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 .../fix-zod-generic-frontend-plugin-api.md    |  2 +-
 ...frontend-plugin-api-configschema-option.md |  5 ++
 .../architecture/60-migrations.md             | 77 +++++++++++++++++++
 3 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/frontend-plugin-api-configschema-option.md

diff --git a/.changeset/fix-zod-generic-frontend-plugin-api.md b/.changeset/fix-zod-generic-frontend-plugin-api.md
index e07a32322a..00f74f5e18 100644
--- a/.changeset/fix-zod-generic-frontend-plugin-api.md
+++ b/.changeset/fix-zod-generic-frontend-plugin-api.md
@@ -2,4 +2,4 @@
 '@backstage/frontend-plugin-api': minor
 ---
 
-**BREAKING**: Removed the deprecated `createSchemaFromZod` helper. Use the `configSchema` option with Standard Schema values instead, for example `configSchema: { title: z.string() }` using zod v3.25+ or v4.
+**BREAKING**: Removed the deprecated `createSchemaFromZod` helper. Use the new `configSchema` option instead. See the [1.50 migration documentation](https://backstage.io/docs/frontend-system/architecture/migrations#150) for more information.
diff --git a/.changeset/frontend-plugin-api-configschema-option.md b/.changeset/frontend-plugin-api-configschema-option.md
new file mode 100644
index 0000000000..03587b7b2b
--- /dev/null
+++ b/.changeset/frontend-plugin-api-configschema-option.md
@@ -0,0 +1,5 @@
+---
+'@backstage/frontend-plugin-api': patch
+---
+
+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. The old `config.schema` option is now deprecated. See the [1.50 migration documentation](https://backstage.io/docs/frontend-system/architecture/migrations#150) for more information.
diff --git a/docs/frontend-system/architecture/60-migrations.md b/docs/frontend-system/architecture/60-migrations.md
index aecc44b039..3ea7f9351e 100644
--- a/docs/frontend-system/architecture/60-migrations.md
+++ b/docs/frontend-system/architecture/60-migrations.md
@@ -11,6 +11,83 @@ This section provides migration guides for different versions of the frontend sy
 
 This guide is intended for app and plugin authors who have already migrated their code to the new frontend system, and are looking to keep it up to date with the latest changes. These guides do not cover trivial migrations that can be explained in a deprecation message, such as a renamed export.
 
+## 1.50
+
+### New `configSchema` option for extension config
+
+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, rather than requiring factory functions. The `createSchemaFromZod` helper has also been removed.
+
+The recommended migration target is [zod v4](https://zod.dev/), but any Standard Schema compatible library or version works, including zod v3.25+.
+
+For example, an extension previously declared like this:
+
+```tsx
+createExtension({
+  // ...
+  config: {
+    schema: {
+      title: z => z.string().default('Hello'),
+      count: z => z.number().optional(),
+    },
+  },
+  factory({ config }) {
+    // ...
+  },
+});
+```
+
+Should now look like this:
+
+```tsx
+import { z } from 'zod';
+
+createExtension({
+  // ...
+  configSchema: {
+    title: z.string().default('Hello'),
+    count: z.number().optional(),
+  },
+  factory({ config }) {
+    // ...
+  },
+});
+```
+
+The same applies to `createExtensionBlueprint`:
+
+```tsx
+import { z } from 'zod';
+
+const MyBlueprint = createExtensionBlueprint({
+  // ...
+  configSchema: {
+    title: z.string().default('Hello'),
+  },
+  factory(params, { config }) {
+    // ...
+  },
+});
+```
+
+And when adding config through `makeWithOverrides`:
+
+```tsx
+import { z } from 'zod';
+
+MyBlueprint.makeWithOverrides({
+  configSchema: {
+    extra: z.string(),
+  },
+  factory(originalFactory, { config }) {
+    return originalFactory({
+      // ...
+    });
+  },
+});
+```
+
+Each field in the `configSchema` record is a standalone schema value rather than a factory function. This decouples the config schema declaration from any specific zod version, and lets you use any schema library that implements the Standard Schema interface.
+
 ## 1.31
 
 ### `namespace` parameter should be removed