README
stylus-native-loader
A super fast Stylus loader for Webpack that leverages the built-in power of Stylus. Configured for modern development.
Unlike other Stylus loaders available that make use of Webpack's resolver for import path resolution (which comes with several limitations and increased overhead), stylus-native-loader relies on the powerful "native" @import/require capabilities of Stylus.
The result is a highly configurable, lean Stylus loader with near-baseline build speeds and unhindered @import/require functionality (with Webpack alias support) 🥳
stylus-loader?
Why use this instead of- It's really fast.
- It's fully compatible with Webpack 4 and 5.
- It uses Stylus native imports, which are extremely fast and flexible.
- It supports Webpack aliases and has automatic tilde path resolution (e.g.
~nib
=/path/to/node_modules/nib
). - It generates better source maps with optional content.
- It watches entire directories for changes, e.g. when adding new files with glob imports.
- It disables all built-in vendor prefixing (by default) in favor of PostCSS Autoprefixer or similar.
- It uses raw defines (by default), allowing JS object literals to be passed via options and converted to Stylus hashes.
Benchmarks
Build times for the vuejs.org Stylus source code, sorted from fastest to slowest.
Min | Max | Average | Diff % | |
---|---|---|---|---|
stylus (no Webpack) | 73.41ms | 102.84ms | 83.25ms | |
stylus-native-loader | 83.03ms | 104.99ms | 90.80ms | +9.06% |
stylus-relative-loader | 125.02ms | 154.99ms | 144.40ms | +73.45% |
stylus-loader | 140.82ms | 204.26ms | 166.58ms | +100.09% |
Getting started
To begin, install stylus-native-loader
and stylus
:
yarn add -D stylus-native-loader stylus
# or
npm i -D stylus-native-loader stylus
Then add the loader to your webpack.config.js. For example, a minimal configuration might look like this:
module.exports = {
module: {
rules: [
{
test: /\.styl$/,
use: ['style-loader', 'css-loader', 'stylus-native-loader'],
},
],
},
}
Configuration by example
Below is an example webpack.config.js using all stylus-native-loader
options. None are required.
const path = require('path')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
module.exports = {
// Any "original source" option excluding "eval" enables source map generation
// @see https://webpack.js.org/configuration/devtool/
devtool: 'source-map',
resolve: {
// All aliases are used for Stylus @import and @require path resolution
// See `alias` loader option below for adding stylus-specific aliases
alias: {
// A standard alias that matches the first segment of an import path
// Note: Tilde (~) is not required, but is convention for stylesheet aliases
// Maps @import '~styl/*' to '/path/to/src/styl/*'
'~styl': path.join(__dirname, 'src/styl'),
// An "exact match" alias (i.e. will only match @import 'mixins')
// @see https://webpack.js.org/configuration/resolve/#resolvealias
// Maps @import 'mixins' to '/path/to/src/styl/mixins'
'mixins