@backstage/rename-header-main-class
Backstage 1.51.0 migration codemod that renames the removed .bui-Header CSS class to .bui-HeaderContent and updates the corresponding classNames.root property access to classNames.content.
What it does
CSS class rename
In BUI v0.15.0 (Backstage 1.51.0), the root .bui-Header class and HeaderDefinition.classNames.root were removed. The Header DOM was split into section classes (headerTop, headerBottom, content, titleStack, tags, etc.). Custom CSS targeting .bui-Header must be updated to target the remaining section classes.
This codemod finds and replaces the root class name in:
- String literals (
'.bui-Header') - Template literals (
`.bui-Header`) - Object property keys in styled-components, Emotion, MUI
styled(), etc. - Standalone CSS/SCSS files (via a dedicated CSS pass)
Section classes such as .bui-HeaderTop, .bui-HeaderBottom, and .bui-HeaderContent are not modified.
Property access rename
Replaces classNames.root with classNames.content in JS/TS:
Object keys in classNames overrides are also updated when the value targets bui-Header.
Descendant/child selector warnings
When the codemod detects a CSS selector using > (child combinator) or descendant combinators after .bui-Header, it adds a TODO comment because the root wrapper element was removed and these selectors may need restructuring:
Known limitations
- Complex selectors in concatenated strings: If the class name is split across multiple string concatenations, the codemod may not detect the full selector context for adding TODO comments.
- Intent for section classes: The codemod defaults to
bui-HeaderContent/content; some overrides may needheaderToporheaderBottominstead.
Optional: AI fixup step
Enable with --param aiFixup=true to address edge cases:
- Reviews TODO comments and assesses whether selectors need restructuring
- Checks for remaining
bui-Headerreferences in styled-components or Emotion - Verifies selector correctness after the root element removal
- Reverts incorrect renames of section classes
Installation
Usage (from this repo)
Development
From the repo root:
Or from this package directory:
License
MIT