破壊的変更46(ダウングレード不可1)
認証バックエンドから実験的 DCR を削除
ダウングレード不可影響対象実験的 DCR を使用する認証バックエンド構成。auth.experimentalDynamicClientRegistration が設定されている構成、またはデータベースに DCR クライアントとセッションがある構成を含む
必要な対応CIMD または auth.staticClients で事前登録したクライアントを使用し、auth.experimentalDynamicClientRegistration を削除した構成
ダウングレード不可(推定: DCR クライアントとセッションの削除、および復元に必要な削除済み状態の回復)
移行により DCR クライアントと、それらの認可セッションおよびオフラインセッションが削除され、対応する認可コードとリフレッシュトークンが無効になります。ユーザーは再度サインインする必要がありますが、発行済みのユーザートークンは有効期限が切れるまで有効です。
原文を表示
The deprecated experimental Dynamic Client Registration (DCR) support has been removed from the auth backend. Use Client ID Metadata Documents (CIMD), or pre-register clients through `auth.staticClients`, and remove `auth.experimentalDynamicClientRegistration` from your configuration. The database migration deletes DCR clients and their authorization and offline sessions, invalidating their authorization codes and refresh tokens. Users must sign in again through a CIMD or pre-registered client; already-issued user tokens remain valid until they expire. See the [DCR migration guide](../ai/mcp-actions.md#migrating-from-dynamic-client-registration).
github.com/backstage/backstage/releases/tag/v1.57.0useRouteRefParams が返すルートパラメーターの限定
影響対象useRouteRefParams を使用するコード
以前は、このフックがルート参照で宣言されていないスプラットパラメーターを返すことがありました。この動作に依存していたコードが受け取るのは、ルート参照で宣言されたパラメーターのみになります。
原文を表示
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.github.com/backstage/backstage/releases/tag/v1.57.0Extension のアタッチ先型の置き換え
影響対象ExtensionAttachTo を使用するコード(推定)
利用側では現在、Extension<unknown>['attachTo'] を使用します。
原文を表示
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.github.com/backstage/backstage/releases/tag/v1.57.0フロントエンドの useApi による promise を値とする Utility API ref の展開
影響対象@backstage/frontend-plugin-api の useApi で使用する、promise を値とする Utility API ref
必要な対応既存の API ref を promise に変更する場合の、利用側とカスタムファクトリーの同時更新
以前、このフックは promise をそのまま返していましたが、現在は API を取り出します。読み込み中は suspend し、拒否理由はエラーバウンダリーに送られます。promise が必要な場合は useApiHolder().get(ref) を使用してください。
原文を表示
### **BREAKING**: Lazy Utility API implementations
Utility API factories can now load implementations on demand through dynamic imports. Declare the API value as a promise, for example `ApiRef<Promise<WorkApi>>`. The `useApi` hook from `@backstage/frontend-plugin-api` unwraps the promise, suspends while it is pending, and throws rejection reasons to an error boundary:
```ts
const workApiRef = createApiRef<Promise<WorkApi>>().with({
id: 'plugin.example.work',
});
const workApi = useApi(workApiRef); // WorkApi
```
The hook's return type is now `Awaited<T>`. Consumers that intentionally used a promise returned by `useApi` must switch to `useApiHolder().get(ref)`. Changing an existing API ref to a promise changes its public contract, so update its consumers and custom factories together. Holders and factory dependencies continue to receive the declared API value unchanged. The legacy `useApi` hook from `@backstage/core-plugin-api` continues returning promises directly.github.com/backstage/backstage/releases/tag/v1.57.0Promise を返す API で同期モックを利用可能に
影響対象TestApiProvider、その他のモック API オーバーライド、または renderInTestApp を使い、Promise を返す API またはモックを扱うテスト
これまでは、Promise を返す API に対する同期モックは受け入れられませんでした。レンダリングがそれ以外の点で同期的であれば、テストでは同期的なアサーションをそのまま使えるようになりました。Promise を返すモックの解決中、renderInTestApp は空の Suspense フォールバックを表示します。そのため、祖先の境界が表示するローディング UI に依存していたテストでは、アサーションの更新が必要になる場合があります。
原文を表示
Page extension boundaries provide Suspense and error handling; consumers outside those boundaries must provide their own. `TestApiProvider` and other mock API overrides accept synchronous mocks even for promise-valued APIs, so tests can keep synchronous assertions when rendering is otherwise synchronous. Promise-valued mocks are also supported, with `renderInTestApp` supplying an empty Suspense fallback while they resolve. Tests that relied on an ancestor boundary's loading UI may need updated assertions. See the [Utility API documentation](../frontend-system/utility-apis/02-creating.md) for lazy factories and migration guidance.
github.com/backstage/backstage/releases/tag/v1.57.0テストアプリヘルパーで報告された作成エラーを例外として扱う変更
影響対象renderInTestApp、renderTestApp、または createExtensionTester を使うテスト
必要な対応不正なテスト設定の修正、または意図的なエラーを isExpectedError で許可する設定。API のオーバーライドには、extensions 内の競合するファクトリーではなく、テストアプリの apis オプションを使用すること
これまでは、アプリが壊れていてもテストが成功することがありました。今後は、アプリまたは拡張機能ツリーの作成中に報告されたエラーがあるとテストが失敗します。実際のアプリでは警告としてログに記録されるだけのエラーも対象ですが、isExpectedError が許可したエラーは除きます。
原文を表示
`renderInTestApp`, `renderTestApp`, and `createExtensionTester` now throw for all errors reported while creating the test app or extension tree, including errors that a real app only logs as warnings. Fix invalid test setups, or allow an intentional error through the `isExpectedError` option. API overrides belong in the test app's `apis` option; a conflicting factory supplied through `extensions` is rejected. Contributed by [@dyatko](https://github.com/dyatko) in [#36333](https://github.com/backstage/backstage/pull/36333).
github.com/backstage/backstage/releases/tag/v1.57.0テストアプリでアプリごとのインメモリストレージを使用
影響対象ブラウザーのストレージ、表示される通知、グローバルなエラー処理、または遅れて登録した購読者へのアラート再送に依存するテストアプリ
必要な対応ブラウザーのストレージ、表示される通知、またはグローバルなエラー処理に依存するテスト向けの明示的な API 実装
トーストとエラーは表示せずに収集されます。また、遅れて登録した購読者へのアラートの再送は行われなくなりました。以前は、遅れて登録した購読者にもアラートが再送されていました。
原文を表示
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0本番用 JSON ログへの行ごとのタイムスタンプ追加
影響対象本番用 JSON ログを使用する環境
必要な対応リクエストログの date フィールドまたは日付プレフィックスを利用するログパイプラインとダッシュボードでは timestamp への切り替え、カスタム JSON ロガー形式ではタイムスタンプ保持のための format.combine(format.timestamp(), format.json()) の指定
以前は、ルート HTTP ルーターのリクエストログにのみ date フィールドがあり、message の先頭にも同じ値が繰り返し記録されていました。他の本番用 JSON ログ行にはタイムスタンプがありませんでした。現在、標準ログではこれらのリクエストログ値は出力されません。カスタムロガー形式では、必要な形式の組み合わせを含めない限り、タイムスタンプは保持されません。
原文を表示
Production JSON logs now include a `timestamp` field on every line. Root HTTP router request logs no longer include a `date` field or repeat the date at the start of the message. Update log pipelines and dashboards that read either of those values to use `timestamp`. Custom JSON logger formats should combine `format.timestamp()` with `format.json()` to preserve the field.
github.com/backstage/backstage/releases/tag/v1.57.0LDAP 組織取り込みでマッピング対象属性をデフォルトで要求
影響対象LDAP 組織エンティティプロバイダーおよび LdapOrgReaderProcessor の設定
必要な対応マッピング対象外の属性を必要とするカスタム変換器では、該当属性を users.options.attributes または groups.options.attributes に列挙するか、['*', '+'] ですべての属性を要求する設定。明示的に設定するリストには、マッピング、ベンダー設定、変換器が必要とするすべての属性を含めること。
以前は検索時にすべての LDAP 属性が含まれていたため、カスタム変換器はマッピング対象外の属性も読み取ることができました。アップグレード後は、そうした追加属性が LDAP エントリーに含まれない場合があります。
根拠“**BREAKING**: Searches no longer request `['*', '+']` by default. This applies to both the org entity provider and `LdapOrgReaderProcessor`. When options.attributes is not explicitly configured, attributes required by map (including custom map.\* overrides and membership mappings) are requested automatically. When options.attributes is explicitly configured, the provided list is used as-is and must include all attributes required by mappings, vendor configuration, and custom transformers. Custom transformers that access other attributes from LDAP entries may now find those attributes missing.” backstage/backstage/pull/35319 ↗ 原文を表示
LDAP organization ingestion now requests only the attributes used by configured mappings, instead of `['*', '+']`. This affects both the entity provider and `LdapOrgReaderProcessor`. Custom transformers that read additional attributes must list them in `users.options.attributes` or `groups.options.attributes`, or explicitly use `['*', '+']` to request all attributes. An explicitly configured list is used as-is and must include every attribute needed by mappings, vendor configuration, and transformers.
github.com/backstage/backstage/releases/tag/v1.57.0LDAP エンティティープロバイダーのデフォルトでの並列読み取り
影響対象接続数の制限により逐次読み取りが必要なディレクトリに接続している LDAP エンティティープロバイダー
必要な対応接続数の制限により逐次読み取りが必要なディレクトリで、プロバイダーに disableParallelReads: true を設定
以前は、更新のたびに1つの LDAP 接続を使ってユーザーとグループを順番に読み取っていました。現在は、disableParallelReads: true を設定しない限り、更新ごとに2つの接続を開いてバインドします。
根拠“The LDAP org entity provider now reads users and groups in parallel by default. Set `disableParallelReads: true` to use one connection and read sequentially. Parallel reads open two binds and two connections per refresh. Directories with per-client connection limits may notice the extra load after upgrading.” backstage/backstage/pull/35319 ↗ 原文を表示
The entity provider also reads users and groups in parallel by default, opening two connections and binds per refresh. Set `disableParallelReads: true` on the provider to retain sequential reads when directory connection limits require it. Connections are closed after each refresh.
github.com/backstage/backstage/releases/tag/v1.57.0TranslationRef の値が呼び出し可能な関数に
影響対象TranslationRef の値を使用するコード
必要な対応TranslationRef の値を不透明な値として扱うこと。複製やプレーンオブジェクト形式の確認は禁止
原文を表示
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0Bitbucket Cloud のワークスペースコード検索にユーザー識別可能な認証情報が必要に
影響対象ワークスペースのコード検索を使用する Bitbucket Cloud エンティティプロバイダーの統合
必要な対応ワークスペースのコード検索には、ユーザーを識別できる認証情報が必要です。たとえば、Atlassian アカウントのメールアドレスを username とし、API の token を使用して、read:repository:bitbucket と read:workspace:bitbucket の両方のスコープを付与します。
以前はコード検索 API に read:workspace:bitbucket は不要でしたが、認証情報が拒否された場合、検出処理はワークスペースのコード検索ではなくソース API に送られるようになりました。API トークンに read:workspace:bitbucket を追加すると、ワークスペースのコード検索を再び利用できます。
根拠“Bitbucket Cloud rejects app passwords, legacy OAuth consumers, and API keys for this API. An API token without `read:workspace:bitbucket` is also rejected with `403`. When that happens, or when code search is not enabled, the provider checks catalog files with the source API instead.” backstage/backstage/pull/36845 ↗ 原文を表示
The Bitbucket Cloud entity provider now uses the workspace code search API following retirement of the previous endpoint on November 15, 2026. Workspace code search requires a credential that identifies a user, such as an Atlassian account email as `username` with an API `token`, and both `read:repository:bitbucket` and `read:workspace:bitbucket` scopes. App passwords, legacy OAuth consumers, API keys, and API tokens missing the workspace scope are rejected by that API.
github.com/backstage/backstage/releases/tag/v1.57.0不正なCatalogフィルターでHTTP 400を返すように
影響対象$all、$any、または$notを使うCatalogクエリフィルター
フィルターオブジェクトでこれらの演算子のいずれかを他のキーと組み合わせた場合、または$allや$anyに配列以外の値を指定した場合、余分なキーは黙って無視され、件数クエリと一覧クエリでオブジェクトの解釈が異なることがありました。
原文を表示
Malformed predicates that combine `$all`, `$any`, or `$not` with other keys in the same object, or pass non-array operands to `$all` or `$any`, now receive a 400 response instead of silently ignoring parts of the filter. Entity lookups through `entities/by-refs` now match case-insensitively, consistent with the entity reference contract. Contributed by [@chicobento](https://github.com/chicobento) in [#36744](https://github.com/backstage/backstage/pull/36744).
github.com/backstage/backstage/releases/tag/v1.57.0Catalog データベースへの公開管理情報の追加
影響対象SQLite、MySQL、PostgreSQL を使用する Catalog バックエンドのインストール環境
SQLite と MySQL では、古いインスタンスが、以前に割り当てられた generation を保持したままコンテンツを上書きすることがありました。そのため、この値だけでは変更がすべて追跡されていることを証明できませんでした。今回のアップグレードでは、既存のエンティティを書き換えずに NULL 許容の generation 列を追加し、PostgreSQL ではインデックスを並行して構築します。
原文を表示
The catalog database upgrade also adds publication bookkeeping and builds an index concurrently on PostgreSQL. The index build scans the catalog table and can exceed deployment startup deadlines on large installations. Review [upgrading large installations](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md#upgrading-large-installations) for instructions on preparing the column and index before deploying.
Internal publication bookkeeping adds a nullable generation column without
rewriting existing entities. PostgreSQL builds its index concurrently, but still
scans the entire catalog table, even when every generation is null.
The metadata transaction has a five-second lock-wait timeout. If it expires,
startup fails and must retry; repeated failures can cause deployment restart
loops. The concurrent index phase has no imposed timeout and can wait on long
transactions elsewhere in the database, including other plugins using separate
schemas. It may exceed deployment startup deadlines.
github.com/backstage/backstage/releases/tag/v1.57.0サインインリゾルバーのユーザートークンクレームにおける正規化・重複排除済みエンティティ参照
影響対象エンティティ参照を含むユーザートークンクレームを発行するサインインリゾルバーを使用する構成
原文を表示
Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
github.com/backstage/backstage/releases/tag/v1.57.0初回使用時に読み込むMarkdownContentレンダラー
影響対象MarkdownContent を使用するアプリ
初回使用時にレンダラーを読み込むことで、アプリの起動時バンドルが小さくなります。レンダリングされた Markdown をすぐに検証するテストでは、非同期クエリが必要になる場合があります。
原文を表示
- `MarkdownContent` loads its renderer on first use, reducing the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.
github.com/backstage/backstage/releases/tag/v1.57.0Backstage CLI コマンドの終了コード維持
影響対象Backstage CLI の終了コードに依存する自動化処理(推定)
原文を表示
- CLI commands preserve their exit codes, and package startup supports repeated `--import` and `--require` flags. Flag support contributed by [@dotboris](https://github.com/dotboris) in [#36647](https://github.com/backstage/backstage/pull/36647).
github.com/backstage/backstage/releases/tag/v1.57.0旧アプリルーター API の利用不可
影響対象RouterBlueprint、app/root ルーター入力、convertLegacyAppOptions({ components: { Router } })、または BrowserRouter を設定するオーバーライドを使用するアプリ
必要な対応BrowserRouter のみを設定するオーバーライドの削除、グローバルプロバイダーの AppRootWrapperBlueprint への移行、遅延読み込みされるページコンポーネント内でのページアダプターのレンダリング
原文を表示
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.github.com/backstage/backstage/releases/tag/v1.57.0routerOptions で指定できる値を replace と state のみに変更
影響対象replace または state 以外の値で routerOptions を設定しているコード
原文を表示
Backstage UI routing is configured automatically in Backstage apps. Standalone apps must provide a `useNavigation` hook to `BUIProvider` if they previously relied on automatic React Router integration. `routerOptions` now only accepts `replace` and `state`, and links using `javascript:`, `data:`, or `vbscript:` become inert. See the [routing migration notes](../frontend-system/architecture/60-migrations.md#157) and [page router guide](../frontend-system/building-plugins/10-page-routers.md) for setup and migration examples.
github.com/backstage/backstage/releases/tag/v1.57.0DialogApi.open による show と showModal の置き換え
影響対象ダイアログ API を使用する拡張機能および API 実装(推定)
必要な対応show または showModal を使うカスタム拡張機能と API 実装の更新、独自のダイアログ表示での DialogApi.open の使用と core.dialog.v2 API リファレンスの参照、@backstage/frontend-plugin-api と合わせた @backstage/plugin-app のアップグレード
原文を表示
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0アイコン API が IconsApi.icon と core.icons.v2 を使用
影響対象アイコン API を使用する拡張機能と API 実装(推定)
必要な対応@backstage/frontend-plugin-api と併せた @backstage/plugin-app のアップグレード
原文を表示
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0@backstage/frontend-plugin-api/alpha エントリーポイントの削除
影響対象@backstage/frontend-plugin-api/alpha からのインポート(推定)
必要な対応@backstage/frontend-plugin-api/alpha からのインポートをメインエントリーポイントからのインポートに置き換え
エクスポートはメインエントリーポイントでも、同じ動作と同一性を保ちます。
原文を表示
- Replace imports from `@backstage/frontend-plugin-api/alpha` with imports from the main entry point. The `/alpha` entry point has been removed; its exports retain the same behavior and identity at their new location.
github.com/backstage/backstage/releases/tag/v1.57.0IconBundleBlueprint がアイコン要素を必須化
影響対象IconBundleBlueprint、IconComponent、またはアイコンバンドル内の Material UI アイコンを使用する拡張機能
必要な対応IconComponent ではなく IconElement を使用し、IconBundleBlueprint にアイコン要素を指定すること。Material UI アイコンでは <MyIcon fontSize="inherit" /> を使用すること
以前は、IconBundleBlueprint はアイコンコンポーネントを受け取り、IconComponent 型も利用できました。convertLegacyAppOptions 経由で渡されるアイコンは引き続き自動変換され、認証プロバイダーのアイコンでは引き続きコンポーネントを使用できます。
原文を表示
- Use `IconElement` instead of the removed `IconComponent` type. `IconBundleBlueprint` now requires elements such as `icons: { user: <MyIcon /> }` rather than components. For Material UI icons, use `<MyIcon fontSize="inherit" />`. Icons passed through `convertLegacyAppOptions` are converted automatically, and auth provider icons continue to accept components.github.com/backstage/backstage/releases/tag/v1.57.0Specialized app のセットアップを prepare/finalize フローへ移行
影響対象createSpecializedApp を使用するアプリ
必要な対応createSpecializedApp から prepareSpecializedApp(options).finalize() への置き換え。サインイン機能または非同期のセッション準備を行うアプリでの、ブートストラップアプリのレンダリングと onFinalized() 経由の購読。確定済みセッションの再利用における advanced.sessionState の使用
原文を表示
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0ApiBlueprint 拡張機能で登録されたカスタム API
原文を表示
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0カスタムナビゲーションコンポーネントでの navItems の使用
以前はフラットな items コレクションを受け取っていましたが、現在は navItems.rest() を通じて項目にアクセスし、item.href と item.title を使用します。item.icon は React 要素として描画します。
原文を表示
- Custom navigation components now receive `navItems` instead of the flat `items` collection. Use `navItems.rest()`, `item.href`, and `item.title`, and render `item.icon` as a React element.
github.com/backstage/backstage/releases/tag/v1.57.0分析機能と拡張ミドルウェアのインポート元変更
影響対象記載された分析関連のエクスポートまたは ExtensionFactoryMiddleware をインポートするプロジェクト(推定)
AnalyticsImplementation、AnalyticsImplementationBlueprint、AnalyticsImplementationFactory のインポート元は @backstage/plugin-app-react です。ExtensionFactoryMiddleware のインポート元は @backstage/frontend-app-api です。
原文を表示
- Import `AnalyticsImplementation`, `AnalyticsImplementationBlueprint`, and `AnalyticsImplementationFactory` from `@backstage/plugin-app-react`, and `ExtensionFactoryMiddleware` from `@backstage/frontend-app-api`.
github.com/backstage/backstage/releases/tag/v1.57.0withApis から useApi を使う関数コンポーネントへの置き換え
影響対象withApis を使用するフロントエンドシステムのコード(推定)
必要な対応withApis から useApi を使う関数コンポーネントへの置き換え
原文を表示
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0フロントエンドプラグインのエイリアス削除
影響対象id、PageTab、PluginOptions エイリアスを使用する拡張機能(推定)
必要な対応削除された id、PageTab、PluginOptions エイリアスの代わりに、FrontendPlugin.pluginId、PageLayoutTab、CreateFrontendPluginOptions を使用
このリリース以前は、拡張機能で名前付きの置き換え先の代わりにこれらのエイリアスが使われていました。アップグレード後は、置き換え先となるプロパティと型を使用します。
原文を表示
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0ProgressProps を既存の {} 型に置き換え
影響対象ProgressProps を使用する利用者(推定)
原文を表示
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.github.com/backstage/backstage/releases/tag/v1.57.0アラートとトーストの設定で無視されていた anchorOrigin オプションの削除
影響対象anchorOrigin を指定する組み込みアラート表示設定、またはトースト表示プロパティ(推定)
これらの設定では anchorOrigin を指定できましたが、このオプションは無視されていました。
原文を表示
- Remove the ignored `anchorOrigin` option from built-in alert display configuration and toast display props.
github.com/backstage/backstage/releases/tag/v1.57.0FrontendFeature プラグインでの pluginId 提供必須化
影響対象pluginId プロパティ導入前の、FrontendFeature として渡されるプラグイン
必要な対応pluginId プロパティ導入前のプラグインを、現行のフレームワークバージョンに対して再ビルドする必要
原文を表示
Plugins passed as a `FrontendFeature` must now provide `pluginId`. Rebuild plugins that predate this property against a current framework version.
github.com/backstage/backstage/releases/tag/v1.57.0スタンドアロンのモック型の削除
影響対象スタンドアロンのモック型を使用するテストコード
スタンドアロンのモック型は、このリリースより前は利用できました。現在は、たとえば ReturnType<typeof mockApis.analytics> のように、mockApis ヘルパーから型を導出できます。
原文を表示
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0ページのマッチングにフレームワークのルーティングを使うナビゲーションテスト
影響対象ルーティングライブラリのコンテキストを必要とする要素を含むナビゲーションテスト
必要な対応ルーティングライブラリのコンテキストを必要とするテスト要素をページアダプターでラップすること
原文を表示
Both render helpers now return an `apis` holder with access to the same Utility API instances used by components, including test overrides. For navigation tests, use `apis.get(coreApis.appHistory)` to access the app history. Page matching uses framework routing; wrap test elements in a page adapter when they need routing-library context. See the [navigation testing guide](../frontend-system/building-plugins/02-testing.md#navigation-and-app-history).
github.com/backstage/backstage/releases/tag/v1.57.0サポート対象の Node.js バージョンを 22・24 から 24・26 に変更
影響対象Node.js 22 を使用する、またはルートの engines.node、CI ワークフロー、Docker イメージで Node.js のバージョンを指定している Backstage 環境
必要な対応ルートの package.json の engines.node を ^24.15.0 || ^26.13.0 に設定し、CI ワークフローと Docker イメージにも一致する Node.js バージョンを設定すること、および create-app で必要な Node.js 24.15.0 以降または 26.13.0 以降
原文を表示
The supported Node.js versions are now 24 and 26. Update `engines.node` in your root `package.json` to `^24.15.0 || ^26.13.0`, and check the versions used in your CI workflows and Docker images. Versions of `avsc` before 5.7.8 can break tests on Node.js 26, and `node-gyp` 12.3.0 cannot download headers through a proxy on that version; run `yarn up -R avsc` or `yarn up -R node-gyp` if your lockfile contains the affected versions.
github.com/backstage/backstage/releases/tag/v1.57.0Backstage CLI のコンパイルターゲットを ES2024 に引き上げ
影響対象Backstage CLI パッケージのビルド、アプリバンドル、バックエンドの開発用変換
必要な対応TypeScript 5.9 以降。フロントエンドで ES2024 の組み込み機能を使う場合は、Chrome または Edge 119、Firefox 121、または Safari 17.4 以降
これらのビルドと変換のターゲットが ES2023 から ES2024 に引き上げられます。ES2024 の組み込み機能を使うフロントエンドコードには、ポリフィルがありません。
原文を表示
The CLI now compiles for ES2024 and requires TypeScript 5.9 or later. Backstage does not include polyfills, so frontend code using ES2024 APIs such as `Object.groupBy` needs Chrome or Edge 119, Firefox 121, or Safari 17.4 or later. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36512](https://github.com/backstage/backstage/pull/36512) and [#36509](https://github.com/backstage/backstage/pull/36509).
github.com/backstage/backstage/releases/tag/v1.57.0ほとんどのフロントエンドパッケージで React 18 が必要
影響対象フロントエンドパッケージを使用するアプリ、特に React 17 のアプリと旧フロントエンドシステム
必要な対応React 18
旧フロントエンドシステムのコアパッケージは、自身の peer dependency の範囲では React 17 を引き続き指定していますが、それらの依存パッケージは React 18 を必要とします。
原文を表示
Most frontend packages now require React 18. The old front-end system core packages retain React 17 in their own peer dependency ranges, but their dependencies include packages that require React 18, so apps using the old system also need to plan the upgrade. See the [React 18 migration guide](../tutorials/react18-migration.md) and [frontend migration notes](../frontend-system/architecture/60-migrations.md#react-17-support-removed).
github.com/backstage/backstage/releases/tag/v1.57.0createGitlabTokenValidator での logger 引数の必須化
影響対象カスタム実装からの createGitlabTokenValidator の呼び出し
必要な対応カスタム実装から呼び出す場合に必要な、新しい logger 引数の指定
原文を表示
For development setups that deliberately accept unauthenticated events, each module provides an explicit `dangerouslyAllowUnauthenticatedEvents: true` option. Custom users of `createGitlabTokenValidator` must also supply its new `logger` argument. See the configuration sections for the [GitHub](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-github/README.md#configuration), [GitLab](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md#configuration), and [Azure DevOps](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-azure/README.md#configuration) modules.
github.com/backstage/backstage/releases/tag/v1.57.0Scaffolder Google Cloud のタスク復旧時の保存失敗の修正
影響対象Scaffolder Google Cloud モジュールを使ったタスク復旧
必要な対応アップグレード前に必要な、バックエンドの Google Cloud 認証情報への storage.objects.list 権限の付与(タスク復旧バケット、既存のオブジェクト権限に追加)
テンプレートのステップが短時間に続けて完了すると、スナップショットが同じ Google Cloud Storage オブジェクトを上書きし、変更レート制限に達してタスク復旧用ワークスペースの保存に失敗することがありました。現在はスナップショットを別々のオブジェクトに保存します。復旧時には最新のスナップショットを復元し、旧バージョンで作成されたスナップショットにも対応します。保存に成功すると古いスナップショットを削除し、削除に失敗した場合は警告をログに記録します。
根拠“Fixed task recovery workspace saves failing with Google Cloud Storage rate limit errors when template steps finish in quick succession. Each snapshot is saved to a separate object, and recovery continues to support snapshots from older versions.” backstage/backstage/pull/36466 ↗ 原文を表示
### **BREAKING**: Google Cloud task recovery permissions
The Scaffolder Google Cloud module now stores each task recovery snapshot as a separate object, avoiding storage rate limits when template steps finish in quick succession. Grant the backend's Google Cloud credentials `storage.objects.list` on the task recovery bucket before upgrading, in addition to the existing object permissions. Recovery continues to support snapshots saved by older versions.
github.com/backstage/backstage/releases/tag/v1.57.0バックエンド HTTP ルーターサービスに WebSocket ルート用の addWebSocketHandler を追加
影響対象カスタム HttpRouterService または RootHttpRouterService の実装を使用する構成、またはバックエンドテストユーティリティを使用する構成
必要な対応カスタム HttpRouterService および RootHttpRouterService の実装における addWebSocketHandler の実装
原文を表示
The backend HTTP router services now provide `addWebSocketHandler` for registering WebSocket upgrade routes. Routes require token authentication by default, and browser clients can pass bearer tokens through the WebSocket protocol header. Cookie authentication is not supported. Custom implementations of `HttpRouterService` and `RootHttpRouterService` must implement the new method; the backend test utilities support it too.
github.com/backstage/backstage/releases/tag/v1.57.0Express のみでの WebSocket アップグレード処理を router API に移行
影響対象フレームワークのサーバーレベルリスナーが有効で、Express 経由のみで WebSocket アップグレードを処理するプラグイン
フレームワークのサーバーレベルリスナーだけが有効な場合、ルーター経由で照合されないアップグレード要求には404が返されます。移行中は既存のサーバーアップグレードリスナーと共存でき、ルーターでは addWebSocketHandler を使ってアップグレードルートを登録できます。
原文を表示
The Signals backend uses this API, fixing first connections that previously required an HTTP request before the WebSocket could connect. Existing server upgrade listeners can coexist during migration, but plugins that handle upgrades only through Express, such as the Kubernetes proxy, must migrate to the router API when the framework's server-level listener is active. Otherwise, unmatched upgrades receive a 404 response when it is the only server-level listener. See the [HTTP router service documentation](../backend-system/core-services/http-router.md).
github.com/backstage/backstage/releases/tag/v1.57.0カスタム TranslationApi のスナップショットで t が必須
影響対象カスタム TranslationApi 実装を使うセットアップ
必要な対応カスタム TranslationApi 実装では、ready が false の間も含め、利用可能なメッセージと言語フォールバックを使って、すべての翻訳スナップショットで t を提供すること
原文を表示
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0coreServices と mockServices オブジェクトの凍結
影響対象coreServices または mockServices の実行時の変更、または mockServices のヘルパーオブジェクトへのスパイ
これらの操作は以前はサポートされていましたが、現在はサポートされていません。既存の呼び出しと型は引き続き利用でき、ヘルパーが作成したモックには影響しません。
原文を表示
- `coreServices` and `mockServices` are now frozen objects. Existing calls and types remain available, but runtime mutation and spying on the mock service helpers themselves are no longer supported; the mocks they create are unaffected.
github.com/backstage/backstage/releases/tag/v1.57.0ウォッチモード以外での OpenAPI 生成失敗時の非ゼロ終了コード
影響対象package schema openapi generate による OpenAPI クライアントまたはサーバーの生成
以前は、生成された出力に対する package lint の失敗などが発生しても、コマンドの終了コードが 0 になることがありました。ウォッチモード以外では、ジェネレーターの処理完了後に非ゼロの終了コードを返すようになりました。ウォッチモードではエラーをログに記録し、監視を続けます。
根拠“Outside watch mode they now wrap and rethrow the error, and `generate/index.ts` waits for all running generators to settle before exiting so a failure in one doesn't cut off the other mid-run. Watch mode still logs the error and keeps watching.” backstage/backstage/pull/36854 ↗ 原文を表示
- OpenAPI client and server generation commands exit with a non-zero status when generation fails, allowing CI to detect failures. Watch mode keeps watching after errors. Contributed by [@aksharprabhudesai](https://github.com/aksharprabhudesai) in [#36854](https://github.com/backstage/backstage/pull/36854).
github.com/backstage/backstage/releases/tag/v1.57.0@backstage/cli-module-package-manager-yarn の Yarn 依存関係をオプショナルなピア依存関係に変更
影響対象@backstage/cli-module-package-manager-yarn のインストール
必要な対応上流の問題が修正されるまで、pm verify-patches の実行に必要なルートの開発依存関係 @yarnpkg/cli、@yarnpkg/core、@yarnpkg/plugin-patch と、解決指定 "@yarnpkg/core/got": "npm:^11.8.6"
上流でのインストール失敗を回避します。
原文を表示
- `@backstage/cli-module-package-manager-yarn` makes its Yarn dependencies optional peers to avoid an upstream installation failure. Until fixed upstream, users of `pm verify-patches` must add `@yarnpkg/cli`, `@yarnpkg/core`, and `@yarnpkg/plugin-patch` as root development dependencies, along with the resolution `"@yarnpkg/core/got": "npm:^11.8.6"`.
github.com/backstage/backstage/releases/tag/v1.57.0CodeOwnersProcessor と AnnotateScmSlugEntityProcessor のエクスポート削除
影響対象このパッケージから CodeOwnersProcessor または AnnotateScmSlugEntityProcessor を使用するバックエンド(推定)
必要な対応いずれかのプロセッサーの動作を維持するための、対応するコミュニティモジュールのバックエンドパッケージへのインストールと backend.add(import('<module-package>')) による登録、および二重登録を避けるための旧カスタムプロセッサー登録の削除
原文を表示
## Migrating removed processors
`CodeOwnersProcessor` and `AnnotateScmSlugEntityProcessor` are no longer exported
by this package. Use the corresponding community modules to retain their behavior:
- `CodeOwnersProcessor`: [`@backstage-community/plugin-catalog-backend-module-codeowners`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-codeowners)
- `AnnotateScmSlugEntityProcessor`: [`@backstage-community/plugin-catalog-backend-module-annotate-scm-slug`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-annotate-scm-slug)
Install the module you need in your backend package and register it with
`backend.add(import('<module-package>'))`. Remove your custom registration of the
old processor to avoid registering it twice. If you need to configure a processor
explicitly, follow the replacement module's documentation.github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md