@anomen/rethemeable

    5.0.1 • Public • Published

    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.

    Keywords

    none

    Install

    npm i @anomen/rethemeable

    DownloadsWeekly Downloads

    2

    Version

    5.0.1

    License

    MIT

    Last publish

    Collaborators

    • anomen