:sparkles: Modular, scoped CSS with ES6

Ryan Tsao

Last update: Nov 18, 2022

Related tags

Overview

CSJS allows you to write modular, scoped CSS with valid JavaScript.

Features

Extremely simple and lightweight
- Zero dependencies, ~2KB minified and gzipped
Leverages native ES6 and CSS features ⁽¹⁾ rather than reinventing the wheel
- Seamless modular, scoped styles with explicit dependencies powered by CommonJS/ES6 modules
- Dead-simple variables/mixins using tagged ES6 template strings
- Style composition with optimal reuse via natural class composition mechanics already in CSS/HTML⁽²⁾
Works tooling-free; no required transpilation/compilation/build steps ⁽³⁾
Framework-agnostic (No React dependency; works with Web Components, etc.)
Fully supported native CSS media queries, pseudo-classes, keyframe animations, etc.
Server-rendered/universal JavaScript support

Quick Example

(Live editable codepen.io demo)

const csjs = require('csjs');
const {div, h1} = require('react').DOM;

const green = '#33aa22';

const styles = csjs`

  .panel {
    border: 1px solid black;
    background-color: ${green};
  }

  .title {
    padding: 4px;
    font-size: 15px;
  }

`;

const html = require('react-dom/server').renderToStaticMarkup(
  div({className: styles.panel}, [ 
    h1({className: styles.title}, 'Hello World!')
  ])
);
/*
<div class="panel_4Eda43">
  <h1 class="title_4Eda43">Hello World!</h1>
</div>
*/

const css = csjs.getCss(styles);
/*
.panel_4Eda43 {
  border: 1px solid black;
  background-color: #33aa22;
}

.title_4Eda43 {
  padding: 4px;
  font-size: 15px;
}
*/

Simple, tooling-free

CSJS runs in ES6 environments without transpilation, compilation, or build steps (including Node 4+ and latest stable Chrome/Firefox/Safari/Edge).

Of course, you can always transpile ES6 template strings using Babel, allowing you to use CSJS in any ES5 environment.

Framework-agnostic

CSJS works with any framework, be it React, native Web Components, or something else.

Full power of JavaScript in your CSS

Real, full-fledged JavaScript
Obviates the need for Sass/Less or other preprocessors
Proper imports/require
Real variables, functions, loops, etc.
As extensible as JavaScript itself

Class Composition Syntax

CSJS also features class composition that works like CSS Modules:

(Live editable codepen.io demo)

common-styles.js

const csjs = require('csjs');

module.exports = csjs`

  .border {
    border: 1px solid black;
  }

  .italic {
    font-family: serif;
    font-style: italic;
  }

`;

quote-styles.js

const csjs = require('csjs');

const common = require('./common-styles');

module.exports = csjs`

  .blockQuote extends ${common.italic} {
    background: #ccc;
    padding: 8px;
    border-radius: 4px;
  }

  .pullQuote extends .blockQuote, ${common.border} {
    background: #eee;
    font-weight: bold;
  }

`;

app.js

const getCss = require('csjs/get-css');
const commonStyles = require('./common-styles');
const quoteStyles = require('./quote-styles');

quoteStyles.blockQuote;
// => "blockQuote_2bVd7K italic_3YGtO7"

quoteStyles.pullQuote;
// => "pullQuote_2bVd7K blockQuote_2bVd7K italic_3YGtO7 border_3YGtO7"

getCss(quoteStyles);
/*
.blockQuote_2bVd7K {
  background: #ccc;
  padding: 8px;
  border-radius: 4px;
}

.pullQuote_2bVd7K {
  background: #eee;
  font-weight: bold;
}
*/

getCss(commonStyles);
/*
.border_3YGtO7 {
  border: 1px solid black;
}

.italic_3YGtO7 {
  font-family: serif;
  font-style: italic;
}
*/

Optional tooling

Extracted static CSS bundles

csjs-extractify is a browserify plugin that allows you to extract your application's CSJS into a static CSS file at build time.

Automatic CSS injection

csjs-injectify is a browserify transform that automatically replaces csjs with csjs-inject, which automatically injects your scoped CSS into the <head> at runtime. It is recommended to use this rather than the csjs-inject module directly.

PostCSS

babel-plugin-csjs-postcss is a Babel plugin that allows you to run PostCSS on the CSS contained within CSJS template string literals at build time. Works with plugins such as Autoprefixer.

Syntax highlighting

neurosnap has created an Atom plugin for syntax highlighting CSS within CSJS tagged template strings.

