Arpadroid Stylesheet Bundler

:information_source: 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.

{
    "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"
    ]
}

:information_source:  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.

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;

}

:information_source: 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.

/**
 * 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();
        }
    });
});

:information_source:   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.

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[];
}

:warning: Livereload will not work if you open an HTML file directly in your browser, you need a local server running e.g. localhost:8080 Activate livereload extension in your browser. Once you do this the CLI running the guard process should say Browser Connected. 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.

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
    }]
};

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'
            }
        ]
    })
];