@instructure/babel-plugin-themeable-styles

---

category: packages

@instructure/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'
import theme from './theme.js'

The plugin will run postcss on the CSS source and transform the CSS import into:

/* Button.js */
const styles = {
  template: function (theme) {
      const tmpl = function () {
        return `.Button__root {
          background: ${theme.background};
          color: ${theme.color};
        }
        .Button__root:hover {
          background: ${theme.hoverBackground};
          color: ${theme.hoverColor};
        }`
      }
      return tmpl.call(theme, theme)
    },
    root: '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-presets.

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

In your .babelrc file:

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

Changelog

5.0.0 (2018-03-29)

Upgrade Guide

The easiest way to upgrade is to run yarn upgrade --scope @instructure. Once you've done this, make sure you check the 'BREAKING CHANGES' section below so that you can make those changes as necessary.

After upgrading you should see deprecation warnings in dev and test environments that will help you prepare for future releases (or check out the 'Deprecations' section below). The ui-codemods scripts should make it easy to update your import/require statements to get rid of a lot of the warnings. Note: you'll need to update your package.json file manually to add the new packages.

Note though, that it's not necessary to upgrade everything at once. Depending on the size of your application you may want to upgrade a package (or component) at a time. This is a major release, but in this case it's safe to do that.

Release Highlights

Breaking up is hard to do: Goodbye, ui-core!

We have broken ui-core into smaller packages like ui-breadcrumb, ui-buttons, and ui-container. This change is intended to make consuming Instructure UI components easier by allowing applications to only import and update the packages they need. You're welcome.