FAQ

Why the name CSJS?

CSJS is 100% valid JavaScript, hence the name Cascading Style JavaScripts.

Why not Sass?

Sass doesn't provide any way to scope CSS, thus encapsulation of styles in components isn't possible with Sass alone. Additionally, because Sass was designed for use in a global CSS namespace, many of its features just don't make sense when styles are scoped and encapsulated in components. @extend in Sass is extremely problematic, whereas CSJS has a proper mechanism for class composition that actually works like it should. Furthermore, with CSJS, you have the ability to use real JavaScript in CSS, which is significantly more powerful and extensible than the language features included in Sass, so there's not really any reason to use Sass at all.

Why not CSS Modules?

CSJS was inspired by CSS Modules and they are virtually identical in concept. However, unlike CSS Modules which attempts to reproduce an ES6-style module system into CSS itself, CSJS simply uses native JS modules. CSJS also uses normal JS variables whereas CSS Modules invents its own CSS variable syntax.

Consquently, CSJS is merely plain JavaScript and works without any extra tooling (CSS Modules is not valid CSS). Furthermore, because CSJS is essentially an amalgamation of plain JavaScript and plain CSS, there's no any new syntax or semantics to learn (besides the optional composition syntactic sugar, which closely mimicks ES6 classes).

Why not Radium?

Inline styles are cool, but there are limitations to using pure inline styles. For example, CSS pseudo-classes and media queries aren't possible with inline styles. This is the premise behind Radium, which works around this by re-implementing these CSS features using JavaScript.

Whereas Radium is wholly dependent on React and involves performance trade-offs in its JavaScript implementations of CSS features, CSJS works regardless of framework (or lack thereof) and allows for the use of all CSS features natively (including media queries and pseudo-classes).

License

MIT

Comments

Performance of "extends" regex
Current way of parsing extends is way too slow. It takes up most of my (small) app's load time. Here is a screenshot from Chrome's Timeline. Looks like it takes 95%+ of the whole script eval.

Wrapping regex parse in

if (css.indexOf('extends') > 0) { while (found = regex.exec(css)) { matches.unshift(found); } }

reduced page load time by about 1.3 seconds. I tried removing every single extends from my scss, it doesn't really matter, the pattern is just slow by itself.
opened by mkazlauskas 7
Extends syntax conflicts with selector grouping
I love how standard css seems to "just work" with csjs but I've noticed an ambiguity surrounding the extends syntax and css selector grouping, due to the use of commas to separate both selectors and extend targets.

.styleA, .styleB { background: red; } .styleA extends .baseStyle, .styleB { background: red; }
enhancement question
opened by sambs 6
autoprefixer?
tl;dr are there plans to support autoprefixer or do you suggest a seperate module that can be combined with csjs to achieve this?

Maybe there is a smart way to just add the vendor prefixes necessary by the current browser. I bookmarked two related projects:

https://github.com/LeaVerou/prefixfree

https://github.com/jsstyles/css-vendor

Wow, I just revisted https://github.com/MicheleBertoli/css-in-js to check if there are any new projects and stumbled across yours :-) Currently I'm using jss because even though it seems a bit big and clunky it has support for all the featuers and comes with a css2jss thing that i used to translate css written in an es6 template string into jss. It kind of works, but this project of yours looks very very promising and seems to be the only one that goes straight for es6 templates which i feel are the way to go, because javascript objects are too clunky to really write css with them. But in real world projects it's pretty important to have some kind of autoprefixer working, otherwise what i save in work using this very awesome css-in-js technique, i pay by manually prefixing all the things with the appropriate vendor prefixes...
question
opened by serapath 5
Cannot use `style.css_class_name` syntax directly with React 15.3.1

Warning: Failed prop type: Invalid prop className of type object supplied to ActiveComponent, expected string.

Have to type style.css_class_name + '' all the time...

I understand that that's some kind of React's limitations, because the object generated from csjs string has toString() method and should be treated by React as real string too.

What I doing wrong because I can't find the same issues from other people?
enhancement

opened by avesus 4
Added unscoped mode

So this is my attempt at a no-scope option. It is very similar to #31 but I tried to remove any unnecessary code for the no-scope options.

As you can see I also duplicated all the tests for the no-scope option.

I also made the csjsTemplate parameter an object so it can be a little easier to configure down the road.

Let me know what you think. Thanks.

opened by neurosnap 4
Support for more browsers

