vue-themed-style-loader

A Webpack plugin to be used in conjunction with vue-loader to assist in generating themed builds of a Vue.js application.

• Getting Started
• Use case
• Example
• Contributing
• Versioning
• License
• Acknowledgements

Getting Started

Prerequisites

• Node v6.9.1 or greater
• Vue.js v2.2.6 or greater
• Webpack 2.3.3 or greater

Usage

To use the vue-themed-style-loader, install the theme:

npm install --save-dev vue-themed-style-loader

Add an entry to your webpack configuration file, after the vue-loader:

    ...
    module: {
        rules: [{
            test: /\.vue$/,
            loader: 'vue-loader',
            options: { ... },
        }, {
            test: /\.vue$/,
            loader: 'vue-themed-style-loader',
            options: {
                theme: 'your-theme-name',
            },
        }]
    },
    ...

And begin specifying themes in your Vue component styles:

<style>
.classname {
    color: black;
}
</style>

<style theme="bold">
.heading {
    font-weight: bold;
}
</style>

<style theme="underline">
.heading {
    text-decoration: underline;
}
</style>

Use Case

Consider this simple Vue Single File Component that renders and styles a dynamic <h1> tag:

<template>
    <h1 class="heading">{{title}}</h1>
</template>

<script>
export default {
    name: 'heading-h1',
    props: [ 'title' ],
};
</script>

<style>
.heading { color: black; }
</style>

Themed display

Considering applying different styling "themes" which will alter the color of the heading, which may normally be done via a parent CSS class:

<style>
.heading { color: black; }

.theme-red .heading { color: red; }

.theme-blue .heading { color: blue }
</style>

This will certainly work, however, it doesn't scale very well as your application and number of themes grows. The size of you stylesheet grows with the number of themes, even though only one theme is likely being used at any given point in time. the more complex the themes, the faster the stylesheet size will grow per theme.

Instead, it would be ideal for our resulting stylesheet to only include the styles relevant to our current theme:

/* styles.css */
.heading {  color: black; }

/* styles-red.css */
.heading {  color: black; }
.theme-red .heading { color: red; }

/* styles-blue.css */
.heading { color: black; }
.theme-blue .heading { color: blue; }

Or, even better, in the cases where a theme completely overrides a base style, it would be ideal to remove the base style altogether:

/* styles.css */
.heading {  color: black; }

/* styles-red.css */
.theme-red .heading { color: red; }

/* styles-blue.css */
.theme-blue .heading { color: blue; }

And, if the base styles aren't being included, we don't need the parent theme class anymore, and could ideally reduce our output themed stylesheets to simply:

/* styles.css */
.heading { color: black; }

/* styles-red.css */
.heading { color: red; }

/* styles-blue.css */
.heading { color: blue; }

This is exactly what vue-themed-style-loader set's out to do :)

Example

Let's alter the <style> sections of our component to use the vue-themed-style-loader to generate the proper themed output:

// Base, unthemed styles
<style>
.heading { color: black; }
</style>

// "red" theme
<style theme="red">
.heading { color: red; }
</style>

// "blue" theme
<style theme="blue">
.heading { color: blue; }
</style>

Now, add the loader to your webpack config. It is important to note that because all webpack loaders are run from right-to-left (see Pitching Loaders, the vue-themed-style-loader must be specified after the vue-loader. this ensures it will execute before the vue-loader to discard inactive themed style sections.

Here's an example webpack.config.js:

    ...
    module: {
        rules: [{
            test: /\.vue$/,
            loader: 'vue-loader',
            options: { ... },
        }, {
            test: /\.vue$/,
            loader: 'vue-themed-style-loader',
            options: {
                theme: 'red',
            },
        }]
    },
    ...

In this setup, with the "red" theme specified, the loader will only preserve <style> and <style theme="red"> sections in your component, and will remove the <style theme="blue"> section.

Replacing

Global replacement

In cases where a given theme section wants to completely replace the base styles, the replace attribute can be specified without a value on the <style> block:

<style>
.heading { color: black; }
</style>

<style theme="red" replace>
.heading { color: red; }
</style>

<style theme="blue">
.heading { color: blue; }
</style>

This will result in all the base styles being stripped, and only the <style theme="red"> section being included in the output. If a single replace section is found for the active theme, then all corresponding base styles will be stripped.

Targeted Replacing

In some cases, it may be beneficial to inherit some base styles and replace others. This can be done via targeted replacement. IF you identify base style secton with an id attribute, you can then specify a specific ID to replace in the replace attribute. For example:

<style>
.heading { font-weight:bold; }
</style>

<style id="colors">
.heading { color: black; }
</style>

<style theme="red" replace="colors">
.heading { color: red; }
</style>

<style theme="blue" replace="colors">
.heading { color: blue; }
</style>

In this instance, our themed style only specified replace="colors", so the base style block with id="colors"` will be replaced, but the base style block without an id will still be inherited.

Scoped styles

The removal algorithm operates independently on normal versus scoped style blocks. A non-scoped block will only ever be replaced by a themed, non-scoped block. And a scoped block will only ever be replaced by a themed, scoped block. In this manner, they can be chosen to replace in one scenario and inherit in another. For example:

<style>
.heading { color: black; }
</style>

<style scoped>
.heading { font-weight: bold; }
</style>

<style theme="red" replace>
.heading { color: red; }
</style>

<style scoped theme="red">
.heading { text-decoration: underline; }
</style>

In this scenario, the scoped base style would be maintained because no scoped sections for the active theme specified the replace attribute.

.heading { font-weight: bold; }
.heading { color: red; }
.heading { text-decoration: underline; }

Contributing

Contributions and Pull Requests are welcome! Or if you find something wrong, please file an issue, and provide a detailed description of the problem.

Versioning

This repository uses SemVer for versioning. For the versions available, see the releases on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

• This would not be possible without Webpack and Vue.js.
  • Notably, the vue-template-compiler module
• This work was inspired by some of the interesting work we're doing over at URBN