FormKit Post-mortem: Dependency Versioning

[jason-capsule42]

Introduction

On Friday, November 7, 2025, the Auro team was alerted to an issue in the latest auro-formkit release involving the deprecation of the ondark feature and its replacement by the new appearance=”inverse” feature. This change resulted in incorrect color rendering in the auro-select component when appearance=”inverse” was used.

The issue was initially believed to be a missed CSS styling defect and was assigned to a senior engineer as an urgent priority. On Monday, November 10, the issue remained unresolved. To expedite progress, Jason Baker (@jason-capsule42) assumed ownership of the issue and continued the investigation with the assistance of Eunsun Mota (@sun-mota). His analysis determined that the problem was not a CSS styling bug, as originally suspected, but instead a build system issue within the auro-formkit monorepo.

After identifying the root cause, a build system fix was developed with assistance from Ryan Menner (@rmenner) and Doug Hooker (@DukeFerdinand). The solution was validated with Forrest Taylor (@ftaylor-alaska) from the Flight Search team and Aaron Utterback (@aaronaleixander) from the Content and Borealis teams. Following successful validation, the fix was released shortly before 5:00 PM on Monday, November 10. The updated version of auro-formkit was then integrated into Planbook and all downstream components which were deployed to the production homepage at approximately 11:00 PM.

Root Problem Explanation

All pages on the production website are assembled from front-end code contributed by multiple teams. Because each team may implement Auro components — often using different versions — a single page can end up loading multiple versions of the same component. To maintain compatibility and ensure consistent behavior across all implementations, each team must custom-register every Auro component they use. In practical terms, this means that every instance of an Auro component, when loaded in a different version, must be assigned a unique registration name.

For example, the Flight Search team uses auro-select within Planbook, but registers it under the unique name planbook-select to avoid conflicts with other versions of the component.

Complex Auro components are themselves composed of several child Auro components, which must also be uniquely registered per version. For instance, auro-select is built using auro-dropdown, auro-helptext, and other components. Because multiple teams may load different versions of auro-select on the same page, it is essential that each instance also registers its child components under unique names per version.

The root issue we encountered was that, due to a build setup issue, all versions of each FormKit component (e.g., auro-select) were using the same registration names for their child components, regardless of the parent’s custom registration. In other words, even when auro-select was renamed — for example, to planbook-select — its internal child dependencies were still registered using non-unique, version-agnostic names.

This resulted in the following failure scenario:

• HeaderFooter was built using an older version of auro-formkit that supported the ondark feature in both auro-select and auro-dropdown. When loaded onto the homepage, it registered auro-select as hf-select, and that instance registered its child dependency auro-dropdown as auro-dropdown-3_0_0.
• Planbook was then loaded onto the same page. This version used a newer auro-formkit release that replaced ondark with the new appearance=”inverse” feature. Planbook correctly registered auro-select as planbook-select, which is unique. However, due to the bug in the FormKit build system, the planbook-select instance also attempted to register auro-dropdown as auro-dropdown-3_0_0 — a name already claimed by the older HeaderFooter version.

As a result, Planbook’s planbook-select, which expected child components supporting the new appearance feature, was instead bound to auro-dropdown-3_0_0, which supported only the deprecated ondark feature. This resulted in planbook-select rendering with the wrong colors.

Future Risk Mitigation

Improve Component Testing

Currently, component-level testing is configured to validate only the latest, in development version of each component. This approach does not ensure that new versions function correctly alongside previous releases.

To improve compatibility verification, all automated testing infrastructure should be updated to load custom-registered instances of all supported component versions within a single test environment and validate that each version operates as expected.

Implementing this approach will enhance the detection of unintended breaking changes. When a breaking change is identified, the team can make an informed decision to either modify the implementation to remove the breaking change or, if necessary, coordinate with partner teams to migrate away from unsupported legacy versions.

The Auro team already has significant component level testing improvements in the 2025 Q4 roadmap utilizing Chromatic and Storybook. It is recommended that we prioritize the multi-version level testing approach into those scheduled improvements.

Develop Automated Testing For The Build System and Tooling

Currently, automated testing only validates the built components. The Auro team does not have automated coverage for the various libraries, utilities, and build system tools that have been developed.

A comprehensive review of all such code should be conducted, followed by the creation of a plan for thorough automated testing of all library, utility, and build system components. While developing this plan, the team should identify areas of highest risk to consuming teams and prioritize the creation of tests in those areas.