DEV Community

Nicholas Petrasek
Nicholas Petrasek

Posted on Fully Autonomous

My Angular Flex-Layout migration compiled. The spacing was wrong.

#angular #css #opensource #webdev

The Angular build passed. The footer still had the wrong spacing.

I found this while trying my Angular Flex-Layout codemod against the archived Kubernetes Dashboard frontend. I maintain the codemod, and I wanted a codebase with enough history to find cases my examples weren't covering.

The problem came down to one directive: fxLayoutGap.

The conversion that looked reasonable

Here is a simplified version of the problematic pattern:

<footer fxLayoutGap="16px">
  <a href="/docs">Docs</a>
  <a href="/support">Support</a>
</footer>
Enter fullscreen mode Exit fullscreen mode

A tempting migration is to remove the directive and add a class:

<footer class="footer-gap">
  <a href="/docs">Docs</a>
  <a href="/support">Support</a>
</footer>
Enter fullscreen mode Exit fullscreen mode 
.footer-gap {
  gap: 16px;
}
Enter fullscreen mode Exit fullscreen mode

It parses. It compiles. The CSS is valid.

But if that footer is an ordinary block container, gap doesn't produce the spacing the old directive did.

Flex-Layout's ordinary gap behavior uses margins on children. CSS gap belongs to a layout context: flex, grid or multi-column. MDN's reference describes those contexts. Putting gap on a regular block container doesn't turn it into one.

Adding display: flex just to make the gap work would introduce another change. Now the children participate in flex layout, which may affect their sizing and placement. That needs an intentional layout decision.

A directive name doesn't establish the layout

The easy case has both directives on the same element:

<div fxLayout="row" fxLayoutGap="16px">
  <button>Cancel</button>
  <button>Save</button>
</div>
Enter fullscreen mode Exit fullscreen mode

That gives the migration tool evidence about the container. The standalone gap gives it much less.

Responsive directives make this harder. If the container is flex at one viewport width, can the tool establish the required layout wherever the gap is active? A conversion that works on a wide screen can still be wrong on a narrow one.

The check has to consider the effective layout across those ranges.

What changed in 2.0.1

I changed the codemod to preserve an uncertain fxLayoutGap and report it for review when it cannot establish the needed flex layout on the same element across the active ranges.

That leaves some work for the developer. I prefer an explicit unresolved directive to a clean-looking diff with missing spacing.

After the fix, the Dashboard trial scanned 164 templates and proposed changes in 103. For both the native CSS and Tailwind targets, the report contained:

  • 327 converted directives
  • 13 cases needing review
  • 3 invalid cases

The two standalone gaps stayed in the source for review. Those numbers describe the migration proposal; they don't mean the whole application has been migrated. This was a local trial on the archived project.

The fix is in release 2.0.1.

Trying it on your own templates

The CLI supports native CSS and Tailwind CSS v4. It requires Node 22.12 or newer, which can be different from the runtime your older Angular application uses.

Start in a branch and install the version used here:

npm install --save-dev --save-exact @nipe-solutions/flex-layout-codemod@2.0.1
Enter fullscreen mode Exit fullscreen mode

For a native CSS proposal:

npx flex-layout-codemod ./src/app \
  --target css \
  --stylesheet ./src/flex-layout.css \
  --plan
Enter fullscreen mode Exit fullscreen mode

This plans the conversion without writing templates or a stylesheet. Review the proposed changes and unresolved diagnostics before using --write. The workflow guide covers stylesheet inclusion and the write step.

A few boundaries matter: the CLI works on external HTML templates, preserves unsupported cases, and doesn't remove Flex-Layout imports or dependencies. Unresolved cases produce exit code 2 by default. You still need to account for them before removing the original library.

For a migration like this, I'd check the build, then check the actual layout at the viewports used by the application. Spacing, wrapping and alignment deserve their own review.

If you're maintaining an Angular app that still uses Flex-Layout, I'd appreciate a trial on one representative directory. A small template that converts incorrectly is especially useful. Open an issue with the input, target and expected layout, or try the single-template playground first.

Have you run into a migration where the compiler was happy but the UI changed?

I maintain this alongside other NIPE open-source frontend libraries. I'm looking for real usage and reproducible feedback to help improve them.

Top comments (0)