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.

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 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 (⇗)
rem units (⇗)

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

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 to the support of font feature settings.

Filter

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

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, 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 it's 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 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

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

Allow you to specify your browser scope. This option enable or disable features according to caniuse database. This is the exact same option that you might know in Autoprefixer. Since cssnext includes Autoprefixer, the option is propagated.

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

Note: if you don't specify this option, Browserslist will automatically try to find 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 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:

customProperties
calc
customMedia
mediaQueriesRange
customSelectors
colorFunction
colorHexAlpha
colorHwb
colorRebeccapurple
fontVariant
filter
rem
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 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)

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

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

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

willcode2surf / cssnext Goto Github PK

cssnext's Introduction

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

cssnext's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org

Jobs

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