Arpadroid Stylesheet Bundler

Aiming to deliver CSS scalability, maintainability and performance, and ultimately striving to boost CSS development experience, productivity and efficiency, Arpadroid's Stylesheet Bundler package helps bundling stylesheets across your application into different stylesheets or themes.

Index

• Intro
• Features
• Theme configuration and setup
• Using the ThemesBundler
• Setting up LiveReload
• Integration with Webpack

To be, or not to be: the reason behind this package.

I built this package to solve a problem that became quite frustrating as every application I stumbled upon suffered of it: the impossibility to get live reload working properly during CSS/SCSS/LESS development in different Angular/React applications which used different versions of Webpack 4 and 5. What I mean by live reload is that when you save a stylesheet, the style change will reflect instantly in your browser and without any loss of state. I have to emphasize the last part because it is specially helpful when dealing with the nowadays ubiquitous Single Page Application. It means the following: say you were styling a modal which takes three clicks to get to; Saving a style and seeing it reflected in the browser should not have you go through those three clicks again, and you should ideally see the change happen instantly and without having to refresh the browser. This is very important, at least if you want to boost CSS developer productivity, reduce developer frustration, and increase developer experience. Actually it's an incredible productivity booster.

Being frustrated with complex build tools and bundlers and configurations that didn't really work or do what I wanted, I decided to give a shot at bundling the stylesheets myself and this package is what I ended up coming up with.

Having used different versions of this script in different applications I learned a few things about CSS performance and architecture and how they could be leveraged with this script.

Keep reading to learn more...

Features

1. Easily bundle one or multiple theme stylesheets from sources across your application's source code.
   

   ℹ️ You can use multiple stylesheets in your application and toggle them interactively or based in application logic.
   Imagine you wanted to switch between a light and dark theme, or have a theme for different user roles, or even a theme for different application states, this is all easy with Arpadroid's Stylesheet Bundler.
   Why?: Instead of having to create a class name for each state and introduce more specificity into your stylesheet, you can encapsulate your styles in different stylesheets and leverage the cascade by toggling them as required. This helps create a more maintainable, scalable and performant CSS architecture.

2. Supports LESS and SCSS, minifies your CSS in production mode, and automatically re-compiles your stylesheets when changes are made during development.

3. It's lightweight and integrates seamlessly with live reload, increasing CSS developer experience and productivity.

4. Use it alongside any build system, toolchain, framework or application.

Theme Configuration and Setup

1. To install the NPM package please run npm i arpadroid-themes

2. The main styles and CSS assets for each theme will be kept under a directory within your application source code with a name and location of your own choosing. The name of this directory will represent the name of the theme e.g default, dark, light, etc... You can have as many theme directories as you like, each will produce a single stylesheet.

3. A JSON configuration file is required at the root of each theme directory, the naming convention is [directoryName].config.json e.g ../themes/default/default.config.json, ../themes/dark/dark.config.json, ../themes/light/light.config.json, etc...

