Setup

To get started, add the treat webpack plugin to webpack.config.js. Since webpack is required to use treat, the webpack plugin is provided via the core treat package as treat/webpack-plugin.

const { TreatPlugin } = require('treat/webpack-plugin');

module.exports = {
  plugins: [new TreatPlugin()]
};

By default, this will inject styles into the page via style-loader, but this can be overridden via the outputLoaders option.

For example, if you’d like to export static CSS files, you can wire it up to mini-css-extract-plugin.

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

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

For more configuration options, view the full list of webpack options.

In order to improve the debugging experience, treat also provides an optional Babel plugin.

First, install the plugin:

$ yarn add --dev babel-plugin-treat

Then, add it to your Babel config. For example, in .babelrc:

{
  "plugins": ["babel-plugin-treat"]
}

All styling APIs (except for globalStyle) have an optional argument that allows you to provide a local debug name.

For example, the local name for the following style will be style by default because treat doesn’t have access to your variable name at runtime.

export const green = style({ color: 'green' });

To fix this, you can pass in a debug name as the last argument:

export const green = style({ color: 'green' }, 'green');

Server-rendered apps will likely be running two webpack builds (one for the browser code, and one for the server code). The server config should disable CSS output by setting outputCSS to false.

const { TreatPlugin } = require('treat/webpack-plugin');

module.exports = {
  plugins: [
    new TreatPlugin({
      outputCSS: false
    })
  ]
};

If you’d like to dynamically load themes, treat supports bundle splitting via webpack dynamic imports with no special setup.

In practice, it’s likely you’ll want to split your themes into separate CSS files. This is achieved by dynamic importing your treat files that call createTheme.

Let’s assume you have a set of theme files that look like this:

// mainTheme.treat.js
import { createTheme } from 'treat';

export default createTheme({
  // Theme variables...
});

You can then dynamically load the desired theme and use it to resolve styles.

import { resolveStyles } from 'treat';
import styleRefs from './styles.treat';

// Inject the theme name somehow:
const themeName = getThemeName();

import(`../themes/${themeName}.treat`).then((theme) => {
  const styles = resolveStyles(theme.default, styleRefs);
  // You now have access to themed styles!
});

If you’re using the React API, you’ll want to provide the theme to your TreatProvider.

To use treat in a Gatsby project, install gatsby-plugin-treat and add it to your gatsby-config.js file like this:

module.exports = {
  plugins: ['gatsby-plugin-treat']
};

You can also provide webpack options to the plugin:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-treat',
      options: {
        // Plugin options go here...
      }
    }
  ]
};

To use treat in a Next.js project, install next-treat and add it to your next.config.js file like this:

const withTreat = require('next-treat')(/* Extra TreatPlugin options */);

module.exports = withTreat(/* Additional Next.js configuration */);

Debugging experience can be improved by setting up the Babel plugin with the .babelrc below:

{
  "presets": ["next/babel"],
  "plugins": ["babel-plugin-treat"]
}