@backstage/humanize-entity-ref-to-presentation
Backstage 1.50.0 migration codemod that replaces deprecated humanizeEntityRef and humanizeEntity from @backstage/plugin-catalog-react with the Catalog Presentation API.
What it does
Context-dependent replacement
The codemod detects the call-site context and applies the appropriate replacement:
| Context | Before | After |
|---|---|---|
| JSX expression | {humanizeEntityRef(ref)} | <EntityDisplayName entityRef={ref} /> |
| React component body | const name = humanizeEntityRef(ref) | const name = useEntityPresentation(ref).primaryTitle |
| Non-React / utility | humanizeEntityRef(ref) | entityPresentationSnapshot(ref).primaryTitle |
Options mapping
defaultKindanddefaultNamespaceoptions are mapped to the context parameter foruseEntityPresentationandentityPresentationSnapshot, or to JSX props forEntityDisplayName.
humanizeEntity
humanizeEntity(entity, fallbackName) follows the same context-dependent replacement. The fallback parameter is dropped since the Presentation API handles display name resolution automatically.
Import handling
- Deprecated import specifiers are removed from the import statement
- New imports (
EntityDisplayName,useEntityPresentation,entityPresentationSnapshot) are added as needed based on the replacements used - Other specifiers from the same import statement are preserved
- Aliased imports (e.g.,
import { humanizeEntityRef as formatRef }) are handled correctly
Re-exports
Re-exports like export { humanizeEntityRef } from '@backstage/plugin-catalog-react' are replaced with the new API exports.
Known limitations
- Namespace imports (
import * as CatalogReact from '...') are detected but not transformed — a warning is emitted for manual migration. humanizeEntityRefreturnsstringwhileEntityDisplayNamereturnsJSX.Element. If the return value is used where only a string is accepted (e.g., passed to a function expectingstring), the JSX replacement may cause type errors that need manual correction.useEntityPresentationis a React hook and cannot be used outside React components or in conditional branches. The codemod only uses it inside functions that contain JSX.- Complex options expressions: If the options argument is a variable reference or computed expression rather than an inline object literal, the JSX props conversion for
EntityDisplayNamewill not parse it.
Optional: AI fixup step
Enable the AI-powered fixup step with --param aiFixup=true to address edge cases:
- Rewrites namespace imports
- Fixes type compatibility issues where
stringwas expected but JSX was substituted - Corrects mixed-context files where the wrong replacement was chosen
Installation
Usage (from this repo)
Development
From the repo root:
Or from this package directory: