호환성 변경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를 사용하는 코드
이전에는 이 훅이 선언되지 않은 splat 파라미터를 반환할 수 있었습니다. 이제 이 훅에 의존하는 코드는 라우트 ref에 선언된 파라미터만 받습니다.
원문 보기
`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.0Promise 값을 가진 Utility API ref를 이제 언래핑하는 프런트엔드 useApi
영향 대상@backstage/frontend-plugin-api의 useApi에서 사용하는 Promise 값을 가진 Utility API ref
필요 조치기존 API ref를 Promise로 변경할 때 해당 소비자와 커스텀 팩토리도 함께 업데이트해야 함
이전에는 이 훅이 Promise를 그대로 반환했지만, 이제 API를 언래핑하고 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에 동기 mock 허용
영향 대상Promise를 반환하는 API 또는 mock과 함께 TestApiProvider, 기타 mock API override 또는 renderInTestApp을 사용하는 테스트
이전에는 Promise를 반환하는 API에 동기 mock을 사용할 수 없었지만, 이제 렌더링이 다른 면에서 동기적으로 이뤄지는 경우 테스트에서 동기 assertion을 유지할 수 있습니다. Promise를 반환하는 mock이 resolve되는 동안 renderInTestApp은 빈 Suspense 폴백을 제공합니다. 따라서 상위 Suspense 경계의 로딩 UI에 의존하던 테스트는 assertion을 수정해야 할 수 있습니다.
원문 보기
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 옵션 사용
이전에는 앱이 정상 작동하지 않아도 테스트가 통과할 수 있었습니다. 이제 앱이나 extension tree를 생성하는 동안 보고된 오류가 있으면 테스트가 실패합니다. 실제 앱에서는 경고로만 로그되는 오류도 해당하며, 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 로그 줄에는 타임스탬프가 없었습니다. 이제 표준 로그에서는 요청 로그의 해당 값들이 빠지고, 프로덕션 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 설정
이전에는 새로고침할 때마다 LDAP 연결 하나로 사용자와 그룹을 순차적으로 읽었습니다. 이제 disableParallelReads: true를 설정하지 않으면 새로고침마다 연결 두 개를 열고 바인드합니다.
근거“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.0호출 가능한 함수가 되는 TranslationRef 값
영향 대상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로 전달됩니다. 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에 배열이 아닌 피연산자를 지정하면, 추가 키가 조용히 무시되어 count 쿼리와 list 쿼리에서 객체를 서로 다르게 해석할 수 있었습니다.
원문 보기
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.0카탈로그 데이터베이스에 게시 이력 관리 정보 추가
영향 대상SQLite, MySQL 또는 PostgreSQL을 사용하는 카탈로그 백엔드 설치 환경
SQLite와 MySQL에서는 이전 인스턴스가 기존에 할당된 generation 값을 유지한 채 콘텐츠를 덮어쓸 수 있었습니다. 따라서 이 값만으로는 변경 사항이 모두 추적되었음을 입증할 수 없었습니다. 이번 업그레이드에서는 기존 엔티티를 재작성하지 않고 널 허용 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로그인 resolver의 사용자 토큰 클레임에 포함되는 정규화·중복 제거된 엔터티 참조
영향 대상엔터티 참조가 포함된 사용자 토큰 클레임을 발급하는 로그인 resolver를 사용하는 설정
원문 보기
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.0show 및 showModal을 대체하는 DialogApi.open
영향 대상다이얼로그 API를 사용하는 확장 기능 및 API 구현(추정)
필요 조치show 또는 showModal을 사용하는 커스텀 확장 기능과 API 구현 업데이트, 자체 다이얼로그 표시 방식과 core.dialog.v2 API 레퍼런스를 활용한 DialogApi.open 사용, @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.0특수 앱 설정의 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.0Analytics 및 extension middleware의 import 경로 변경
영향 대상AnalyticsImplementation, AnalyticsImplementationBlueprint, AnalyticsImplementationFactory 또는 ExtensionFactoryMiddleware를 import하는 프로젝트(추정)
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.0useApi를 사용하는 함수형 컴포넌트로 withApis 대체
영향 대상프런트엔드 시스템에서 withApis를 사용하는 코드(추정)
필요 조치useApi를 사용하는 함수형 컴포넌트로 withApis 대체
원문 보기
- 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.0alert 및 toast 설정에서 무시되던 anchorOrigin 옵션 제거
영향 대상내장 alert 표시 구성 또는 anchorOrigin을 지정하는 toast 표시 props(추정)
이 설정에서는 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독립형 mock 타입 제거
영향 대상독립형 mock 타입을 사용하는 테스트 코드
독립형 mock 타입은 이번 릴리스 이전까지 제공됐습니다. 이제 mockApis 헬퍼에서 타입을 추론할 수 있습니다. 예를 들어 ReturnType<typeof mockApis.analytics>를 사용할 수 있습니다.
원문 보기
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
구형 프런트엔드 시스템의 코어 패키지는 자체 피어 의존성 범위에 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 사용자 정의 호출
필요 조치사용자 정의 호출 시 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 모듈의 task recovery 워크스페이스 저장 실패 수정
영향 대상Scaffolder Google Cloud 모듈로 task recovery를 구성한 경우
필요 조치업그레이드 전, 기존 객체 권한에 더해 백엔드의 Google Cloud 인증 정보에 task recovery 버킷의 storage.objects.list 권한 부여
템플릿 단계가 짧은 간격으로 완료되면 스냅샷이 같은 Google Cloud Storage 객체를 덮어써 객체 변경 속도 제한에 걸릴 수 있었고, 그 결과 task recovery 워크스페이스 저장이 실패할 수 있었습니다. 이제 저장할 때 별도의 객체를 사용합니다. 복구 시 최신 스냅샷을 복원하고 이전 버전의 스냅샷도 지원합니다. 저장에 성공하면 오래된 스냅샷을 정리하며, 정리에 실패하면 경고를 로그에 기록합니다.
근거“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 업그레이드 처리의 라우터 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 생성 실패 시 0이 아닌 종료 코드 반환
영향 대상package schema openapi generate를 통한 OpenAPI 클라이언트 또는 서버 생성
이전에는 package lint가 생성된 출력물 검사에 실패하는 등의 오류가 발생해도 명령이 종료 코드 0으로 끝날 수 있었습니다. 이제 워치 모드가 아니면 생성기가 모두 완료된 뒤 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 및 다음 resolution: "@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 export 제거
영향 대상이 패키지의 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