@anomen/rethemeable

Rethemeable

Rethemeable provides utilities for producing and consuming themeable React components.

It doesn't define the notion of theme. A theme can be a list of CSS class names or a set of inline style directives.

It doesn't define how components apply themes. It is up to component to decide what and when to apply CSS class names or inline styles.

Instead Rethemeable define a way to propagate theme through React component tree.

It's up to component authors to declare the theming contract for each component.

It's up to consumers to fulfil the theming contract for each component.

Installation

Install from npm:

% npm install rethemeable

Usage

Define a themeable component:

import { themeable } from 'rethemeable'
import React from 'react'

@themeable
class Button extends React.Component {

  render() {
    let theme = this.theme
    return (
      <button className={theme.self}>
        <i className={theme.icon} />
        {this.props.children}
      </button>
    )
  }
}

Now define a theme as a collection of styles for a set of React components. Styles for each component are isolated by an unique key within the theme:

import Button from 'widgets/Button'

let BootstrapTheme = {
  [Button.theme]: {
    self: 'btn btn-xs'
  }
}

And configure it via <ApplyTheme /> component:

import { ApplyTheme } from 'rethemeable'
import React from 'react'

React.render(
  <ApplyTheme theme={BootstrapTheme}>
    <div>
      <h1>This is an app</h1>
      <Button>See, I don't have theme prop passed explicitly</Button>
    </div>
  </ApplyTheme>
)

Component <Button /> will receive theme implicitly.

You can also pass theme directly to component via props if you need a more fine-grained control:

<Button theme={BootstrapTheme} />

If you don't want to use <ApplyTheme /> component but just apply some theme on a themeable component you can use theme function:

import { theme } from 'rethemeable'
import ThemeableButton from 'third-party-themeable-button'

let MyButton = theme(ThemeableButton, BootstrapTheme);

React.render(<MyButton>Hello, I'm themed!</MyButton>)

Rethemeable with CSS modules

Rethemeable approach works well with CSS modules, as you can compose your theme from a set of CSS modules:

import Button from 'widgets/Button'
import Modal from 'widgets/Button'

import ButtonTheme from './Button.css'
import ModalTheme from './Modal.css'

let Theme = {
  [Button.theme]: ButtonTheme,
  [ModalTheme.theme]: ModalTheme
}

Chunking theme and component separately, or when to pass themeKeys

It can be desirable to chunk (or split) bundled assets in production, especially when dealing with larger sites.

When chunking themeable components, the theme and themeable components must to be able to be loaded independently in order for a build pipeline (like Webpack) to properly optimize chunk size and contents.

Separating the definition of theme keys from a given themeable component allows the keys, theme, and components to be loaded if and whenever they are needed.

./key-registry.js

/** List of theme keys to connect classmaps with component themes */

export {
  Button: Symbol('Button'),
  Modal: Symbol('Modal')
}

./theme.js

/** Map themeKey Symbols to theme classmaps */

import { Button, Modal } from './key-registry';
import ButtonTheme from './button.css';
import ModalTheme from 'some-module/with-modal-styles.css';

const theme = {
  [Button]: ButtonTheme,
  [Modal]: ModalTheme
}

export { theme }

./Button.jsx

import { themeable } from 'rethemeable';
import { compAKey as themeKey } from './key-registry';

class Button {}

export default themeable(Button, {themeKey});

./Modal.jsx

import { themeable } from 'rethemeable';
import { compBKey as themeKey } from './key-registry';

class Modal {}

export default themeable(Modal, {themeKey});

./Layout.jsx

/** Provide theme to themeable components via context */

import Helmet from 'react-helmet';
import { theme } from './theme.js';
import { ApplyTheme } from 'rethemeable';

// map of asset paths extracted during build
import assets from 'assets-map.json';

class App {
  /*

  render(
    <ApplyTheme theme={theme}>
      <Helmet link={assets.theme.css} />
        {this.props.children}
    </ApplyTheme>
    )
}

Without chunks, all components are hard dependencies of a theme. Therefore they must be chunked together to preserve the link of Symbol to theme. This can result bloated chunks and/or tedious maintenance of themes.