KSS Webpack Plugin

1.6.0 verified Sat Apr 25 auth: no javascript maintenance

KSS Webpack Plugin (v1.6.0) generates a KSS styleguide from CSS/SCSS sources during Webpack builds. It integrates kss-node into the Webpack pipeline, allowing styleguide generation as part of the build process. The plugin supports custom templates and automatic insertion of named chunks (JS or CSS) into the styleguide. Compatible with KSS (Knyle Style Sheets) documentation format. Last updated in 2021 with a low release cadence; peer dependencies require Webpack 3 or 4. Alternative to standalone kss-node CLI with tighter Webpack integration.

Common errors

error this.render is not a function ↓

cause Missing or incompatible kss-node version installed.

fix

npm install kss@3 --save-dev

error Cannot find module 'kss' ↓

cause kss (kss-node) is a peer dependency and not installed.

fix

npm install kss --save-dev

error Error: No valid source found ↓

cause Source path is incorrect or does not contain CSS/SCSS files.

fix

Ensure the 'source' path exists and contains .css or .scss files.

error Webpack 5 compatibility issue: Tapable.plugin is not a function ↓

cause Plugin uses Webpack 3/4 plugin API which changed in Webpack 5.

fix

Use webpack-kss for Webpack 5 or downgrade to Webpack 4.

Warnings

gotcha Chunks must be named in Webpack entry; unnamed chunks are not supported. ↓

fix Define entry points with keys (e.g., entry: { main: './src/index.js' }) to use chunks configuration.

gotcha Plugin does not add any chunks to the styleguide by default; you must specify the chunks array or manually include assets. ↓

fix Add a 'chunks' array in kssConfig listing the chunk names to inject.

breaking This plugin is designed for Webpack 3 and 4. It may not work with Webpack 5. ↓

fix Use webpack-kss or update plugin; or use kss-node CLI separately for Webpack 5 builds.

deprecated The package has not been updated since 2021; consider it in maintenance mode. ↓

fix Evaluate alternative solutions like stylemark or standalone kss-node.

gotcha Node.js version older than 12 may cause compatibility issues with dependencies. ↓

fix Upgrade Node.js to 12 or newer.

Install

npm install kss-webpack-plugin

yarn add kss-webpack-plugin

pnpm add kss-webpack-plugin

Imports

KssWebpackPlugin

wrong

import KssWebpackPlugin from 'kss-webpack-plugin';

correct

const KssWebpackPlugin = require('kss-webpack-plugin');

Package uses CommonJS; no default ESM export. Use require().

KssWebpackPlugin

wrong

import * as KssWebpackPlugin from 'kss-webpack-plugin';

correct

import KssWebpackPlugin = require('kss-webpack-plugin');

TypeScript users should use import = require() for CJS compatibility.

Instance

wrong

KssWebpackPlugin({ source: 'path/to/css' })

correct

new KssWebpackPlugin({ source: 'path/to/css' })

Required constructor must be instantiated with 'new'.

Quickstart

Configures KssWebpackPlugin with source, destination, custom template, and automatic chunk insertion.

const KssWebpackPlugin = require('kss-webpack-plugin');
const path = require('path');

const kssConfig = {
  source: path.resolve(__dirname, 'src/styles'),
  destination: path.resolve(__dirname, 'dist/styleguide'),
  builder: path.resolve(__dirname, 'kss-template'),
  chunks: ['main', 'vendor']
};

const webpackConfig = {
  entry: {
    main: './src/index.js',
    vendor: ['react', 'react-dom']
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].bundle.js'
  },
  plugins: [
    new KssWebpackPlugin(kssConfig)
  ]
};

module.exports = webpackConfig;