Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kodyl/stilr

Encapsulated styling for your javascript components with all the power of javascript and CSS combined.
https://github.com/kodyl/stilr

Last synced: about 2 months ago
JSON representation

Encapsulated styling for your javascript components with all the power of javascript and CSS combined.

Awesome Lists containing this project

README 

        
# Stilr [![Build Status](https://travis-ci.org/kodyl/stilr.svg)](https://travis-ci.org/kodyl/stilr) [![npm version](https://badge.fury.io/js/stilr.svg)](http://badge.fury.io/js/stilr)



Encapsulated styling for your javascript components with all the power of

javascript and CSS combined.



- Unique class names (Content Hash Based)

- Useable on the server

- Allows nested pseudo selectors

- Allows nested media queries

- No namespacing / Class name collisions.

- Plays nicely with React Hot Loader and autoprefixer.



...oh, and did I mention you get duplicate style elimination for free?



__Note__: This library fits really nice with [React](https://facebook.github.io/react/) but should work with other libraries like [Angular 2](https://angular.io/) or [Deku](https://github.com/dekujs/deku)



## API



#### `object StyleSheet.create(object spec)`

Stilr extracts the styles from the style object and returns an object with the

same keys mapped to class names.



__Example__

```javascript

import StyleSheet from 'stilr';



const palm = '@media screen and (max-width:600px)';



const styles = StyleSheet.create({

  container: {

    color: '#fff',

    ':hover': {                 // Pseudo Selectors are allowed

      color: '#000'

    },

    [palm]: {                   // Media Queries are allowed

      fontSize: 16,

      ':hover': {

        color: 'blue'  		// Pseudo selectors inside media queries.

      }

    }

  }

});



console.log(styles.container);  // => '_xsrhhm' -- (The class name for this style.)

```



#### `string StyleSheet.render()`

Stilr outputs the contents of its internal stylesheet as a string of css



__Example__

```javascript

import StyleSheet from 'stilr';



StyleSheet.create({

  container: {

    color: '#fff'

  }

});



const CSS = StyleSheet.render();



console.log(CSS);             // => '._yiw79c{color:#fff;}'

```



#### `bool StyleSheet.clear()`

Clear Stilr internal stylesheet



__Example__

```javascript

import StyleSheet from 'stilr';



const styles = StyleSheet.create({

  container: {

    color: '#fff'

  }

});



StyleSheet.clear();



const CSS = StyleSheet.render();



console.log(CSS);             // => ''

```



## Examples



#### Basic Button Component Example.

Let's start of by creating our styles. If you have ever used React Native, this

will be familiar to you:



```javascript

import StyleSheet from 'stilr';

import { palm } from './breakpoints';

import { color, font } from './theme';



const styles = StyleSheet.create({

  base: {

    transition: 'background-color .25s',

    borderRadius: 2,

    textAlign: 'center',

    fontSize: 20,

    padding: 6,

    color: '#fff',

    border: `${ color.border } 1px solid`,

    [palm]: {

      fontSize: 18

    }

  },

  primary: {

    backgroundColor: color.primary,

    ':hover': {

      color: 'tomato'

    }

  },

  secondary: {

    backgroundColor: 'tomato',

    color: '#eee'

  }

});

```



Stilr will now generate a set of class names based on the content of your styles

and return an object with the same keys mapped to those classes.



Note that you're able to use pseudo selectors and media queries.

Pseudo selectors are written like you normally would in CSS, e.g.: `:hover`, `:active`,

`:before` etc.

Media queries are the same, e.g. `palm` in the example is just a string: `@media screen and (max-width:600px)`. Any valid media query is allowed.



Since we just have a bunch of class names now, we can use these in our React

Component.



```javascript

import React, { PropTypes } from 'react';



class Button extends React.Component {

  static propTypes = {

    type: PropTypes.oneOf(['primary', 'secondary'])

  }



  render() {

    const { type, children } = this.props;

    const buttonStyles = [

      styles.base,

      styles[ type ]

    ].join(' ');



    return (

      

        { children }

      

    );

}

```



Next up, let's render our css and mount our app:



```javascript

import React from 'react';

import Button from './button';

import StyleSheet from 'stilr';



React.render(

  ,

  document.getElementById('root')

);



document.getElementById('stylesheet').textContent = StyleSheet.render();

```



This step could also have been done on the server. Since StyleSheet.render just

returns a string of css. In our case, it would look something like this in a

prettified version:

```css

@media screen and (max-width:600px) {

  ._82uwp6 {

    font-size: 18px;

  }

}



._82uwp6 {

  transition: background-color .25s;

  border-radius: 2px;

  text-align: center;

  font-size: 20px;

  padding: 6px;

  color: #fff;

  border: #fff 1px solid;

}



._11jt6vs:hover {

  color: tomato;

}



._11jt6vs {

  background-color: red;

}



._1f4wq27 {

  background-color: tomato;

  color: #eee;

}

```



In case you were wondering: Yes, this would would be an ideal place to add something like autoprefixer, minification etc.



## Duplicate Style Elimation

```javascript

import StyleSheet from 'stilr';



const styles = StyleSheet.create({

  same: {

    fontSize: 18,

    color: '#000'

  },

  sameSame: {

    fontSize: 18,

    color: '#000'

  }

});



console.log( styles.same );        => '_1v3qejj'

console.log( styles.sameSame );    => '_1v3qejj'

```



...magic.



Under the hood, stilr creates class names based on a content hash of your style object

which means that when the content is the same, the same hash will always be

returned. 



## Extracting your styles.



#### Server

If you do serverside rendering, you should be able to extract your styles right after you load your app.



```javascript

import React from 'react';

import StyleSheet from 'stilr';

import App from '../your-app.js';



const css = StyleSheet.render();

const html = React.renderToStaticMarkup();



// Extract css to a file or insert it in a file at the top of your html document

```

Apply autoprefixer here, or other preprocess goodness here. 

If you're really fancy, you only do the required autoprefixes based on the user agent.



### Development

When working with Stilr in development, the preferred way to extract styles would be the following way, just before you initialize your app.



```javascript

import App from '../app';

import React from 'react';

import StyleSheet from 'stilr';



let stylesheet = document.createElement('style');

stylesheet.textContent = StyleSheet.render();

document.head.appendChild(stylesheet);



React.render(, document.getElementById('root'));

```



### React Hot Loader + Autoprefixer

If you're using [React Hot Loader](https://github.com/gaearon/react-hot-loader). Use the following approach in development to get hot loading styles and autoprefixer awesomeness.



```javascript

import React from 'react';

import StyleSheet from 'stilr';

import autoprefixer from 'autoprefixer';

import postcss from 'postcss';



// Make sure you have a style element with the ID: 'stylesheet' in your html.

const stylesheet = document.getElementById('stylesheet');



class App extends React.Component {

   render() {

     if (process.env !== 'production') {

       const prefixedCSS = postcss(autoprefixer()).process( StyleSheet.render() ).css;

       stylesheet.textContent = prefixedCSS;

     }

     

     return (

        ...snip...

     );

   }

}

```

If you're using Webpack, you have to add `node: { fs: 'empty' }` to your config file. Otherwise autoprefixer will throw an error when trying to use it on the client.



#### Production



##### Makefile

Add this as a build step in your makefile.

```Makefile

extract-styles:

	@node -p "require('babel/register')({ignore: false}); var s = require('stilr'); require('./your-app.js'); s.render()" > ./bundle.css

```



The following snippet can also be executed anywhere to extract the styles.

Remember to replace `./your-app.js` with the entry file of your app.

`node -p "require('babel/register')({ignore: false}); var s = require('stilr'); require('./your-app.js')`



## TODO:

- [ ] Remove React as a dependency

- [ ] More examples