4. At a minimum, the configuration file should define the theme stylesheets through the includes property. The stylesheet includes are relative to the theme directory and the extension should be omitted. e.g:

   {
       "includes": [
           "vars/colors",
           "vars/easing",
           "vars/layout",
           "vars/screen",
           "vars/typography",
           "vars/animations",
           "vars/variables",
           "vars/fonts",
           "main",
           "components/headings",
           "components/lists",
           "components/scrollbar",
           "components/summary",
           "components/link",
           "components/code",
           "components/blockquote"
       ]
   }

   ℹ️  It's good to avoid the use of @import in your CSS altogether because it creates HTTP requests, which can greatly affect performance and scalability creating a bottleneck during the loading phase. It is best to define your imports as shown above and all files will be concatenated into a single file at the root of your theme directory. Therefore any assets referenced from any stylesheet, no matter where this file might be in your application, will be relative to the theme directory. This helps simplify development.
   

   
   For all other documentation on the theme bundler configuration options please refer to the ThemeBundlerInterface

   export interface ThemeBundlerInterface {
       /**
        * @property {string} path - The absolute path to the theme directory containing all stylesheets.
        * It is NOT required via the file config [themeName].config.json.
        * It is the only required property when creating an instance of the ThemesBundler and defining the themes array.
        * Check it out in the the sample script demo/css/bundle.js.
        */
       path?: string;
   
       /**
        * @property {string[]} includes - An array of stylesheet paths to be included in the compilation process.
        * The paths to the stylesheets are relative to the theme directory and should not include the file extension.
        * e.g. 'main', 'variables/colors', 'variables/sizes' etc...
        */
       includes?: string[];
   
       /**
        * @property {'css' | 'less' | 'scss'} extension - The extension of the theme files, the default is 'css'.
        * Note: the ThemesBundler will allow you to have different themes with different extensions.
        * You have the possibility to have a theme with a .less extension and another with a .scss extension.
        */
       extension?: 'css' | 'less' | 'scss';
   
       /**
        * @property {string} commonThemeFile - A path to a common stylesheet that will be used as a base for the current theme.
        * It is internally set by the ThemesBundler if we set a commonThemePath (refer to ThemesBundlerInterface).
        */
       commonThemeFile?: string;
   
       /**
        * @property {string} configFile - An absolute path to the configuration file for the theme config.
        * It is required to have a config file for any theme. I
        * If the configFile is not specified in the configuration, then the script will look for a file following this pattern:
        * '[themesPath]/[themeName]/[themeName].config.json' e.g. 'src/themes/default/default.config.json'
        */
       configFile?: string;
   
       /**
        * @property {string} target - Specifies the full path and exact filename of the output theme file after compilation.
        * The contents of this file are not minified and should be used in development mode.
        * If not specified, the script will output the styles to a file following this pattern: '/../[themeName]/[themeName].bundled.css'
        */
       target?: string;
   
       /**
        * @property {string} minifiedTarget - Specifies the full path and exact filename of the minified theme file.
        * If not specified, the script will output the styles to a file following this pattern: '/../[themeName]/[themeName].min.css'
        */
       minifiedTarget?: string;
   
       /**
        * @property {string[]} patterns - A set of absolute glob file patterns to be used when looking for theme files in other directories.
        * It is passed via the ThemesBundler config. Refer to ThemesBundlerInterface patterns property for more information.
        */
       patterns?: string[];
   
       /**
        * @property {boolean} verbose - If set to true it logs the output of the compilation process.
        */
       verbose?: boolean;
   
   }

   ℹ️ Any properties defined in the theme's file configuration will take preference and override any other properties defined when we instantiate the ThemesBundler and define the themes, see usage below.

Using the ThemesBundler

We must invoke the themes bundler at build time within a nodeJS script, this can be done in your webpack file (if you are using Webpack), via a script in your package.json or directly via CLI. Here is a documented demo implementation of the ThemesBundler, feel free to copy and repurpose it for you own needs:

/**
 * Sample usage of ThemesBundler.
 * The script will act based upon the --mode passed, which can be either `development` or `production`.
 * You can have a script in your package.json that runs this file with the `--mode` flag.
 * E.g. `node ./scripts/bundle.js --mode=production`.
 */
const arpadroidThemes = require('arpadroid-themes');
const { ThemesBundler } = arpadroidThemes;
const argv = require('yargs').argv;
const mode = argv.mode === 'production' ? 'production' : 'development';
const cwd = process.cwd();
const basePath = cwd + '/demo/css/themes';
// We instantiate the bundler.
const bundler = new ThemesBundler({
    themes: [
        { path: basePath + '/default' },
        { path: basePath + '/mobile' },
        { path: basePath + '/desktop' },
        { path: basePath + '/dark' }
    ],
    patterns: [cwd + '/demo/css/components/**/*', cwd + '/demo/css/pages/**/*'],
    minify: mode === 'production',
    commonThemePath: basePath + '/common'
});

// We wait until the bundler is ready.
bundler.promise.then(() => {
    // We clean up the output directory of each theme before compiling.
    bundler.cleanup();
    // We bundle of all themes.
    bundler.bundle().then(() => {
        if (mode === 'development') {
            // We watch all files for changes and re-bundle the themes correspondingly.
            bundler.watch();
        }
    });
});

ℹ️   Once we run the script above all themes will be bundled into their respective stylesheets.
- For each theme, the bundler will create a file in its root directory called [themeName].bundle.css with the un-minified styles.
- If we are running the script in production mode a minified file will be created [themeName].min.css.
- If you are running the script in development mode and edit a file that belongs to a theme, the theme will be re-bundled on save.

For detailed information about the ThemesBundler configuration check out the ThemesBundlerInterface

