Mini CSS themes webpack plugin

Generates themes for webpack css modules based setup. Requires mini-css-extract-plugin as it depends on it to generate the different themes css files. Currently it supports only SASS.

Installation

1. Install npm package:

   npm i --save mini-css-themes-plugin

2. Add plugin in webpack.

   const MiniCssThemesWebpackPlugin = require('mini-css-themes-plugin');
   // ...
   module.exports = {
      plugins: [
        new MiniCssThemesWebpackPlugin({
           themes: {
               'theme_one': './path/to/theme_one/theme.scss',
               'theme_two': './path/to/theme_two/theme.scss',
           },
           defaultTheme: 'theme_one'
        })  
      ]
   };

3. By default use imports to the default theme in all css modules: ex /path/to/theme_one/theme.scss in this example.

How it works

The plugin will duplicate all css modules imports found in js modules for each non default theme. These duplicates will then have their own compilation and a special loader will change the default theme path import in scss files. Finally new chunk is generated for each non default theme.

With the installation example and with two entrypoints you will have the following additional chunks asset outputs:

• theme__theme_two~entrypoint_1.hash.css
• theme__theme_two~entrypoint_2.hash.css

This plugin is not providing the loading mechanism of these themes. You will have to write that yourself. Considering that you also have the webpack manifest plugin:

const defaultTheme: string = 'theme_one';
const selectedTheme: string = 'theme_two';

// Here manifest is the loaded manifest.json.
const loadThemes: (entrypoint: string) => Array<Promise<any>> = (entrypoint) => 
  Object.keys(manifest)
    .filter((file: string) =>  {
      if (selectedTheme !== defaultTheme) {
        // There can be multiple chunks for same theme for this entry.
        return file.indexOf(`theme__${selectedTheme}~${entrypoint}`) === 0 && file.match(/\.css$/)
      } else {
        return file.indexOf(entrypoint) === 0 && file.match(/\.css$/)
      }
    })
    // addCss should take care of loading the css file in the DOM.
    .map((file: string) => addCss(manifest[file]));

Promise.all([
  ...loadThemes('entrypoint_1'),
]).then(() => {
  // ... proceed to render your application ...
});

Themable composes

Using composes with switchable themes is supported, but not recommended as it will slow down unnecessarily the compilation. Prefer extracting components instead of relying on composes.

It is recommended to separate all classes that get composed in a separate file in order to avoid bloating the css modules with many unused classes. This means that one needs to have multiple entry points per theme. Here is an example how to do this:

In webpack config:

new MiniCssThemesWebpackPlugin({
    themes: {
        'theme_one': {
          default: './path/to/theme_one/theme.scss',
          composes: './path/to/theme_one/composes.scss'
        },
        'theme_two': {
          default: './path/to/theme_two/theme.scss',
          composes: './path/to/theme_one/composes.scss'
        },
    },
    defaultTheme: 'theme_one'
});

Then in css modules using composes.

@import './path/to/theme_one/theme.scss';

.composed {
  composes: someClass from './path/to/theme_one/composes.scss';
}

Limitations

1. You must use the theme imports only in css modules. So for example the following is not possible since the plugin cannot detect the theme import and do the switch.

// MyComponent.scss
@import './something/not/from/the/theme.scss'

// ./something/not/from/the/theme.scss
// This import won't be switched when generating the themes and the values below
//  will remain the same for all themes.
@import './path/to/theme_one/theme.scss'
$myOtherVar: $themeVar1 + $themeVar2

2. Currently the plugin won't include plain .css imports from your sources or from under node modules into the separate themes. Since these are not themable anyway it is advised to separate this css imports in their own files (common chunks) and then load them for all themes. This is good for caching and theme file size overall.

Release notes

1.0.0-beta.1

• Additional fixes for loader configurations and assets cleanup.

1.0.0-beta.0

• Add support for webpack 5.