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.js
module.exports = {
  …
  plugins: [new StylableWebpackPlugin()]
  …
};

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

new StylableWebpackPlugin({ 
    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: /\.(png|jpg|gif)$/,
        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.