cssnext

Use tomorrow's CSS syntax, today.

This is a CSS transpiler (CSS4+ to CSS3) that allows you to use tomorrow's CSS syntax today. It transforms CSS specs that are not already implemented in popular browsers into more compatible CSS.

This is not a classic CSS preprocessor, but can totally replace one.

Check out the website or try cssnext in your browser.

---

Why / Features / Limitation / Installation / CLI Usage / Node.js API / Contribute

---

Why

Prior 2015, CSS was frustrating by not having any specification for features we were looking for. No variables, no math, no color manipulation & no customization. Things are going to change soon since a lot of work has been made by the W3C to write new specs to make our life easier.

This project aims to allow using future CSS syntax, today.

It is similar to Myth or SUIT CSS preprocessor but pushes the concept to the next level by supporting more features. It works great with cssrecipes or SUIT CSS.

It's not planned for now to provide polyfills for future CSS APIs that depend on the client browser.

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

Features

• automatic vendor prefixes (⇗),
• custom properties & var() (⇗) limited to :root,
• reduced calc() (⇗) to optimize previously parsed var() references),
• custom media queries (⇗) a nice way to have semantic media queries,
• media queries ranges (⇗) that allows to replace min-/max- with <= & >= (syntax easier to read),
• custom selectors (⇗) to create your own selectors,
• color() (⇗) a color function to modify colors,
• hwb() (⇗) similar to hsl() but easier for humans to work with,
• gray() (⇗),
• #rrggbbaa (⇗),
• rebeccapurple (⇗),
• font-variant properties (⇗),
• filter properties (⇗)

Bonus features

The features below are considered as bonus since it's totally not related to CSS specs.

• @import inline local files and modules - node_modules or web_modules (⇗) to output a bundled CSS file.
• minification is available (⇗) if you want to compress the output for production.

@todo

Any omissions of the CSS specifications (even in draft) that are subject to be handled by cssnext are not intentional.
You can take a look to the list of features that are waiting to be implemented.
Feel free to work on a feature ready to be added, or 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.

Limitation

Custom properties

The current transformation for custom properties just aims to provide a future-proof way of using a limited subset (to top-level :root selector) of the features provided by native CSS custom properties.
The transformation is not complete and can't be properly. By injecting selectors with new computed rules, we will break original cascade & unexpected results might happen.

---

Installation

$ npm install cssnext

You can install it

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

Usage

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

CLI

cssnext offers 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

cssnext can be used with it's own API

var string = cssnext(string, options)

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

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

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

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

/!\ Note: if you are using non inlined sourcemaps, cssnext will return a object: {css: string, map: sourcemap}

See sourcemap & map options for more informations.

var postcssPlugin = cssnext(options)

cssnext can be used as a postcss plugin

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

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

var output = postcss()
  .use(cssnext())
  .use(/* your other postcss plugin */)
  .process(input)
fs.writeFileSync("dist/index.css", output)

Node.js options

features (default: all features)

Object containing key of features to enable/disable.
Features are enabled by default: no key means feature is enabled.

//eg: disable import support
var output = cssnext(input, {
  features: {
    import: false
  }
})

Each features are based on PostCSS plugins & can get their own options. To pass options to a feature, you can just pass an object to the feature:

//eg: preserve custom properties
var output = cssnext(input, {
  features: {
    customProperties: {
      preserve: true
    }
  }
})

To know all available options, please check available features list where you will find references to all the plugins used.

Here are all available features:

• import
• customProperties
• calc
• customMedia
• mediaQueriesRange
• customSelectors
• colorFunction
• colorHexAlpha
• colorHwb
• colorRebeccapurple
• fontVariant
• filter
• autoprefixer

Note: order is important to get everything working correctly.

compress (default: false)

Allows you to compress the output (using CSSWring).

sourcemap (default: false)

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 an accurate sourcemap, please also use the from option.
• If you want more control on the sourcemap, please use the map option instead.

map (default: depends on sourcemap)

(default: undefined if sourcemap is false, inline if sourcemap it true)

If you want better control on sourcemap, you are at the right place. This is the postcss map option, so checkout the related documentation directly.

If you specify this option, sourcemap value will be ignored.

/!\ Using this option might changes the return value of cssnext() (object instead of css string if map is not inlined. The object will be like {css: "{css string}", map: {sourcemap object}})

from (default: null)

Source of the file. Required for accurate 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)

Some feature options

features.autoprefixer.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.

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

//eg
var output = cssnext(input, {
  features: {
    autoprefixer: {
      browsers: ["> 1%", "last 2 versions", "Firefox ESR"]
    }
  }
})

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

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

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

//eg
var output = cssnext(input, {
  features: {
    import: {
      path: ["src/stylesheets"]
    }
  }
})

Usage with other tools

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

• gulp-cssnext
• grunt-cssnext
• cssnext-loader (webpack)
• duo-cssnext
• cssnext-brunch
• broccoli-cssnext
• Prepros 5 (More options (dropdown) > Project options (item) > Compilers (tab) > Enable cssnext (checkbox at the bottom))
• @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 find 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

Add a feature

1. Add test files (input + expected output) in test/features,

• If the feature can affect some others, update test/cases/example.css to test integration with other features,
• Run test, & check tests are broken (otherwise feature is useless),
• Choose a pretty simple and clear name (that match the specs),
• Add the feature in the README features list (title, link to spec, link of the plugin, short desc),
• Add the feature in the README node.js options list (camelCaseName),
• Add the dependency in the package.json,
• Add the feature in the source (in index.js), in the appropriate place (order matter),
• Run test and be happy,
• Add feature on the playground example,
• Add feature on the website

Changelog

License

---

Acknowledgements

Huge thanks to all the people that where involved in :

• rework
• rework css parser
• myth
• autoprefixer
• postcss

Without all those people, this project would not exist.