node package manager


Stylus loader for webpack


A stylus loader for webpack.

var css = require('!raw!stylus!./file.styl'); // Just the CSS 
var css = require('!css!stylus!./file.styl'); // CSS with processed url(...)s 

See css-loader to see the effect of processed url(...)s.

Or within the webpack config:

module: {
  loaders: [{
    test: /\.styl$/,
    loader: 'css-loader!stylus-loader?paths=node_modules/bootstrap-stylus/stylus/'

Then you can: var css = require('./file.styl');.

Use in tandem with the style-loader to add the css rules to your document:

module: {
  loaders: [
    { test: /\.styl$/, loader: 'style-loader!css-loader!stylus-loader' }

and then require('./file.styl'); will compile and add the CSS to your page.

stylus-loader can also take advantage of webpack's resolve options. With the default options it'll find files in web_modules as well as node_modules, make sure to prefix any lookup in node_modules with ~. For example if you have a styles package lookup files in it like @import '~styles/my-styles. It can also find stylus files without having the extension specified in the @import and index files in folders if webpack is configured for stylus's file extension.

module: {
  resolve: {
    extensions: ['', '.js', '.styl']

will let you have an index.styl file in your styles package and require('styles') or @import '~styles' it. It also lets you load a stylus file from a package installed in node_modules or if you add a modulesDirectories, like modulesDirectories: ['node_modules', 'web_modules', 'bower_components'] option you could load from a folder like bower_components. To load files from a relative path leave off the ~ and @import 'relative-styles/my-styles'; it.

Be careful though not to use the extensions configuration for two types of in one folder. If a folder has a index.js and a index.styl and you @import './that-folder', it'll end up importing a javascript file into your stylus.

You can also use stylus plugins by adding an extra stylus section to your webpack.config.js.

var stylus_plugin = require('stylus_plugin');
module: {
  loaders: [
    { test: /\.styl$/, loader: 'style-loader!css-loader!stylus-loader' }
stylus: {
  use: [stylus_plugin()]

The easiest way of enabling nib is to import it in the stylus options:

stylus: {
  use: [require('nib')()],
  import: ['~nib/lib/nib/index.styl']

where ~ resolves to node_modules/

stylus-loader currently prefers resolving paths with stylus's resovling utilities and then falling back to webpack when it can't find files. Use the preferPathResolver option with the value 'webpack' to swap this. This has the benefit of using webpack's async resolving instead of stylus's sync resolving. If you have a lot of dependencies in your stylus files this'll let those dependencies be found in parallel.

stylus: {
  preferPathResolver: 'webpack',

npm install stylus-loader stylus --save-dev

Important: in order to have ability use any stylus package version, it won't be installed automatically. So it's required to add it to package.json along with stylus-loader.

npm test
open http://localhost:8080/test/

In lieu of a formal styleguide, take care to maintain the existing coding style.

  • Please see
  • 2.3.1 - Fix typo in README (@stevewillard)
  • 2.3.0 - Fix most use cases of relative path resolving (@mzgoddard), Add option to prefer a path resolver (webpack or stylus) (@mzgoddard)
  • 2.2.0 - Let stylus use option be just a function (@yuffiy), Track json calls as imports like use calls (@gnarf)
  • 2.1.2 - Fix support for stylus include config (@andrewburgess), Add block-level imports to listimports (@kenaniah)
  • 2.1.1 - Support Node 6 (@yyx990803), Test in webpack 1 and 2 (@phyllisstein)
  • 2.1.0 - Add support for stylus's include and set (@michaek)
  • 2.0.1 - Add peer dependency on stylus (@jchitel), fix PathCache for webpack 2 (@Unhelpful)
  • 2.0.0 - Remove dependency on stylus (@kossnocorps)
  • 1.6.1 - Remove version breaking change in 1.6.0
  • 1.6.0 - Remove dependency on stylus (@kossnocorps)
  • 1.3.0 - resolve use() calls (@mzgoddard), manual imports through path cache (@mzgoddard)
  • 1.2.0 - files in package.json (@SimenB), test running with testem (@mzgoddard), and some performance changes (@mzgoddard)
  • 1.1.0 - Pass through sourceMap option to stylus instead of defaulting to inline. Inherit source-map from devtool (@jordansexton).
  • 1.0.0 - Basic source map support (@skozin). Remove nib as dep. stylus is now a direct dep (as peerDependencies are deprecated).
  • 0.6.0 - Support loader prefixes when resolving paths (@kpdecker).
  • 0.5.0 - Disable Stylus parser caching in listImports (@DaQuirm). Update to stylus@0.49.2 and nib@1.0.4 as peerDependencies (@kompot).
  • 0.4.0 - Allow configuration of plugins through webpack config (@bobzoller). Update to stylus 0.47.2 (@shanewilson).
  • 0.3.1 - Fix when dependency (@tkellen)
  • 0.3.0 - Define url resolver() when "resolve url" option is true (@mzgoddard).
  • 0.2.0 - Now tracks dependencies for @import statements making cacheable work. Update stylus dep.
  • 0.1.0 - Initial release

Copyright (c) 2014 Kyle Robinson Young
Licensed under the MIT license.