postcss/postcss 5.0.0

5.0 “President Valac”

on GitHub

PostCSS 5.0 brings custom syntax and fixes plugin API.

It is a biggest release in project history. But do not worry, we have only few very rare breaking changes.

Breaking Changes

• safe option was removed and Safe Parse was moved to separated project.
  Use parser: require('postcss-safe-parser') instead.
• Node.js 0.10 is not officially supported anymore. However, PostCSS should still work, if you install and load the es6-promise polyfill.
• Node#toString does not include before space symbols for root nodes.
• Very rare returning new Root plugin API was removed.

Custom Syntaxes

Now PostCSS can transform styles in any syntax, not only in CSS. It is important for cases:

• We have many tools like CSSfmt or Stylelint, which works directly with sources. So now, they will be able to work with SCSS by postcss-scss.
• Now we can use shorter syntax for PostCS-only solutions. For example, // one line comments with SCSS parser or SugarSS with Stylus/Sass like syntax.
• CSS-in-JS solutions like React Style Autoprefix or Styling now can directly convert JS object to PostCSS AST without stringifing and reparsing.

PostCSS 5.0 has 3 new options:

• parser to change input parser. For example, to use Safe Parser in online demo tool.
• stringifier to change output content generator.
• syntax to change both parser and stringifier.

Because some syntax can return non-CSS value, Result now has content alias.

import scss from 'postcss-scss';

postcss().process(source, { syntax: scss }).then( (result) => {
    result.content // SCSS-to-SCSS transforms
});

postcss().process(source, { parser: scss }).then( (result) => {
    result.css // Compile SCSS one-line comments
});

We wrote good docs about developing new syntax for PostCSS. If you will have any questions, ask in our Gitter chat.

API Changes

In 5.0 we change nodes API to make it clear and more familiar to DOM or jQuery API.
Do not worry, old methods are still work, just show a deprecated message.

If your plugin is built with PostCSS 5.0, it will have plugin.process(css) shortcut to work as separated tool:

import nested from `postcss-nested`;
nested.process(css).then( result => console.log(result.css) );

@jedmao renamed eachInside, eachDecl, eachRule, eachAtRule and eachComment to walk, walkDecls, walkRules, walkAtRules and walkComments. So recursive behaviour is more clear.

@ben-eb with @jonathantneal made API more common with DOM API:

• Method remove deletes node itself and removeChild removes child from container.
• Method Node#replace was removed in favor of replaceWith.
• Insert methods now support multiple arguments with nodes.

All whitespace symbols properties now called “raw” and located in Node#raws object, so custom parser can add own custom raw properties. Node#style and cleanStyles methods were renamed to raw and cleanRaws:

if ( decl.raw('before').match(/\n/) ) {
    decl.raws.before = '';
}

Messages

PostCSS ecosystem now has one of the best CSS linters — Stylelint. So we make warning/error API much better.

First, In 5.0 we have smarter color support detection by @sindresorhus supports-color.

Second, we add word and index options to errors and warnings methods to highlight special word in bad node.

Third, we now have Node#warn shortcut to add warnings:

export default postcss.plugin('postcss-important-hater', () => {
    return (css, result) => {
        css.walkDecls( (decl) => {
            if ( decl.important ) {
                decl.warn(result, '!important is bad', { word: '!important' });
            }
        });
    };
});

// title.sass:2:15 !important is bad
// .title
//   color: black !important
//                ^

TypeScript and Windows

@jedmao made PostCSS really enterprise ready solution :).

First, he fix all tests on Windows and added AppVeyor CI to test every commit on Windows.

Second, he made really big job and added type definitions for TypeScript. For example, Visual Studio will show nice autocompletion with documentation:

Do not worry, PostCSS itself is still ES7 project.

Other Changes

• Deprecate CssSyntaxError#generated in favor of input.
• Deprecate Root#prevMap in favor of Root.source.input.map.
• Add stringifier option to Node#toString.
• Rule#selectors setter detects separators.
• Add postcss.stringify method.
• Throw descriptive errors for incorrectly formatted plugins.
• Add docs to npm release.
• Fix url() parsing.