0
# PostCSS Flexbugs Fixes
1

2
PostCSS Flexbugs Fixes is a PostCSS plugin that automatically fixes common CSS flexbox bugs documented in the flexbugs project. The plugin addresses three specific flexbox issues: unitless flex-basis values being ignored (bug 4), the default flex value changes (bug 6), and flex-basis not supporting calc() expressions (bug 8.1.a).
3

4
## Package Information
5

6
- **Package Name**: postcss-flexbugs-fixes
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-flexbugs-fixes`
10

11
## Core Imports
12

13
```javascript
14
const flexbugs = require('postcss-flexbugs-fixes');
15
```
16

17
For ES modules:
18

19
```javascript
20
import flexbugs from 'postcss-flexbugs-fixes';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require('postcss');
27
const flexbugs = require('postcss-flexbugs-fixes');
28

29
// Use with default settings (all bugs enabled)
30
postcss([flexbugs()])
31
  .process(css, { from: undefined })
32
  .then(result => {
33
    console.log(result.css);
34
  });
35

36
// Disable specific bug fixes
37
postcss([flexbugs({ bug6: false, bug81a: false })])
38
  .process(css, { from: undefined })
39
  .then(result => {
40
    console.log(result.css);
41
  });
42
```
43

44
## Capabilities
45

46
### Plugin Factory Function
47

48
Creates a PostCSS plugin instance with configurable bug fixes.
49

50
```javascript { .api }
51
/**
52
 * Creates a PostCSS plugin to fix common flexbox bugs
53
 * @param {Object} [opts] - Configuration options
54
 * @param {boolean} [opts.bug4=true] - Fix unitless flex-basis values (flexbug #4)
55
 * @param {boolean} [opts.bug6=true] - Fix default flex value changes (flexbug #6)
56
 * @param {boolean} [opts.bug81a=true] - Fix flex-basis calc() support (flexbug #8.1.a)
57
 * @returns {Object} PostCSS plugin object
58
 */
59
function flexbugsPlugin(opts) {
60
  // Returns PostCSS plugin object
61
}
62

63
// Export as default
64
module.exports = flexbugsPlugin;
65

66
// PostCSS plugin marker
67
module.exports.postcss = true;
68
```
69

70
**Options Interface:**
71

72
```javascript { .api }
73
interface FlexbugsOptions {
74
  /** Enable/disable fix for flexbug #4 - unitless flex-basis values ignored */
75
  bug4?: boolean;
76
  /** Enable/disable fix for flexbug #6 - default flex value changes */
77
  bug6?: boolean;
78
  /** Enable/disable fix for flexbug #8.1.a - flex-basis doesn't support calc() */
79
  bug81a?: boolean;
80
}
81
```
82

83
**Note:** The source code uses the option name `bug81a`, not `bug8a` as mentioned in some project documentation.
84

85
**Plugin Object Interface:**
86

87
```javascript { .api }
88
interface PostCSSPlugin {
89
  /** Plugin identifier */
90
  postcssPlugin: string;
91
  /** Plugin processor function that walks CSS declarations */
92
  Once: (css: PostCSS.Root, postcss: PostCSS.Helpers) => void;
93
}
94
```
95

96
### Usage Examples
97

98
**Fix unitless flex-basis values (Bug 4):**
99

100
Input CSS:
101
```css
102
.foo { flex: 1; }
103
.bar { flex: 1 1; }
104
.foz { flex: 1 1 0; }
105
.baz { flex: 1 1 0px; }
106
```
107

108
Output CSS (when Bug 6 is also enabled, which is default):
109
```css
110
.foo { flex: 1 1; }
111
.bar { flex: 1 1; }
112
.foz { flex: 1 0; }
113
.baz { flex: 1 1; }
114
```
115

116
Output CSS (when Bug 6 is disabled):
117
```css
118
.foo { flex: 1 1 0%; }
119
.bar { flex: 1 1 0%; }
120
.foz { flex: 1 1 0%; }
121
.baz { flex: 1 1 0%; }
122
```
123

124
**Fix default flex value changes (Bug 6):**
125

126
Input CSS:
127
```css
128
.element { flex: 1; }
129
.element2 { flex: 1 0 0%; }
130
```
131

132
Output CSS:
133
```css
134
.element { flex: 1 1; }
135
.element2 { flex: 1 0; }
136
```
137

138
Note: Bug 6 removes the `0%` flex-basis when present to work around Safari issues. When Bug 6 is combined with Bug 4 (default), Bug 4 first normalizes unitless basis values to `0%`, then Bug 6 removes any `0%` basis values entirely.
139

140
**Fix calc() in flex-basis (Bug 8.1.a):**
141

142
Input CSS:
143
```css
144
.element { flex: 1 0 calc(1vw - 1px); }
145
```
146

147
Output CSS:
148
```css
149
.element {
150
  flex-grow: 1;
151
  flex-shrink: 0;
152
  flex-basis: calc(1vw - 1px);
153
}
154
```
155

156
**Selective bug fixing:**
157

158
```javascript
159
// Only fix bug 4 and 6, disable bug 8.1.a
160
postcss([flexbugs({ bug81a: false })])
161
  .process(css, { from: undefined });
162

163
// Only fix bug 6
164
postcss([flexbugs({ bug4: false, bug81a: false })])
165
  .process(css, { from: undefined });
166

167
// Disable all fixes
168
postcss([flexbugs({ bug4: false, bug6: false, bug81a: false })])
169
  .process(css, { from: undefined });
170
```
171

172
## Integration Examples
173

174
**With PostCSS CLI:**
175

176
```json
177
{
178
  "postcss": {
179
    "plugins": {
180
      "postcss-flexbugs-fixes": {}
181
    }
182
  }
183
}
184
```
185

186
**With Webpack:**
187

188
```javascript
189
module.exports = {
190
  module: {
191
    rules: [
192
      {
193
        test: /\.css$/,
194
        use: [
195
          'style-loader',
196
          'css-loader',
197
          {
198
            loader: 'postcss-loader',
199
            options: {
200
              postcssOptions: {
201
                plugins: [
202
                  ['postcss-flexbugs-fixes', { bug6: false }]
203
                ]
204
              }
205
            }
206
          }
207
        ]
208
      }
209
    ]
210
  }
211
};
212
```
213

214
**With Gulp:**
215

216
```javascript
217
const gulp = require('gulp');
218
const postcss = require('gulp-postcss');
219
const flexbugs = require('postcss-flexbugs-fixes');
220

221
gulp.task('css', () => {
222
  return gulp.src('src/*.css')
223
    .pipe(postcss([flexbugs()]))
224
    .pipe(gulp.dest('dist/'));
225
});
226
```