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. Compiles Styl to CSS.

Getting Started

To begin, you'll need to install stylus and stylus-loader:

npm install stylus stylus-loader --save-dev

or

yarn add -D stylus stylus-loader

or

pnpm add -D stylus stylus-loader

Then add the loader to your webpack config. For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        loader: "stylus-loader", // compiles Styl to CSS
      },
    ],
  },
};

And run webpack via your preferred method.

Options

• stylusOptions
• sourceMap
• webpackImporter
• additionalData
• implementation

stylusOptions

Type:

type stylusOptions =
  | {
      use: Array<string | Function>;
      include: string;
      import: string;
      define: Array;
      includeCSS: false;
      resolveURL: boolean | Object;
      lineNumbers: boolean;
      hoistAtrules: boolean;
      compress: boolean;
    }
  | (loaderContext: LoaderContext) => Array<string>;

Default: {}

You can pass any Stylus specific options to the stylus-loader through the stylusOptions property in the loader options. See the Stylus documentation. Options in dash-case should use camelCase.

object

Use an object to pass options through to Stylus.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
          },
          {
            loader: "stylus-loader",
            options: {
              stylusOptions: {
                /**
                 * Specify Stylus plugins to use. Plugins may be passed as
                 * strings instead of importing them in your Webpack config.
                 *
                 * @type {(string|Function)[]}
                 * @default []
                 */
                use: ["nib"],

                /**
                 * Add path(s) to the import lookup paths.
                 *
                 * @type {string[]}
                 * @default []
                 */
                include: [path.join(__dirname, "src/styl/config")],

                /**
                 * Import the specified Stylus files/paths.
                 *
                 * @type {string[]}
                 * @default []
                 */
                import: ["nib", path.join(__dirname, "src/styl/mixins")],

                /**
                 * Define Stylus variables or functions.
                 *
                 * @type {Array|Object}
                 * @default {}
                 */
                // Array is the recommended syntax: [key, value, raw]
                define: [
                  ["$development", process.env.NODE_ENV === "development"],
                  ["rawVar", 42, true],
                ],
                // Object is deprecated syntax (there is no possibility to specify "raw')
                // define: {
                //   $development: process.env.NODE_ENV === 'development',
                //   rawVar: 42,
                // },

                /**
                 * Include regular CSS on @import.
                 *
                 * @type {boolean}
                 * @default false
                 */
                includeCSS: false,

                /**
                 * Resolve relative url()'s inside imported files.
                 *
                 * @see https://stylus-lang.com/docs/js.html#stylusresolveroptions
                 *
                 * @type {boolean|Object}
                 * @default { nocheck: true }
                 */
                resolveURL: true,
                // resolveURL: { nocheck: true },

                /**
                 * Emits comments in the generated CSS indicating the corresponding Stylus line.
                 *
                 * @see https://stylus-lang.com/docs/executable.html
                 *
                 * @type {boolean}
                 * @default false
                 */
                lineNumbers: true,

                /**
                 * Move @import and @charset to the top.
                 *
                 * @see https://stylus-lang.com/docs/executable.html
                 *
                 * @type {boolean}
                 * @default false
                 */
                hoistAtrules: true,

                /**
                 * Compress CSS output.
                 * In the "production" mode is `true` by default
                 *
                 * @see https://stylus-lang.com/docs/executable.html
                 *
                 * @type {boolean}
                 * @default false
                 */
                compress: true,
              },
            },
          },
        ],
      },
    ],
  },
};

function

Allows setting the options passed through to Stylus based off of the loader context.

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              stylusOptions: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.styl") {
                  return {
                    paths: ["absolute/path/c", "absolute/path/d"],
                  };
                }

                return {
                  paths: ["absolute/path/a", "absolute/path/b"],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

sourceMap

Type:

type sourceMap = boolean;

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              sourceMap: true,
            },
          },
          {
            loader: "stylus-loader",
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

webpackImporter

Type:

type webpackImporter = boolean;

Default: true

Enables/Disables the default Webpack importer.

This can improve performance in some cases. Use it with caution because aliases and @import at-rules starting with ~ will not work.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              webpackImporter: false,
            },
          },
        ],
      },
    ],
  },
};

additionalData

Type:

type additionalData =
  | string
  | (
      content: string | Buffer,
      loaderContext: LoaderContext,
      meta: any
    ) => string;

