stylus-loader

What is stylus-loader?

The stylus-loader npm package is a utility that allows you to load and compile Stylus files directly in Webpack. This integration facilitates the use of Stylus, a pre-processor for CSS, enabling developers to write cleaner and more efficient style sheets by utilizing variables, functions, and mixins.

What are stylus-loader's main functionalities?

Loading and Compiling Stylus Files

This feature allows developers to integrate Stylus files into their Webpack build process. The provided code configures Webpack to use stylus-loader along with css-loader and style-loader to process files ending in .styl, compile them into CSS, and inject them into the DOM.

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          'style-loader',
          'css-loader',
          'stylus-loader'
        ]
      }
    ]
  }
};

Custom Import Paths

This feature allows the specification of custom paths where Stylus files are located, making it easier to organize and maintain stylesheets. The code sample demonstrates how to add custom paths to the stylus-loader configuration in Webpack.

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'stylus-loader',
            options: {
              paths: ['node_modules', 'path/to/import/dir']
            }
          }
        ]
      }
    ]
  }
};

Other packages similar to stylus-loader

sass-loader

Similar to stylus-loader, sass-loader is used to compile Sass files into CSS within the Webpack build process. While both loaders serve a similar purpose for different CSS pre-processors (Stylus for stylus-loader and Sass/SCSS for sass-loader), the choice between them typically depends on the specific syntax and features preferred by the developer.

less-loader

less-loader functions similarly to stylus-loader but for Less files. It integrates with Webpack to compile Less into CSS. Like stylus-loader, it supports customizations such as modifying variable values and managing import paths. The main difference lies in the syntax and capabilities of Less compared to Stylus.

README

stylus-loader

A stylus loader for webpack.

Usage

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.

Stylus Plugins

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()]
}

Multiple configs can be used by giving other configs different names and referring to the with the config query option.

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

Webpack 2

Webpack 2 formalizes its options with a schema. Options can be provided to stylus-loader in the options field to module.rules or through LoaderOptionsPlugin or stylus-loader's OptionsPlugin (a convenience wrapper around LoaderOptionsPlugin).

Config through module rules:

module: {
  rules: [
    {
      test: /\.styl$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'stylus-loader',
          options: {
            use: [stylus_plugin()],
          },
        },
      ],
    }
  ],
},

Config through LoaderOptionsPlugin:

module: {
  rules: [
    {
      test: /\.styl$/,
      loader: 'style-loader!css-loader!stylus-loader',
    },
  ],
},
plugins: [
  new webpack.LoaderOptionsPlugin({
    test: /\.styl$/,
    stylus: {
      // You can have multiple stylus configs with other names and use them
      // with `stylus-loader?config=otherConfig`.
      default: {
        use: [stylus_plugin()],
      },
      otherConfig: {
        use: [other_plugin()],
      },
    },
  }),
],

Config through stylus-loader's OptionsPlugin (convenience wrapper for LoaderOptionsPlugin):

plugins: [
  new stylusLoader.OptionsPlugin({
    default: {
      use: [stylus_plugin()],
    },
  }),
],

Using nib with stylus

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/

Prefer webpack resolving

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',
}

Install

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.

Testing

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

Contributing

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

Release History

• Please see https://github.com/shama/stylus-loader/releases
• 2.4.0 - Add OptionsPlugin to help support webpack 2 (@mzgoddard)
• 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

License

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