postcss-flexbugs-fixes

postcss-flexbugs-fixes is a small, focused PostCSS plugin that patches CSS output to work around the well-documented “flexbugs” — a set of inconsistent flexbox behaviors across browser implementations. It targets three specific issues: unitless flex-basis values being dropped from flex shorthand (bug #4), the changed default flex-basis behavior that trips up Safari (bug #6), and flex-basis’s lack of calc() support in older Safari (bug #8.1.a). Each fix is implemented as an isolated transform under bugs/, applied to every flex declaration during the PostCSS build step.

Because flexbox cross-browser quirks are notoriously hard to track down by hand, this plugin became a near-default inclusion in JavaScript build tooling — most notably bundled into Create React App’s PostCSS pipeline, giving it reach far beyond its direct npm install count. It ships with per-bug toggles (bug4, bug6, bug8a), skips flex values that reference CSS custom properties to avoid breaking dynamic theming, and requires postcss ^8.1.4 as a peer dependency rather than bundling its own copy.

What You Get

• Three targeted bug fixes - Rewrites flex shorthand for bug #4 (unitless flex-basis dropped), bug #6 (changed default basis), and bug #8.1.a (calc() unsupported in flex-basis).
• Per-bug opt-out flags - bug4, bug6, and bug8a options let consumers selectively disable any individual fix.
• Safe custom-property handling - Skips rewriting any flex value that references a CSS custom property (var(...)) so dynamic theming isn’t broken.
• Zero-config drop-in - Works with sensible defaults out of the box; just add it to a PostCSS plugin array with no options required.

Common Use Cases

• Cross-browser flexbox layouts - Teams shipping layouts built with flex shorthand who need consistent rendering in Safari and older browsers without hand-writing longhand properties.
• Create React App-style build pipelines - Projects that inherited this plugin as part of a bundled PostCSS config (e.g. CRA) and want to understand or tune what it’s doing.
• Selective bug patching - Projects affected by only one of the three flexbugs, disabling the others via the bug4/bug6/bug8a options.

Under The Hood

Architecture The plugin exports a single factory function (index.js) that merges user options with defaults (bug4, bug6, bug81a all true) and returns a PostCSS plugin object using the Once visitor API from PostCSS 8. Inside, it walks every declaration via css.walkDecls, short-circuiting on values containing var( or equal to none, then conditionally invokes three independent transform modules (bugs/bug4.js, bugs/bug6.js, bugs/bug81a.js), each a pure function operating on a single declaration node in place. There’s no shared state between the three fixes and no build step — the whole surface area is one entry point plus three sibling files, so changing one fix has no effect on the others.

Tech Stack Plain CommonJS JavaScript with no transpilation step; it depends only on postcss (^8.1.4) as a peer dependency, meaning consumers supply their own PostCSS instance. Dev tooling is dated — gulp plus gulp-mocha and gulp-eslint drive the npm test script, chai provides assertions, and .travis.yml still targets Node 15 on Travis CI. There is no bundler, no TypeScript, and only a yarn.lock (no npm lockfile); files in package.json ships just bugs/ and index.js to consumers.

Code Quality Tests live under specs/ using a shared test.js helper that runs each fixture through postcss([plugin(opts)]).process(...) and asserts on result.css with Chai’s expect, covering all three bug fixes plus a pluginSpec.js and regressiveSpecs.js for regression fixtures — a real, if old-school, test suite (Mocha via gulp-mocha) with reasonable edge-case coverage (unitless basis, calc(), var()). There are no type annotations or shipped type definitions, error handling is minimal (no validation of malformed input, relying on PostCSS’s own parser), naming is short but consistent (bug4, bug6, bug81a mirroring the flexbugs issue numbers), and CI runs on Travis, a largely dormant service today, so automated checks on new PRs are questionable.

API Design The public API is a single factory function matching PostCSS’s plugin convention exactly (plugin(opts) returning {postcssPlugin, Once}), so integration is a one-liner in any postcss.config.js with zero required configuration — defaults fix all three bugs immediately. The only configuration surface is three boolean flags mirroring the underlying flexbugs issue numbers, easy to discover from the README’s per-bug documentation but assuming familiarity with PostCSS’s own plugin-array wiring. No TypeScript types are shipped, so option and return shapes rely entirely on the README and PostCSS’s own conventions for discoverability.