branding-webpack-plugin
v1.1.0
Published
Cross platform theming with CSS variables
Downloads
4
Readme
Branding plugin 🎨
Use CSS custom properties to theme your app with fallbacks for browsers that don't support it (tested on IE11).
What it does
Branding plugin allows you to import CSS variables that get applied to the page.
The CSS variables are defined in a .branding
file.
When imported, they get applied to the page, therefore any usage of the CSS variable gets the theme's colour.
You also get access to the colour values in JavaScript.
Branding plugin creates a nice fallback for IE 11 by creating an overrides stylesheet that gets loaded only when the browser doesn't support CSS variables.
The end result is that you can easily import a theme's colours without worrying about browser support.
📃 Blog post: You can read more about how it works here
Installation and configuration
You'll need webpack 4.
npm i --save-dev branding-webpack-plugin
A non-supported webpack 3 version also exists. You can install it by running
npm i --save-dev branding-webpack3-plugin
In your webpack config, create a new instance of BrandingPlugin and add its CSS loader to your CSS pipeline, and its loader for *.branding files.
const BrandingPlugin = require('webpack-branding-plugin');
const brandingPlugin = new BrandingPlugin();
module.exports = {
module: {
rules: [
{test: /\.branding$/, use: [brandingPlugin.createLoader()]},
{test: /\.css$/, use: [{loader: 'style-loader'}, {loader: 'css-loader'}, brandingPlugin.createCSSLoader()]}
]
},
plugins: [brandingPlugin]
};
Usage
Say you have your app's CSS in app.css
and some branding/theming colours in theme.branding
.
app.css
body {
color: black;
background: var(--my-theme-color);
}
theme.branding
:root {
--my-theme-color: red;
}
Then, you can import theme.branding
in your entry JS file:
index.js
import './app.css'; // uses CSS and style loader
// uses branding plugin and loader to apply the CSS variables to the page,
// with fallbacks for browsers that don't support it!
import brandingVars from './theme.branding';
console.log(brandingVars); // Output: {'--my-theme-color': 'red'}
This also works with dynamic imports import('./theme.branding')
, which means you can dynamically import a theme
at runtime e.g. import(`./theme-${confirm('Enter theme name')}.branding`)
.
You can read the blog post to learn more about a real use case.
Example
Take a look at the examples
folder for a working example of how it works.
Caveats
- CSS overrides are used to override app CSS when the browser doesn't support custom properties. This has specificity implications.
- There is a known issue where Edge (which supports custom properties) doesn't load images from the correct relative root.
Contributions
Contributions welcome via issues and pull requests! Read our contribution guide here.
There is a basic test to ensure the plugin works with and without CSS variable support.
To run the tests, run:
npm test
You can also run the test server in the background using npm run serve-test
and run jest directly in another terminal using npm run jest
.