SWAMPy

✎ CARVE FLESH

EDITING: README.md

---
category: packages
---

## babel-plugin-themeable-styles

[![npm][npm]][npm-url]&nbsp;
[![build-status][build-status]][build-status-url]&nbsp;
[![MIT License][license-badge]][LICENSE]&nbsp;
[![Code of Conduct][coc-badge]][coc]

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

Given CSS file:

```css
/* 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:

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

In addition to running [postcss](https://github.com/postcss/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:

```js
/* 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](https://github.com/webpack/loader-utils#interpolatename)
string to the generateScopedName option:

```js
/* 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:

```js
/* 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

```sh
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](#ui-babel-preset).

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

In your .babelrc file:

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

[npm]: https://img.shields.io/npm/v/@instructure/babel-plugin-themeable-styles.svg
[npm-url]: https://npmjs.com/package/@instructure/babel-plugin-themeable-styles

[build-status]: https://travis-ci.org/instructure/instructure-ui.svg?branch=master
[build-status-url]: https://travis-ci.org/instructure/instructure-ui "Travis CI"

[license-badge]: https://img.shields.io/npm/l/instructure-ui.svg?style=flat-square
[license]: https://github.com/instructure/instructure-ui/blob/master/LICENSE

[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://github.com/instructure/instructure-ui/blob/master/CODE_OF_CONDUCT.md

CANCEL

Name	Type	Size	Modified	Actions
↩ ..	DIR	—	—
📁 lib/	DIR	—	2023-09-24 03:36
📁 test/	DIR	—	2023-09-24 03:36
📄 .npmignore	NPMIGNORE	61 B	2023-09-24 03:36	EDIT
📄 CHANGELOG.md	MD	23.5 KB	2023-09-24 03:36	EDIT
📄 package.json	JSON	1.2 KB	2023-09-24 03:36	EDIT
📄 README.md	MD	3.6 KB	2023-09-24 03:36	EDIT