postcss-extend
v1.0.5
Published
As close to cssnext @extend as possible for PostCSS
Downloads
136,357
Readme
postcss-extend
A PostCSS plugin that tries to minimize the number of repeat selectors and rules you write in CSS.
Use this plugin to:
- Define a "silent" extendable selector — a "placeholder selector" — to which you can (from anywhere in the doc) add concrete selectors from other rule sets.
- Add concrete selectors from one rule (containing the
@extend
) to all rule sets with the selector specified (or a subclass of the one specified). - Pull in declarations in rulesets (most) anywhere in the doc (by a selector) from within
@media
statements (semi-safely) - Extend existing media-conscious rulesets, even if some of them are within
@media
statements.
Installation | Usage | Getting it Working | Quirks --- | --- | --- | ---
The logical statement of this @extend
is to "allow my parent rule to use the declarations of what I extend".
The functionality is intended to somewhat mirror Sass's @extend
with %
placeholders (a.k.a. "silent classes") and real rules.
Unlike Sass's @extend
, however, this plugin (among other things) does not allow you to extend into selector sequences: i.e. if you want to @extend a
, it will not go off and try to extend:
#admin .tabbar a {
font-weight: bold;
}
Nor will trying to @extend a:hover
match:
.comment a.user:hover {
color: red;
}
It will however, try to extend selector sequences with the base-piece to work with, i.e. trying to @extend .never
will match:
.never li:first {
color: red;
}
/*or*/
.never.ever {
color: blue;
}
Arguably, these limitations make this plugin both less dangerous than SASS's @extend
, and enforce more (obviously-)predictable behaviors. However, many of SASS @extend
's other behaviors have been kept, or altered in such a way to allow ease of use, but not necessarily the same level of strict logical extension.
In regards to the concerns people have with Sass's @extend
, and the problems that can arise from its use, many do not apply to this stripped-out version. However, it is by no means foolproof, and Smart Sass users often recommend to only ever @extend
placeholders (cf. Harry Robert and Hugo Giraudel): with this plugin, that recommendation is not enforced, but syntactically set apart.
postcss-extend
is compatible with PostCSS v5.0+.
A Note on "mixins" & "extends": Mixins copy declarations from an abstract definition into a concrete rule set. These
@extend
s (normally) clone a concrete rule set's selector(s) and add them to an abstract placeholder selector, or another existing rule. This plugin enables extends. If you would like to use mixins, as well — or instead — have a look atpostcss-mixins
.
Installation
npm install postcss-extend --save
Public Service Announcement: Because of an issue with postcss-nested
, if you are trying to use both postcss-nested
and this plugin, you need to use this plugin first.
Usage
Defining Placeholders
With @define-placeholder
, you associate a rule set with a placeholder selector, which you will later extend with concrete selectors. It (and its other aliases) can only be extended if it's already been declared in the document, is at the root-level (not inside anything) and cannot be extended-out-of.
You can also use its aliases: @define-extend
or @extend-define
.
@define-placeholder simple-list {
list-style-type: none;
margin: 0;
padding: 0;
}
/* or @define-extend simple list {...} */
/* or @extend-define list {...} */
@define-placeholder
at-rules, and the placeholder names (e.g. simple-list
, above), will be removed entirely from the generated CSS, replaced by the selectors you've added via @extend
(see example above).
The "%" (silent) placeholder
The "%" placeholder acts similarly to @define-placeholder
and its aliases, with four exceptions. One, that it doesn't need to be declared before it is extended. Two, you can extend out of it (thus extending anything that extends the placeholder, or nothing if the placeholder isn't referenced). Three, it needs to be specifically targeted in the extend, for example: @extend %simple-list
. Four, it doesn't need to be at the root in order to work - and can be inside of something else (e.g. an @media
):
%container {
padding-left: 15px;
}
@media (--md-viewport) {
%container {
padding-left: 2em;
}
}
.extendingClass {
@extend %container;
}
(@define-placeholder
's limitations are an originally unintended feature, kept for its possible usefulness as a stricter, more controlled method of extending).
Additionally, all definitions will log a warning if they go unused, and should only contain declarations and comments: no statements (violations will also log warnings).
Extending Rules or Placeholders
Use the at-rule @extend
within a rule set to add that rule set's selector(s) to a placeholder (which was defined via @define-placeholder
).
You can also use its alias `@define-extend'.
.list-i-want-to-be-simple {
@extend simple-list;
font-size: 40em;
}
Rules and placeholders are extended in much the same fashion; the only real difference is that placeholders can be named most anything, whereas rules need to be extended via the same syntax in the css. For example, to extend a 'foo' class it'd be @extend .foo
There is only one overarching @extend
guideline to obey: @extend
must not occur at the root level, it only can be used inside rule sets.
Extending Sub Classes and Sub Elements
Whenever extending a rule or placeholder, you are also automatically trying to extend any subclasses or elements that have exactly what you selected (before a space, .
, :
, or #
). For example:
.potato {
color: white;
}
.potato:first-child,
.potato a::after {
background: brown;
}
#superfun {
@extend .potato;
}
Resolves to:
.potato, #superfun {
color: white;
}
.potato:first-child, .potato a::after, #superfun:first-child, #superfun a::after {
background: brown;
}
Make note that #superfun
deletes itself, because otherwise it would have been empty brackets.
You also can still specifically extend subclasses by-themselves by calling them out explicitly.
If (in the above example) you wanted to only get background:brown
instead of everything having to do with .potato
, you could just use @extend .potato:first-child;
.
Extending with @media
The bridging behavior of this plugin is by far its most dangerous, despite the steps to keep it relatively sane. Be mindful.
The logical statement of this @extend
is to "allow my parent rule to use the declarations of what I extend." Thus, when within an @media rule, its behavior takes on the contingency of the rule, and instead of tacking on its parent's selectors to rules it extends (thus using their declarations), it directly brings in the declarations.
Simple declaration pulling
Trying to extend a rule outside an @media
from the inside is fairly straightforward. For example:
.potato {
color: white;
outline: brown;
font-family: sans-serif;
}
@media (width > 600px) {
.potato:first {
float: center;
}
.spud {
@extend .potato;
color: red;
font-size: 4em;
}
}
Resolves to:
.potato {
color: white;
outline: brown;
font-family: sans-serif;
}
@media (width > 600px) {
.potato:first, .spud:first {
float: center;
}
.spud {
color: red;
font-size: 4em;
outline: brown;
font-family: sans-serif;
}
}
Notice how .spud
only takes in declarations from .potato
that it doesn't already have. Extending will never override declarations already present while copying. Additionally, notice how .spud
extends .potato
's pseudo-class (:first
) inside the media scope by tacking onto the target rule, just like before. That's because it is scope-conscious (especially while in an @media
).
External Sub classes
So what does it do when subclasses of the extended rule are also outside @media
?
.potato {
float: left;
}
.potato:first, .potato ul:first-child {
float: right;
}
@media (width > 600px) {
.spud {
@extend .potato;
font-weight: bold;
color: red;
}
.spud:first {
background: purple;
}
}
Resolves to:
.potato {
float: left;
}
.potato:first, .potato ul:first-child {
float: right;
}
@media (width > 600px) {
.spud {
font-weight: bold;
color: red;
float: left;
}
.spud ul:first-child {
float: right;
}
.spud:first {
background: purple;
float: right;
}
}
First let's notice that the sub class .spud ul:first-child
(which wasn't within @media
originally) is created with a copy of .potato ul:first-child
's declaration. Meanwhile, .spud:first
was already within the @media
rule, and it took on the extra declaration. If there is a rule within the @media
with exactly the same selectors as what it would create, it will just pull in declarations. Keep in mind, the same ideas apply here while "pulling in" declarations: it copies, but won't replace.
Extending something inside @media
(on the outside looking in)
So what if you want to extend something that's within an @media
from the root? It's actually fairly straightforward when you think about what that means.
@media (width > 600px) {
.spud {
font-weight: bold;
color: red;
}
.spud:first-child {
background: purple;
}
}
.sputnik {
@extend .spud;
font-weight: normal;
font-style: italic;
}
Resolves to:
@media (width > 600px) {
.spud, .sputnik {
font-weight: bold;
color: red;
}
.spud:first-child, .sputnik:first-child {
background: purple;
}
}
.sputnik {
font-weight: normal;
font-style: italic;
}
Extending from the root, just like before, just tacks on selectors onto target rules, even into the @media
. This stays true to the logic of this version of @extend
because it's maintaining the conditionality of the declarations within @media
.
Extending something in an @media
while inside an @media
Don't. It's currently directly-disallowed in code to prevent unexpected things from happening, and will throw an error to warn you. The current expectation is that the only time the majority of users would do this is when making a mistake. That expectation remains unless someone can present a solution and a logical way of handling this (not in the native CSS parser) that is also a realistic common-use case.
Chaining @extend
s, or extension-recursion
Definitely one of the more powerful features of SASS's @extend
is here too. It does, however, come with a slight caveat that it is order-agnostic, meaning that it doesn't enforce order by only extending that which came above it. It just goes.
.charlie {
@extend .delta;
font-weight: bold;
}
.alpha {
@extend .bravo;
color: red;
}
.bravo {
@extend .charlie;
background: blue;
}
.delta {
color: green;
background: gray;
}
Resolves to:
.charlie, .bravo, .alpha {
font-weight: bold;
}
.alpha {
color: red;
}
.bravo, .alpha {
background: blue;
}
.delta, .charlie, .bravo, .alpha {
color: green;
background: gray;
}
Doesn't that take a lot of computation to do though? Well, not really since it's not "true" recursion. Since we're tacking on selectors, every rule is a living record of everything that has extended it, and if we're not tacking on selectors, we're copying everything we need from the other rule. Thus, in well-formed CSS we only need to go through the CSS doc once, top to bottom.
In anti-pattern CSS (extending things yet to be declared), it will handle @extend
recursively, but only if the extended target has unresolved @extend
rules in it (thus, slowing down processing, but keeping it working as expected). As a bonus, there is a built-in recursive-stack tracking that both detects infinite loops, and throws warnings (in order of least-tampered css first) for every step of the infinite loop. It also does its best to still process the CSS in the infinite loop (almost always as intended).
Getting It Working with PostCSS
Plug it in just like any other PostCSS plugin. There are no frills and no options, so integration should be straightforward. For example (as a node script):
var fs = require('fs');
var postcss = require('postcss');
var simpleExtend = require('postcss-extend');
var inputCss = fs.readFileSync('input.css', 'utf8');
var outputCss = postcss()
.use(simpleExtend())
// or .use(simpleExtend)
.process(inputCss)
.css;
console.log(outputCss);
Or take advantage of any of the myriad of other ways to consume PostCSS, and follow the plugin instructions they provide.
Quirks
As with any piece of code, it's got a few quirks. Behaviors that are not intended, and not enforced, may disappear (or be forcibly altered) with the next release, so it's useful to be aware of them.
Order of Processing : Currently, all of the @extend
s being processed are run in a sequential manner from the top to the bottom of the doc. This keeps things relatively snappy, but makes it so that we have to do conditional-recursion on not-yet-declared-or-extended rules. This leads to some blatant inefficiencies when processing badly formed CSS (anti-pattern CSS). So if you want to keep processing time down, write good CSS. If you're curious if what you're writing is an anti-pattern, don't worry, it will throw a warning.
Non-logical means of extension for @media
: As anyone who's aware of the complications discussed in the SASS issue about extending across @media
would know. There is no way (known) of extending when @media
rules are involved that is both 'clean and simple' and 'logically correct with how @extend
is used elsewhere'. The way this plugin operates, and its logical meaning, is a blatant compromise so that it has both common use cases and easier implementation. While the current implementations will not change (without flags), such things as extending an @media
from within an @media
does nothing, this could possibly change in the future.
'TLDR' Contention with the @extend
spec:
- Order of Processing/Specificity In normal cases, the document is processed top-to-bottom; however, as a feature-fallout of the implementation, it is capable of extending in an anti-pattern (extending things yet to be declared). If what you're writing is an anti-pattern, it will throw a warning.
- Specificity Inheritance Unlike example 5 in the spec,
@extend
in this plugin will not maintain the specificity of the rules extended to. Avoiding anti-patterns in your CSS will allow you to avoid this becoming an issue (pending browser implemenation). Does not log a warning. - Media-cross-media Inheritance Attempting to extend a rule inside a media block from within another media block is directly disallowed in the code and will throw a warning.
- Silent placeholders Includes both the stricter
@define-placeholder
and its aliases for compatibility with simple-extend, and the%
placeholder from the spec. As this isn't the native parser, the placeholder will be wiped from the CSS if it goes unused (as well as throw a warning). - Subclass inheritance Currently doesn't log a warning for its use, as it is not stated in the spec for or against its behavior (despite it logically following). All sub classes of an extended "base" class are extended, creating subclasses for the extending class as a means of mimicking the inheritance of specific sub-class contingencies (like
:active
) - "Whiff" extension trying to extend something that doesn't exist will log an error, and like everything else, remove the
@extend
rule.