Object.assign() is not supported even in IE11 and in iOS 7 and 8 (I know they are very buggy but they exist yet). https://github.com/rtsao/csjs/blob/695d7820f61e7c6bae6b264f8bde3b8e444289dc/lib/csjs.js#L27

Please, rewrite that into something more supported.

opened by avesus 4

:not(selector) expand error?

Hi.I wrote the following style with csjs v.1.0.3

module.exports = csjs`
@media screen and (min-width: 769px) {
  .columns:not(.is-desktop) {
    display: -webkit-box;
    display: -webkit-flex;
    display: -ms-flexbox;
    display: flex;
  }
}
`

But it is expanded as follows

module.exports = csjs`
@media screen and (min-width: 769px) {
  .columns_2B2Wm:not(.is-desktop)_2B2Wm {
    display: -webkit-box;
    display: -webkit-flex;
    display: -ms-flexbox;
    display: flex;
  }
}
`

bug

opened by bokuweb 4

How should I write to apply multiple classname?

How should I write to apply multiple classname? I want to apply multi classname to single element.

style.js

module.exports = csjs`
    .foo  {
      font-size: '20px';
    }

    .bar {
      color: red;
    }

app.js

import React, { Component, PropTypes } from 'react';
import csjs from 'csjs';
import styles from './styles';
import insertCss from 'insert-css';

insertCss(csjs.getCss(styles));

export default class Foo extends Component {
  render() {
    return (
      <div className={styles.foo styles.bar}>
        { this.props.children }
      </div>
    );
  }
}

question

opened by bokuweb 4

Use simple lexical analysis instead of regex
See: https://github.com/rtsao/csjs/issues/39

This is a pretty significant refactor. Scoping is now based on tokenization, which based on early benchmarks, should speed things up significantly. Lexer is based on the lexer from https://github.com/brettstimmerman/mensch but modified to be faster and avoid doing work we don't need for CSJS

Remaining items:

[x] Add back compositions

[x] Pass test suite

[ ] Do benchmarking

This would also be an opportunity to do something like: https://github.com/rtsao/csjs/issues/34 and https://github.com/rtsao/csjs/issues/25
opened by rtsao 3
Fix for similar animation names
When creating this library I noticed that some of the similar animation names were incorrect.

For instance, if we had animations named bounce, bounceIn, bounceInDown it would result in:

animation-name: bounceIn_3YDk0BDown;

instead of:

animation-name: bounceInDown_3YDk0B;

This PR makes it check more explicitly for the animation name. Thanks!
opened by shama 3
Is there any way to compress string literals?

This project has been perfect so far, i can't believe it solves pretty much all the major issues with React and styles.

The only gripe left is that the minified endbuild has lots of needless holes in it taking space due to the string literals. And since postCSS/cssnano doesn't work with babel-plugin-csjs-postcss there's no obvious solution.

Is there any alternative to compress it?
question

opened by drcmda 2

Scoped multi-valued animations

Hi, I have a problem with scoped, multi-valued animations. Looks like it doesn't work as expected for me. For example the following code

  .foo {
    animation: keyframe-1 1s ease-in-out, keyframe-2 .5s linear;
  }
  
  .bar {
    animation-name: keyframe-1, keyframe-2;
  }
  
  @keyframes keyframe-1 {}
  @keyframes keyframe-2 {}

will result in

.foo_4y20Hz {
  animation: keyframe-1 1s ease-in-out, keyframe-2_4y20Hz .5s linear;
}
.bar_4y20Hz {
  animation-name: keyframe-1, keyframe-2_4y20Hz;
}
@keyframes keyframe-1_4y20Hz {}
@keyframes keyframe-2_4y20Hz {}

Only the last animation-name is prefixed within a declaration value.

opened by msn0 0

"observables" in csjs
I just saw #61 and I like that #15 might be supported.

Do I understand correctly, that #61 might add some kind of runtime css parsing?

I'm not sure if necessary, but I was thinking, maybe some kind of runtime css parsing could help to add some form of "observable" primitiv, so that a css property would be auto-updated, whenever the observable variable changes.

The idea would be, that - maybe similar to a minimal version of styletron , every part of the stylesheet that uses an "observable" is put into a <style> tag that is as minimal as possible and internally, csjs subscribes generated functions to changes of all "observables" to update those <style> tags.

example:

function o (value) { // or something else var subscribers = [] return function variable (val) { if (typeof val === 'function') subscribers.push(val) else if (val === undefined) return value else (value = val, subscribers.forEach(fn => fn(value))) } } var color = 'red' var color$ = o() color$(function(x){ // observe the value console.log('color$ changed to', x) }) color$('green') //set the value color$() //get the value - e.g. can be used when initializing css var css = csjs` .title { color: ${color}; background-color: ${color$}; } ` color$('blue') // update the value
opened by serapath 0
Status of CSJS?

Hello @rtsao I just wanted to check in and see what the general plan and direction for CSJS is. We've noticed that it's been some time since the last release and there hasn't been any major new additions or developments into CSJS itself for some time.

Asking mainly from the perspective of react-csjs, one of the options we've have been looking into is shipping CSJS internally along with that package to make things like automatically including extended styles a bit easier (since we can wrap the CSJS instance in a singleton and control that interface for the user) just to name an example. There's a handful of other things we're thinking about for the future of react-csjs that this combination would enable.

@wKovacs64 @drcmda and I would like to get your thoughts and see if you think this makes sense, etc.

opened by tizmagik 1

Linting

Would it make sense to standardize on a particular code style to make contribution easier? Here are results from running semistandard on master.

csjs|master ⇒ ./node_modules/.bin/semistandard | wc -l
semistandard: Semicolons For All! (https://github.com/Flet/semistandard)
semistandard: Run `semistandard --fix` to automatically fix some problems.
      69

csjs|master ⇒ ./node_modules/.bin/semistandard        
semistandard: Semicolons For All! (https://github.com/Flet/semistandard)
semistandard: Run `semistandard --fix` to automatically fix some problems.
  /Users/scott/Documents/sites/csjs/lib/base62-encode.js:10:33: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:5:40: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:6:60: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:12:53: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:17:43: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:25:2: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:27:23: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:28:3: Split initialized 'var' declarations into multiple statements.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:30:20: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/build-exports.js:31:45: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:15:25: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:37:37: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:45:22: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:60:23: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:64:27: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:65:32: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:67:38: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/composition.js:78:21: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:12:39: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:16:30: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:18:9: 'values' is already defined.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:45:4: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:46:2: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:53:21: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:63:16: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:64:30: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:75:17: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/csjs.js:76:42: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:3:5: 'makeComposition' is defined but never used.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:7:41: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:8:3: Split initialized 'var' declarations into multiple statements.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:9:10: Expected a conditional expression and instead saw an assignment.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:13:31: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:21:41: Strings must use singlequote.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:25:37: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:42:1: Block must not be padded by blank lines.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:44:18: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/css-extract-extends.js:48:22: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/extract-exports.js:10:24: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/extract-exports.js:18:19: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/extract-exports.js:21:3: Expected space(s) after "while".
  /Users/scott/Documents/sites/csjs/lib/get-css.js:5:33: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/hash-string.js:8:34: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/hash-string.js:13:45: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/regex.js:13:33: Unexpected trailing comma.
  /Users/scott/Documents/sites/csjs/lib/replace-animations.js:5:27: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/replace-animations.js:6:65: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/replace-animations.js:14:8: '+' should be placed at the end of the line.
  /Users/scott/Documents/sites/csjs/lib/replace-animations.js:17:54: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/replace-animations.js:25:6: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/scoped-name.js:6:37: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/scoped-name.js:9:29: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/scoped-name.js:11:4: Missing semicolon.
  /Users/scott/Documents/sites/csjs/lib/scopeify.js:11:17: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/scopeify.js:18:20: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/lib/scopeify.js:20:23: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:34:23: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:40:22: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:45:17: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:46:34: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:53:21: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:64:4: Missing semicolon.
  /Users/scott/Documents/sites/csjs/test/index.js:67:10: 'moduleExists' is defined but never used.
  /Users/scott/Documents/sites/csjs/test/index.js:67:22: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:70:5: Expected space(s) after "catch".
  /Users/scott/Documents/sites/csjs/test/index.js:75:10: 'fixturePath' is defined but never used.
  /Users/scott/Documents/sites/csjs/test/index.js:75:21: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:79:23: Missing space before function parentheses.
  /Users/scott/Documents/sites/csjs/test/index.js:80:42: Missing space before function parentheses.

opened by scott113341 1

Document syntax highlighting/IDE integration options
Related:

https://github.com/rtsao/csjs/issues/45

https://github.com/rtsao/csjs/issues/35

https://github.com/neurosnap/autocomplete-csjs

https://github.com/neurosnap/language-csjs/

documentation
opened by rtsao 0