Stylable Webpack Plugin
The Stylable Webpack Plugin (for Webpack version 4x) is the main build utility for Stylable. It supports both development and production modes, providing various configurations that can be tweaked according to your specific needs. It enables loading Stylable files (.st.css
) from local projects or imported from a 3rd party source (for example, NPM node modules).
Getting started
Install stylable-webpack-plugin
as a dev dependency in your local project.
Install using npm:
npm install stylable-webpack-plugin --save-dev
Install using yarn:
yarn add stylable-webpack-plugin --dev
Sample dev config:
// webpack.config.jsmoduleexports = … plugins: …;
Plugin Configuration Options
Some of the default values given to configuration parameters depend on what environment mode is currently active in webpack (development
or production
).
Below you can see the various possible configuration parameters and their default values.
Option | Type | Development Mode Default | Production Mode Default | Description |
---|---|---|---|---|
outputCSS | boolean | false | true | Generate CSS asset files per bundle |
filename | string | - | [name].bundle.css | The name of the CSS bundle file when outputCSS is enabled |
includeCSSInJS | boolean | true | false | Include target CSS in the JavaScript modules (used by runtime renderer) |
createRuntimeChunk | boolean | false | false | Move all Stylable modules into a separate chunk with a runtime renderer |
rootScope | boolean | true | true | Enable automatically scoping the root component (will default to false in the upcoming future) |
bootstrap.autoInit | boolean | true | true | Initialize the rendering of the CSS in the browser |
optimize.removeUnusedComponents | boolean | true | true | Remove selectors that contain namespaces (classes) that are not imported by JavaScript |
optimize.removeComments | boolean | false | true | Remove CSS comments from the target |
optimize.removeStylableDirectives | boolean | true | true | Remove all -st-* from target (currently also removes empty rules which will be a separate option coming soon) |
optimize.classNameOptimizations | boolean | false | true | Shorten all class names and replace them in the JavaScript modules |
optimize.shortNamespaces | boolean | false | true | Shorten all namespaces which affects the resulting data-* selectors and DOM attributes |
optimize.minify | boolean | false | true | Minify each css asset. |
Sample production configuration
outputCSS: true includeCSSInJS: false optimize: removeUnusedComponents: true removeComments: true removeStylableDirectives: true classNameOptimizations: true shortNamespaces: true minify: true
Asset handling
CSS assets are handled by a url-loader + file-loader combination.
module: rules: test: /\.$/ use: loader: "url-loader" options: limit: 8192
Compatibilities with existing loading mechanisms
If you're using css_loader/extract make sure to exclude .st.css
files from the process. You cannot use loaders with Stylable .st.css
files
How it works (in case you're wondering)
The plugin transforms all Stylable files into JavaScript modules with CSS rendering capabilities.
Every bundle that contains Stylable modules is injected with a stylable-bootstrap-module
as its entrypoint. This module is responsible for:
- Ensuring that all of the transformed modules are imported in the proper order.
- Initializing the runtime DOM renderer.
The resulting renderer orders the CSS by the depth of each module, calculated from its dependencies and component dependencies.
Stylable bootstrap module The stylable-bootstrap-module
is a generated module injected into the bundle as its entrypoint and ensures all Stylable modules are injected into the runtime renderer.
Runtime DOM renderer The core Stylable runtime renderer in the browser is responsible for rendering stylesheets in the correct order in the DOM.