stylis

What is stylis?

The stylis npm package is a lightweight CSS preprocessor that allows developers to write nested CSS, use mixins, and perform other transformations before the CSS is compiled. It is particularly designed to be used with CSS-in-JS libraries and offers a middleware architecture to extend its capabilities.

What are stylis's main functionalities?

CSS Preprocessing

Stylis allows you to write nested CSS rules, which it will then flatten into valid CSS. The code sample demonstrates how to preprocess a nested CSS string.

const stylis = require('stylis');

const css = `
  .parent {
    color: red;
    .child {
      color: blue;
    }
  }
`;

const output = stylis('.parent', css);
console.log(output);

Prefixing

Stylis automatically adds vendor prefixes to CSS rules when necessary. The code sample shows how to automatically prefix the 'display: flex;' rule.

const stylis = require('stylis');

const css = `display: flex;`;

const output = stylis('', css);
console.log(output);

Middleware

Stylis supports middleware, allowing you to intercept and transform CSS at various stages of processing. The code sample demonstrates a middleware that changes the color property for elements with the class '.button'.

const stylis = require('stylis');

stylis.use((context, content, selectors, parents, line, column, length) => {
  if (context === 2 && selectors[0] === '.button') {
    return content.replace('color: red', 'color: blue');
  }
});

const css = `.button { color: red; }`;

const output = stylis('', css);
console.log(output);

Other packages similar to stylis

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. It is more established and has a larger ecosystem of plugins compared to stylis. PostCSS can be used for a wide range of tasks including linting, optimization, and applying polyfills.

sass

Sass is a mature and feature-rich CSS extension language that allows for variables, nesting, mixins, and more. Unlike stylis, Sass has its own syntax and requires compilation to CSS, but it offers a more comprehensive set of features for styling.

less

Less is another CSS pre-processor that extends the capabilities of CSS with variables, mixins, functions, and more. It is similar to Sass and offers a different syntax and feature set compared to stylis.

README

Stylis

• ~2Kb minified+gzipped

Supports

• Edge
• IE 9+
• Chrome
• Firefox
• Safari
• Node.js

---

Installation

direct download

<script src=stylis.min.js></script>

CDN

<script src=https://unpkg.com/stylis@0.11.1/stylis.min.js></script>

npm

npm install stylis --save

Features

• variables via ~~foo and var(~~foo)
• web component emulation of :host, :host() and :host-context()
• inline global injection via :global(selector)
• block level global injection via @global {}
• nesting a { &:hover {} }
• static and function mixins via @mixin ... and @include
• prefixer
• namespacing
• flat css color: red; h1 { color: red; }
• middleware support
• keyframes and animation namespacing (with the option to disable)
• including an option to disable compact features like variables and mixins.

---

Stylis is a small css compiler that turns this

stylis('#user', styles);

Where styles is the following css

// variables
~~foo: 20px;

// flat css
font-size: 2em;
font-family: sans-serif;
width: var(~~foo);

// emulation for shadow dom selectors
:host {
    color: red;
}

:host(.fancy) {
    color: red;
}

:host-context(body) {
    color: red;
}

// removes line comment

.name {
    transform: rotate(30deg);
}

// inject to global scope block
@global {
    body {
        background: yellow;
    }
}

// inject to global scope inline
span, h1, :global(h2) {
	color:red;

	/**
	 * removes block comments
	 */
}

// prefixing
& {
	animation: slidein 3s ease infinite;
    display: flex;
    flex: 1;
    user-select: none;
}

// namespaced animations
&:before {
	animation: slidein 3s ease infinite;	
}

// namespaced keyframes
@keyframes slidein {
	from { transform: translate(10px); }
	to { transform: translate(200px); }
}

// flat namespaced css in @media
@media (max-width: 600px) {
    display: block;

	&, h1 { 
        appearance: none; 
    }
}

// nesting
h1 {
    color: red;

    h2 {
        display: block;

        h3, &:hover {
            color: blue;
        }
    }

    font-size: 12px;
}

// static mixins
@mixin large-text {
    font-size: 20px;
}

// function mixins
@mixin linx (link, visit, hover, active) {
    a {
        color: var(~~link);
        &:hover {
          color: var(~~hover);   
        }
    }
}

// use static mixins
& {
    @include large-text;
}

// use function mixins
@include linx(white, blue, green, red);

into this (minus the whitespace)