export interface ThemesBundlerInterface {
    /**
     * @property {ThemeBundlerInterface[]} themes - An array of ThemeBundlerInterface configurations to define your themes.
     * Check the implementation in demo/css/bundle.js.
     * It is only required to define a path property for each of them.
     * E.g. themes: [{ path: '/../src/themes/default' }, { path: '/../src/themes/dark' }]
     */
    themes?: ThemeBundlerInterface[];

    /**
     * @property {string[]} patterns - A set of absolute glob file patterns to be used when looking for theme files in other directories.
     * Note these external files need to be named as follows to be recognized as theme files:
     * [filename].[themeName].[extension]  e.g. 'my-stylesheet.default.css, my-stylesheet.dark.css'.
     * Check the implementation in demo/css/bundle.js.
     * Those patterns are used to find the theme files in external directories.
     * They will pick up any files in any subdirectories as well so you are free to structure your code as you please.
     */
    patterns?: string[];

    /**
     * @property {boolean} minify - Indicates whether the bundled themes should be minified. Default is false.
     */
    minify?: boolean;

    /**
     * @property {string} commonThemePath - A path to a common theme that will be used as a base for all defined themes.
     * It can be useful when you have scss/less mixins that are required as part of the compilation process of other themes.
     * If set the script will:
     *  1. Look for a theme config file in the specified directory
     *  2. If found, it will bundle the theme.
     *  3. When compiling every other theme, it will prepend the common theme in each theme file.
     */
    commonThemePath?: string;

    /**
     * @property {string} watchPaths - Paths to be monitored for changes in external theme files, if not specified the script will use the working directory by default.
     */
    watchPaths?: string[];
}

Setting up LiveReload

1. Install guard-livereload

2. Copy the Guardfile used in this repo and drop it at the root of your project, modify as needed.

3. Using the CLI, go to the root of your project's source code (the same location where your Guardfile is), and run the command guard.

4. Grab and install the livereload browser extension here: LiveReload for Chrome

5. Navigate to your project's local URL in your browser.
   

   ⚠️ Livereload will not work if you open an HTML file directly in your browser, you need a local server running e.g. localhost:8080

6. Activate livereload extension in your browser.
   Once you do this the CLI running the guard process should say Browser Connected.

7. Enjoy CSS development!
   With all setup correctly, any time you save a change in a CSS file your browser should reflect the change instantly and without affecting the state of your page.

Integration with Webpack

1. In order to integrate the script with Webpack you'll need to invoke the ThemesBundler within the webpack.config.js

   const arpadroidThemes = require('arpadroid-themes');
   const { ThemesBundler } = arpadroidThemes;
   const argv = require('yargs').argv;
   const mode = argv.mode === 'production' ? 'production' : 'development';
   const cwd = process.cwd();
   const basePath = cwd + '/demo/css/themes';
   
   const bundler = new ThemesBundler({
       themes: [
           { path: `${basePath}/default` },
           { path: `${basePath}/dark` }
       ],
       patterns: [`${cwd}/demo/css/components/**/*`, `${cwd}/demo/css/pages/**/*`],
       minify: mode === 'production',
       commonThemePath: basePath + '/common'
   });
   
   module.exports = (async () => {
       await bundler.promise;
       bundler.cleanup();
       await bundler.bundle();
       if (mode === 'development') {
           bundler.watch();
       }
       return [{
           // ...webpackConfig
       }]
   };

2. Finally you will have to export your bundled stylesheets and their corresponding assets. To do so, you can use the copy-webpack-plugin in the webpack config like in the example below:

   const CopyPlugin = require('copy-webpack-plugin');

   // webpack config...
   plugins: [
       // webpack plugins...
       new CopyPlugin({
           patterns: [
               {
                   // exporting the minified style
                   from: 'demo/css/themes/default/default.min.css',
                   to: cwd + '/dist/themes/default/default.min.css'
               },
               {
                   // exporting assets
                   from: './demo/css/themes/default/fonts',
                   to: cwd + '/dist/themes/default/fonts'
               },
               {
                   from: 'modules/theme/themes/dark/dark.min.css',
                   to: cwd + '/dist/themes/dark/dark.min.css'
               }
           ]
       })
   ];

If you want to collaborate, have any ideas or feedback, feel free to reach out through my GitHub email.

One last note: there is a working demo included as part of this repo, which has more information and a few tricks. Don't forget to check it out, to do so open up demo.html in your browser and have a play with it. I have added some practical examples as to how this package can be leveraged, and I'll be adding more with time.