category: packages

babel-plugin-themeable-styles

Transforms CSS imports (via css-modules-require-hook) into a JavaScript object that provides a CSS Module, along with a template function that, given a theme variables object, will return the themed CSS as a string.

Given CSS file:

/* style.css */
.root {
  background: var(--background);
  color: var(--color);

  &:hover {
    background: var(--hoverBackground);
    color: var(--hoverColor);
  }
}

and a JavaScript module that imports the CSS file:

/* Button.js */
import styles from './styles.css'

In addition to running postcss on the CSS source, a unique component id is generated by hashing the source. The component id is made available as the componentId property in the resulting JavaScript import object. The component id is also used to generate scoped CSS class names. By default, in production, CSS class names are prepended by the component id. In development, CSS class names are prepended by the name of the CSS source's containing directory in addition to the component id for easier debugging.

If you'd like to customize how the scoped class names are generated, you can add a config file to your project root:

/* themeable.config.js */
module.exports = {
  generateScopedName: (context, componentId, name, filepath, css) {
    // note that you can use interpolated strings here too:
    return `${componentId}-[folder]__${name}`
  }
}

Or just pass an interpolated string to the generateScopedName option:

/* themeable.config.js */
module.exports = {
  generateScopedName: '[name]__[local]___[hash:base64:5]'
} 

The transformed CSS import result in development would look similar to the following example:

/* Button.js */
const styles = {
  componentId: 'dUxGkD',
  template: function (theme) {
    const tmpl = function () {
      return `.dUxGkD__Button__root {
        background: ${theme.background};
        color: ${theme.color};
      }
      .dUxGkD__Button__root:hover {
        background: ${theme.hoverBackground};
        color: ${theme.hoverColor};
      }`
    }
    return tmpl.call(theme, theme)
  },
  root: 'dUxGkD__Button__root'
}

Installation

yarn add --dev @instructure/babel-plugin-themeable-styles

Usage

Note: the easiest way to use this plugin is to use the babel preset provided by @instructure/ui-babel-preset.

However the plugin can be configured on its own as follows:

In your .babelrc file:

{
  "plugins": [
    [
      "@instructure/babel-plugin-themeable-styles",
      {
        ignore: "node_modules/**/*"
      }
    ],
  ]
}