stylus-loader

8.1.3 verified Sat Apr 25 auth: no javascript

Webpack loader that compiles Stylus (.styl) files into CSS. Current stable version is 8.1.3, released February 2026, with regular bugfix updates. Maintained by the webpack team. Key differentiator: first-class webpack integration, supports webpack resolve and loaders, optional Rspack compatibility since v8.1.0, and incremental build optimization. Requires Node.js >=18.12.0 (v8) and Stylus >=0.52.4 as a peer dependency. Alternatives like stylus itself require separate CLI usage or manual integration.

Common errors

error Error: Module build failed (from ./node_modules/stylus-loader/dist/cjs.js): TypeError: Cannot read properties of undefined (reading 'stylus') ↓

cause Stylus is not installed or not a peer dependency

fix

npm install stylus --save-dev

error Error: Node.js version 14.15.0 is not supported. Please upgrade to Node.js 18.12.0 or higher. ↓

cause Using stylus-loader v8 with older Node.js

fix

Upgrade Node.js to 18.12.0+

error Warning: The define option as an object is deprecated. Use array syntax. ↓

cause Using object syntax for `define` in stylusOptions

fix

Change to array: define: [['var', value, raw]]

Warnings

breaking Node.js version requirement raised ↓

fix Upgrade to Node.js 18.12.0 or higher

gotcha Stylus options must be nested under `stylusOptions` ↓

fix Wrap Stylus options in `stylusOptions: { ... }`

breaking Minimum Stylus version requirement ↓

fix Use Stylus >=0.52.4

deprecated `define` option as an object is deprecated ↓

fix Use array syntax for `define`: [[key, value, raw]]

gotcha Options in dash-case must be camelCase ↓

fix Use `lineNumbers` instead of `line-numbers`, etc.

Install

npm install stylus-loader

yarn add stylus-loader

pnpm add stylus-loader

Imports

StylusLoader
wrong
```
const stylusLoader = require('stylus-loader')
```
correct
```
import stylusLoader from 'stylus-loader'
```
CommonJS require works but default export is typically used as loader string, not imported programmatically.

Webpack config

wrong

{
  test: /\.styl$/,
  use: 'stylus-loader'
}

correct

{
  test: /\.styl$/,
  loader: 'stylus-loader'
}

Both work, but 'loader' is more concise when no other loaders are chained.

stylusOptions

wrong

{
  test: /\.styl$/,
  use: [{
    loader: 'stylus-loader',
    options: { /* stylus options directly */ }
  }]
}

correct

{
  test: /\.styl$/,
  use: [{
    loader: 'stylus-loader',
    options: {
      stylusOptions: { /* ... */ }
    }
  }]
}

Stylus options must be nested under 'stylusOptions' key, not flattened.

Quickstart

Basic webpack configuration to load Stylus files with style-loader, css-loader, and stylus-loader, including source maps.

// webpack.config.js
const path = require('path');
module.exports = {
  mode: 'development',
  entry: './src/style.styl',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          { loader: 'style-loader' },
          { loader: 'css-loader', options: { sourceMap: true } },
          { loader: 'stylus-loader', options: { stylusOptions: { compress: false } } }
        ]
      }
    ]
  }
};