Mixins vs @extend: Which Minimizes Generated CSS Size in Stylus?

Direct Answer

For a UI kit with many components sharing flat, static property sets, @extend on placeholder selectors usually produces smaller compiled CSS than mixins. Mixins duplicate every declaration at each call site, while @extend groups selectors into a single rule. The savings are most reliable when the extended selectors are defined before use and the reuse count is high.

If your shared blocks contain nested selectors, media queries, or parameterized values, mixins may still be safer. In those cases @extend can concatenate selectors inside at-rules and inflate specificity, which may force additional override rules and erase the size advantage.

Confirmed vs. Likely Behavior

Confirmed: Stylus mixins emit property declarations each time they are invoked. @extend merges selectors into one rule set, reducing output when the same block is reused. Stylus does not tree-shake unused mixin definitions; if a mixin is never called, its body remains in the compiled CSS. By contrast, @extend only generates CSS for selectors that actually extend another selector.

Likely and requiring verification: Complex mixins with nested rules or media queries can cause @extend selector bloat due to concatenation. Deep @extend chains can also inflate specificity, making overrides harder and potentially adding rules that counteract size savings. These effects depend on your Stylus version and project structure.

When @extend Wins on Size

• High reuse across simple, flat property lists.
• Placeholder selectors (%base) keep the base rule out of the output unless extended.
• Cross-file @extend works only when the target selector is imported before the file that extends it.

Mitigating Specificity and Ordering Risks

1. Keep extended selectors shallow; avoid deep @extend chains across components.
2. Define placeholder selectors in a base file and import it first.
3. Use mixins for parameterized values and @extend for static shared blocks.
4. Compile with --compress to measure real payload impact.

Verification Steps

Create two minimal fixtures: one using a mixin across ten selectors, one using @extend on a placeholder with the same properties. Compile both and compare byte sizes.

stylus --compress mixin-test.stylus -o mixin-test.css
stylus --compress extend-test.stylus -o extend-test.css
wc -c mixin-test.css extend-test.css

Run a CSS analyzer or linter on the output to confirm that no unused rules remain. Repeat with different reuse counts to find the break-even point for your kit.

Missing Diagnostic Detail

One detail changes the recommendation: do your shared style blocks include media queries or nested selectors? If yes, mixins are likely the safer default despite duplication, because @extend can concatenate selectors inside those constructs and raise specificity. If they are flat property lists, @extend is the leaner choice.