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.
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 / Limitation / Installation / CLI Usage / Node.js API / Contribute
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.
- automatic vendor prefixes (⇗),
- custom properties &
var()
(⇗) limited to:root
, - reduced
calc()
(⇗) to optimize previously parsedvar()
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 tohsl()
but easier for humans to work with,gray()
(⇗),- #rrggbbaa (⇗),
rebeccapurple
(⇗),- font-variant properties (⇗),
- filter properties (⇗)
The features below are considered as bonus since it's totally not related to CSS specs.
@import
inline local files and modules -node_modules
orweb_modules
(⇗) to output a bundled CSS file.- minification is available (⇗) if you want to compress the output for production.
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.
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.
$ 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
You can use cssnext using CLI, as a JavaScript library or through others tools.
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
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
cssnext can be used with it's own API
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.
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)
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.
Allows you to compress the output (using CSSWring).
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.
(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}})
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)
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"]
}
}
})
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"]
}
}
})
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
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 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
The current lead maintainer is Maxime Thirouin
See all contributors
Huge thanks to all the people that where involved in :
Without all those people, this project would not exist.