necolas / cssnext

Use tomorrow's CSS syntax, today

Use tomorrow's CSS syntax, today.

This is not a CSS preprocessor, but can replace one.
This is a CSS transpiler (CSS4+ to CSS3) that allow you to use tomorrow's CSS syntax today. It transforms CSS specs that are not already implemented in popular browsers into more compatible CSS.
Take a look to available features.

cssnext is similar to Myth or SUIT CSS preprocessor but push the concept to the next level by supporting more features.

cssnext works great with SUIT CSS and cssrecipes.

tl;dr : try cssnext in your browser.

Follow @cssnext to get latest news & join #cssnext on irc.freenode.net if you have any questions.

Goals

• Allow using future CSS syntax today.
• Keep code close as possible to the original code.

Non-Goals

• Provide polyfills for future CSS APIs that depend on the client browser.

Features

Available

• automatic vendor prefixes (via autoprefixer)
• custom properties & var() (via postcss-custom-properties)
• reduced calc() (via postcss-calc, to optimize previously parsed var() references)
• custom media queries (via postcss-custom-media), a nice way to avoid repeating media queries
• color() (via postcss-color), a color function to modify color
• hwb() (via postcss-color), similar to hsl() but easier for humans to work with
• #rrggbbaa (via postcss-color)

Additionals enhancements

• @import inline local files (via postcss-import) to output an bundled CSS file.

@todo

Any omissions of the CSS specifications (even in draft) that are subject to be handled by cssnext are not intentional.
Feel free to open a new issue if you find something that should be handled.
Keep in mind that, as of right now, this project is intended to support new CSS syntax only.

---

Installation

$ npm install cssnext

You can install it

• globally (-g), to use it through the CLI
• locally ()--save or --save-dev), to use it through npm scripts (npm run) or via .node_modules/.bin/csnext
• by using other tools like gulp-cssnext

Usage

You can use cssnext using CLI, as a JavaScript library or through others tools.

CLI

cssnext offer a command-line interface. Here's how to compile a file and print it to stdout:

$ cssnext index.css

To create an output file, you can just add a second argument

$ cssnext index.css output.css

Or use CLI std(in|out) redirection(s)

$ cat input.css | cssnext > output.css

CLI options

If you don't care about a certain feature, such as custom media queries, you can omit support for them like so:

$ cssnext --no-custom-media index.css

To enable source maps for these files, add the --sourcemap flag.

To see all CLI options

$ cssnext --help

Node.js API

var cssnext = require("cssnext")
var fs = require("fs")

var input = fs.readFileSync("index.css", "utf8")

var output = cssnext(input)
fs.writeFileSync("dist/index.css", output)

cssnext accept 2 arguments: a css string and an object of options.

Node.js options

For now, all options are passed to all postcss plugins. This mean you should be able to any specific plugin options.

features (default: all features)

Object containing key of features to enable/disable.
No key means feature is enabled.

//eg: disable color support
var output = cssnext({
  features: {
    color: false
  }
})

Here is all available features:

• import
• customProperties
• calc
• customMedia
• color
• prefixes

browsers (default: autoprefixer default)

Array to specify browsers you want to target (for now only used by autoprefixer).
See autoprefixer documentation of this option for more details.

Default to something like ["> 1%", "last 2 versions", "Firefox ESR"].

compress (default: false)

Allow you to compress the output (using CSSWring).

sourcemap (default: false)

If you want a accurate sourcemap, please use instead the from option.

This option is a shortcut to enable inlined sourcemap in the output.
Just pass true to get the sourcemap at the end of the output.
If you want better control on sourcemap, use postcss map option directly.

from (default: null)

Source of the file. Needed for sourcemap.

var cssnext = require("cssnext")
var fs = require("fs")

var source = "./index.css"
var output = cssnext(
  fs.readFileSync(source, "utf8"),
  {from: source}
)
fs.writeFileSync("dist/index.css", output)

path (default: dirname(from) || process.cwd())

A string or an array of paths in where to look for files when inlining using @import.
Default to dirname of postcss from or fallback to process.cwd().

Note: nested @import will additionally benefit of the relative dirname of imported files.

Usage with other tools

Here are some tools that will help you use cssnext in your current workflow

• gulp-cssnext
• grunt-cssnext
• @todo brunch plugin
• @todo brocolli plugin
• @todo component-builder package
• @todo meteor package

---

Contributing

cssnext uses a lot of postcss plugins, so you might need to take a look at them if you found an issue or want to create or enhance a feature.

Otherwise, work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.

$ git clone https://github.com/cssnext/cssnext.git
$ git checkout -b patch-1
$ npm install
$ npm test

Changelog

License

---

Acknowledgements

Huge thanks to all the people that where involved in :

• rework
• rework css parser
• myth
• autoprefixer

Thanks to Andrey Sitnik for postcss.

Without all those people, this project would not exist.