Default: undefined

Prepends Stylus code before the actual entry file. In this case, the stylus-loader will not override the source but just prepend the entry's content.

This is especially useful when some of your Stylus variables depend on the environment:

Note

Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Stylus entry files.

string

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              additionalData: `@env: ${process.env.NODE_ENV};`,
            },
          },
        ],
      },
    ],
  },
};

function

Sync

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              additionalData: (content, loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.styl") {
                  return "value = 100px" + content;
                }

                return "value 200px" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

Async

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              additionalData: async (content, loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === "styles/foo.styl") {
                  return "value = 100px" + content;
                }

                return "value 200px" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

implementation

Type:

type implementation = Function | string;

The special implementation option determines which implementation of Stylus to use. Overrides the locally installed peerDependency version of stylus.

function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              implementation: require("stylus"),
            },
          },
        ],
      },
    ],
  },
};

string

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              implementation: require.resolve("stylus"),
            },
          },
        ],
      },
    ],
  },
};

Examples

Normal usage

Chain the stylus-loader with the css-loader and the style-loader to immediately apply all styles to the DOM.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          {
            loader: "style-loader", // creates style nodes from JS strings
          },
          {
            loader: "css-loader", // translates CSS into CommonJS
          },
          {
            loader: "stylus-loader", // compiles Stylus to CSS
          },
        ],
      },
    ],
  },
};

Source maps

To enable sourcemaps for CSS, you'll need to pass the sourceMap property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in devtool.

webpack.config.js

module.exports = {
  devtool: "source-map", // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              sourceMap: true,
            },
          },
          {
            loader: "stylus-loader",
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

Using nib with stylus

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          {
            loader: "style-loader", // creates style nodes from JS strings
          },
          {
            loader: "css-loader", // translates CSS into CommonJS
          },
          {
            loader: "stylus-loader", // compiles Stylus to CSS
            options: {
              stylusOptions: {
                use: [require("nib")()],
                import: ["nib"],
              },
            },
          },
        ],
      },
    ],
  },
};

Import JSON files

Stylus does not provide resolving capabilities in the json function. Therefore webpack resolver does not work for .json files. Use stylus resolver.

index.styl

// Suppose the file is located here `node_modules/vars/vars.json`
json('vars.json')

@media queries-small
  body
    display nope

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "stylus-loader",
            options: {
              stylusOptions: {
                // Specify the path. where to find files
                paths: ["node_modules/vars"],
              },
            },
          },
        ],
      },
    ],
  },
};

In production

Usually, it's recommended to extract the style sheets into a dedicated file in production using the MiniCssExtractPlugin. This way your styles are not dependent on JavaScript.

webpack resolver

Webpack provides an advanced mechanism to resolve files. The stylus-loader applies the webpack resolver when processing queries. Thus you can import your Stylus modules from node_modules.

@import 'bootstrap-styl/bootstrap/index.styl';

Using ~ is deprecated and can be removed from your code (we recommend it), but we still support it for historical reasons. Why you can removed it? The loader will first try to resolve @import/@require as relative, if it cannot be resolved, the loader will try to resolve @import/@require inside node_modules. Just prepend them with a ~ which tells webpack to look up the modules.

@import "~bootstrap-styl/bootstrap/index.styl";

It's important to only prepend it with ~, because ~/ resolves to the home-directory. Webpack needs to distinguish between bootstrap and ~bootstrap, because CSS and Styl files have no special syntax for importing relative files. Writing @import "file" is the same as @import "./file";

Stylus resolver

If you specify the paths option, modules will be searched in the given paths. This is Stylus default behavior.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.styl/,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
          },
          {
            loader: "stylus-loader",
            options: {
              stylusOptions: {
                paths: [path.resolve(__dirname, "node_modules")],
              },
            },
          },
        ],
      },
    ],
  },
};

Extracting style sheets

Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or hot module replacement in development. In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a FOUC might be visible. Thus it's often still better to have them as separate files in your final production build.

There are two possibilities to extract a style sheet from the bundle:

• extract-loader (simpler, but specialized on the css-loader's output)
• MiniCssExtractPlugin (more complex, but works in all use-cases)

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT

Changelog

7.1.0 (2022-10-06)

Features

• allow to extend conditionNames (#365) (5d76d64)