loliver / treat

:candy: Themeable, statically extracted CSS‑in‑JS with near‑zero runtime.

Themeable, statically extracted CSS‑in‑JS with near‑zero runtime.

Write your styles in JavaScript/TypeScript within treat files (e.g. Button.treat.js) that get executed at build time.

All CSS rules are created ahead of time, so the runtime is very lightweight—only needing to swap out pre-existing classes. In fact, if your application doesn’t use theming, you don’t even need the runtime at all.

All CSS logic, including its dependencies, will not be included in your final bundle.

Because theming is achieved by generating multiple classes, legacy browsers are supported.

Documentation

See the documentation at seek-oss.github.io/treat for more information about using treat.

Requirements

Your project must be using webpack with the supplied webpack plugin, but that’s it.

First-class support is provided for React and TypeScript, but those layers are entirely optional. The core runtime API can be integrated into other frameworks, if needed.

The runtime makes use of Map, so you may need a polyfill for pre-ES2015 browsers.

Basic usage

First, install the core libary.

$ yarn add treat

Then, add the webpack plugin to your project. In this case, we’re using mini-css-extract-plugin to generate a static CSS file.

const { TreatPlugin } = require('treat/webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  plugins: [
    new TreatPlugin({
      outputLoaders: [MiniCssExtractPlugin.loader]
    }),
    new MiniCssExtractPlugin()
  ]
};

Next, define and export styles from a treat file.

// Button.treat.js
// ** THIS CODE WON'T END UP IN YOUR BUNDLE! **
import { style } from 'treat';

export const button = style({
  backgroundColor: 'blue',
  height: 48
});

Finally, import the styles.

// Button.js
import * as styles from './Button.treat.js';

export const Button = ({ text }) => `
  <button class="${styles.button}">${text}</button>
`;

Themed usage

This themed usage example makes use of react-treat to keep things simple. React is not required to use treat.

First, install react-treat.

$ yarn add react-treat

Assuming you’ve already set up the webpack plugin, start by creating and exporting a theme from a treat file. Normally, you’d define multiple themes, but let’s keep it short.

// theme.treat.js
// ** THIS CODE WON'T END UP IN YOUR BUNDLE! **
import { createTheme } from 'treat';

export default createTheme({
  brandColor: 'blue',
  grid: 4
});

Then, import the desired theme and pass it to TreatProvider at the root of your application.

// App.js
import React from 'react';
import { TreatProvider } from 'react-treat';

import theme from './theme.treat.js';

export const App = () => (
  <TreatProvider theme={theme}>...</TreatProvider>
);

Now that you’ve configured the theming system, define and export themed styles from a treat file.

// Button.treat.js
// ** THIS CODE WON'T END UP IN YOUR BUNDLE EITHER! **
import { style } from 'treat';

export const button = style((theme) => ({
  backgroundColor: theme.brandColor,
  height: theme.grid * 11
}));

Themed styles have higher precedence than non-themed styles, regardless of document order. For more information, read the theming guide.

Then import and resolve themed styles via the useStyles Hook.

// Button.js
import React from 'react';
import { useStyles } from 'react-treat';
import * as styleRefs from './Button.treat.js';

export const Button = (props) => {
  const styles = useStyles(styleRefs);

  return <button {...props} className={styles.button} />;
};

Documentation

See the documentation at seek-oss.github.io/treat for more information about using treat.

License

MIT.