Encapsulated styling for your javascript components with all the power of javascript and CSS combined.
Clone or download
danieljuhl Merge pull request #36 from alex3165/master
Add type declaration file for typescript
Latest commit c3fdd14 Nov 22, 2016
Permalink
Failed to load latest commit information.
dist make build Nov 21, 2016
lib lib: remove react as a dependency, and fork the utils used in react f… Nov 21, 2016
.babelrc chore: added babel-runtime Apr 15, 2016
.eslintrc chore: set ecmaVersion to 6 in .eslintrc Nov 21, 2016
.gitignore build: removed dist from .gitignore, to allow for installing from github Feb 21, 2016
.npmignore added npm ignore May 23, 2015
.travis.yml
CHANGELOG.md [docs] updated changelog with bugfix Jul 28, 2015
LICENSE change name in license Nov 21, 2016
Makefile deps: update babel and eslint; and make required changes to source code Apr 9, 2016
README.md Don't suggest using deprecated autoprefixer-core Mar 23, 2016
package.json make build and release Nov 22, 2016
stilr.d.ts

README.md

Stilr Build Status npm version

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 but should work with other libraries like Angular 2 or 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

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

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

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:

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.

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 (
      <button className={ buttonStyles }>
        { children }
      </button>
    );
}

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

import React from 'react';
import Button from './button';
import StyleSheet from 'stilr';

React.render(
  <Button type='primary' />,
  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:

@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

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.

import React from 'react';
import StyleSheet from 'stilr';
import App from '../your-app.js';

const css = StyleSheet.render();
const html = React.renderToStaticMarkup(<App />);

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

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(<App />, document.getElementById('root'));

React Hot Loader + Autoprefixer

If you're using React Hot Loader. Use the following approach in development to get hot loading styles and autoprefixer awesomeness.

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.

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