A Webpack loader to encapsulate CSS with a given class name to prevent styles from leaking between modules. Ideal for micro-frontend architectures where multiple teams contribute to the same UI.
In micro-frontend architectures, different teams develop and deploy modules that render on the same page. This can cause CSS rules to unintentionally impact other modules. encapsulated-css-loader
solves this by encapsulating CSS within a unique class name, ensuring style isolation.
This loader is ideal for a decentralised build process, using something unique to the module (e.g., repository name) as the encapsulation class name. When rendering the module, apply the same unique class name to ensure that CSS rules are scoped correctly.
While there are other solutions, such as CSS Modules, there is no guarantee how teams will build and develop their modules. Therefore encapsulating CSS at the highest level - in the Webpack configuration - was considered the fastest, safest, and more robust solution.
example.scss:
h1 {
color: red;
}
.example {
background-color: #FF69B4;
p {
color: #570861;
}
}
example.scss after encapsulation, using "test" as the class name:
.test h1 {
color: red;
}
.test .example {
background-color: #FF69B4;
}
.test .example p {
color: #570861;
}
Please note: The loader does not work for SASS files.
First, install the package as a dev dependency along with sass-loader
:
# Using yarn
yarn add -D encapsulated-css-loader sass-loader
# Using npm
npm install -D encapsulated-css-loader sass-loader
-
Webpack loaders run in reverse order - from bottom to top - so
encapsulated-css-loader
should be the first loader to run. Pass in the desiredclassName
to encapsulate the CSS. -
The next loader must be
sass-loader
- even if you are not using SCSS in your project. -
Configure any other CSS loaders - such as
postcss
,css-loader
, andstyle-loader
- as required.
{
module: {
rules: [
// Bundle styles and process with PostCSS.
{
test: /\.(sc|c)ss$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { sourceMap: true } },
{ loader: 'postcss-loader', options: { postcssOptions: { plugins: ['postcss-preset-env'] } } },
{ loader: 'sass-loader', options: { sourceMap: true } },
{ loader: 'encapsulated-css-loader', options: { className: 'test' } },
],
},
]
}
}