/cssnext

Use tomorrow's CSS syntax, today

Primary LanguageJavaScriptMIT LicenseMIT

cssnext Travis Build Status AppVeyor Build status Code Climate NPM version

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.

Is it cssnext or CSSNext or CSSnext?

The official name is cssnext, which should never be capitalized, especially not at the start of a sentence, unless it is being displayed in a location that is customarily all-caps (such as the title of man pages).

Why Features Limitations 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 you to use 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 the latest news & join #cssnext on irc.freenode.net if you have any questions.

Features

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. url() referenced are also rebased.
  • 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 at 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.

Limitations

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.

Font variant

font-variant are transformed to font-feature-settings. You might take a look at the support of font feature settings.

Filter

The W3C filters are only transformed as svg filter using the url(data:*) trick for Firefox < 35.

Installation

$ npm install cssnext

You can install it

Usage

You can use cssnext using CLI, as a JavaScript library, as a PostCSS plugin 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 its own API or as a PostCSS plugin.

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 an 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

browsers (default: browserslist default - > 1%, last 2 versions, Firefox ESR, Opera 12.1)

Allows you to specify your browser scope. This option enables or disables features according to caniuse database. This is the exact same option that you might know from Autoprefixer. Since cssnext includes Autoprefixer, the option is propagated.

See Browserslist queries syntax to adjust this option to your needs.

Note: if you don't specify this option, Browserslist will automatically try to find a browserslist config file or use its default value.

features (default: all features)

You should probably use browsers option instead of this one.

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

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

Each feature is based on PostCSS plugins & can get its 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 the available features list where you will find references to all the plugins used.

Here are all the available features:

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

Note: order is important to get everything working correctly.

import (default: true)

Allows you to inline local @import files (thanks to postcss-import):

  • you can refer to node_modules and web_modules packages
  • you can omit .css extension

Note: you can pass postcss-import options directly.

url (default: true)

By default, url() are rebased according to from (and to) option(s). This is convenient especially for @imported files.

Note: you can pass postcss-url options directly in order to inline or have more control over urls.

compress (default: false)

Allows you to compress the output (using CSSWring). You can enable minification by passing true or by providing an object containing CSSWring options.

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 change 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)

Usage with other tools

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

Note that you can also use cssnext as a PostCSS plugin.

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

People

The current lead maintainer is Maxime Thirouin. MoOx' Gratipay

See all contributors.

Acknowledgements

Huge thanks to all the people that where involved in:

Without all those people, this project would not exist.