#user {
	font-size: 2em;
	font-family: sans-serif;
    width: 20px;
}
#user {
    color: red;
}
#user.fancy {
    color: red;
}
body #user {
    color: red;
}
#user .name {
    -webkit-transform: rotate(30deg);
    -ms-transform: rotate(30deg);
    transform: rotate(30deg);
}
body {
    background: yellow;
}
#user span,
#user h1,
h2 {
    color: red;
}
#user {
    display: -webkit-flex;
    display: flex;

    -webkit-flex: 1;
    -moz-flex: 1;
    flex: 1;

    -webkit-user-select: none;
    -moz-user-select: none;
    -ms-user-select: none;
    user-select: none;

    -webkit-animation: userslidein 3s ease infinite;
    animation: userslidein 3s ease infinite;
}
#user:before {
    -webkit-animation: userslidein 3s ease infinite;
    animation: userslidein 3s ease infinite;
}
@-webkit-keyframes userslidein {
    from {
        -webkit-transform: translate(10px);
        -ms-transform: translate(10px);
        transform: translate(10px);
    }
    to {
        -webkit-transform: translate(200px);
        -ms-transform: translate(200px);
        transform: translate(200px);
    }
}
@keyframes userslidein {
    from {
        -webkit-transform: translate(10px);
        -ms-transform: translate(10px);
        transform: translate(10px);
    }
    to {
        -webkit-transform: translate(200px);
        -ms-transform: translate(200px);
        transform: translate(200px);
    }
}
@media (max-width: 600px) {
    #user, #user h1 {
        -webkit-appearance: none;
        -moz-appearance: none;
        appearance: none;
    }

    #user {
        display: block;
    }
}

#user h1 {
    color: red;
    font-size: 12px;
}

#user h1 h2 {
    display: block;
}

#user h1 h2 h3,
#user h1 h2 h2:hover {
    color: blue;
}

#user {
    font-size: 20px;
}

#user a {
    color: white;
    &:hover {
      color: green;   
    }
}

API

stylis(
    selector: {string},     // selector - i.e `.class` or `#id` or `[attr=id]`
    styles: {string},       // css string
    animations: {boolean=}  // false to prevent prefixing animations, true by default
    compact: {boolean=}     // enable additional features (mixins, variables)
    middleware: {function=}
);

Middleware

The optional middleware function accepts four arguments ctx, str, line, column, the middleware is executed at 4 stages.

1. at every selector declaration ctx = 0 i.e .class / .foo, .bar
2. at every property declaration ctx = 1 i.e color: red;
3. before a block of compiled css is added to the output string ctx = 2, i.e .class {color:red;}
4. before a block of flat compiled css is added to the output string ctx = 3, i.e color:blue;
5. When an import statement is found ctx = 4, i.e import 'foo'
6. before the compiled css output is returned ctx = 5

If you wanted to you could parse import statements in the middleware and return the imported file, stylis will then insert the content of it into the css that it later parse/compile. The str value on import context is the file name i.e foo or foo.scss or multiple files foo, bar.

If at any context point the middleware returns a non-falsey value the token or block of css will be replaced with the return value. For example we can add a feature random() that when used prints a random number.

stylis(``, `h1 { width: calc(random()*10); }`, false, function (ctx, str, line, column) {
    switch (ctx) {
        // str will be `width: calc(random()*10);`
        case 1: return str.replace(/random\(\)/g, Math.random());
    }
});

Will replace all instances of random() with a random number.

Extending css syntax with function

As you can tell from the above middleware it is possible to extend css's syntax. In the previous example we used a function as middleware which allows for much lower level access and control but we could as well use an object of functions that define what different function in the css will generate. For example a random() and darken(value) extension can look like

stylis(``, `
        h1 { 
            width: calc(random()*10); 
            color: darken(#FFF);
        }
`, false, {
    random () {
        return Math.random();
    }
    darken (value) {
        return '#000';
    }
});

If we had used darken(#FFF, #CCC) in our css the two arguments would have been passed to the darken function.

Intergration

You can use stylis to build an abstraction ontop of, for example imagine we want to build an abstract that makes the following React Component possible

class Heading extends React.Component {
    stylesheet(){
        return `
            &{
                color: blue
            }
        `;
    }
    render() {
        return (
            React.createElement('h1', 'Hello World')
        );
    }
}

We could simply extend the Component class as follows

React.Component.prototype.stylis = function (self) {
    var namespace = this.displayName;

    return function () {
        stylis(namespace, self.stylesheet(), document.head);
        mounted = true;
        this.setAttribute(namespace);
    }
}

Then use it in the following way

class Heading extends React.Component {
    stylesheet(){
        return `
            &{
                color: blue
            }
        `;
    }
    render() {
        return (
            React.createElement('h1', {ref: this.stylis(self)}, 'Hello World')
        );
    }
}

When the first instance of the component is mounted the function assigned to the ref will get executed adding a style element with the compiled output of stylesheet() where as only the namespace attribute is added to any subsequent instances.

You can of course do this another way

class Heading extends React.Component {
    constructor (props) {
        super(props);
        // or you can even inline this
        this.style = React.createElement('style', {id: this.displayName}, this.stylesheet());
    }
    stylesheet(){
        return `
            &{
                color: blue
            }
        `;
    }
    render() {
        return (
            React.createElement('h1', null, 'Hello World', this.style)
        );
    }
}

One will add it to the head another will render it in place with the component.

If you want a better picture into what can be done, there is an abstraction i created for dio.js that does away with the above boilerplate entirely http://jsbin.com/mozefe/1/edit?js,output