A Stylus loader for webpack. Compiles Stylus files into CSS.
To begin, you'll need to install stylus and stylus-loader:
npm install stylus stylus-loader --save-devor
yarn add -D stylus stylus-loaderor
pnpm add -D stylus stylus-loaderThen add the loader to your webpack configuration. For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
// Uses the built-in CSS support of webpack, i.e. `.module.styl` files
// are treated as CSS modules, other files are treated as plain CSS
type: "css/auto",
// Compiles Stylus to CSS
use: ["stylus-loader"],
},
],
},
experiments: {
// Enables the built-in CSS support of webpack
css: true,
},
};Note
The built-in CSS support of webpack requires experiments.css to be enabled.
Alternatively you can still chain the loader with css-loader and style-loader (or the mini-css-extract-plugin), see Using css-loader and style-loader.
Finally, run webpack using the method you normally use (e.g., via CLI or an npm script).
Type:
type stylusOptions =
| {
use: (string | ((stylusOptions: StylusOptions) => void))[];
include: string[];
import: string[];
define: any[];
includeCSS: false;
resolveURL: boolean | object;
lineNumbers: boolean;
hoistAtrules: boolean;
compress: boolean;
}
| ((loaderContext: LoaderContext) => 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 be written in camelCase.
Use an object to pass options through to Stylus.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
stylusOptions: {
// eslint-disable-next-line jsdoc/no-restricted-syntax
/**
* Specify Stylus plugins to use. Plugins may be passed as
* strings instead of importing them in your Webpack config.
* @type {(string | (renderer: object) => void)[]}
* @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 {[string, string | number | boolean, boolean?] | Record<string, string | number | boolean>}
* @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 | { nocheck?: boolean, paths?: string[] }}
* @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,
},
},
},
],
},
],
},
experiments: {
css: true,
},
};Allows setting the options passed through to Stylus based off of the loader context.
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
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"],
};
},
},
},
],
},
],
},
experiments: {
css: true,
},
};Type:
type sourceMap = boolean;webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
sourceMap: true,
},
},
],
},
],
},
experiments: {
css: true,
},
};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,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
webpackImporter: false,
},
},
],
},
],
},
experiments: {
css: true,
},
};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 will simply 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, such as using multiple Stylus entry files.
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
additionalData: `@env: ${process.env.NODE_ENV};`,
},
},
],
},
],
},
experiments: {
css: true,
},
};module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
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}`;
},
},
},
],
},
],
},
experiments: {
css: true,
},
};module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
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}`;
},
},
},
],
},
],
},
experiments: {
css: true,
},
};Type:
type implementation = (() => typeof import("stylus")) | string;The implementation option allows you to specify which Stylus implementation to use.
It overrides the locally installed peerDependency version of stylus.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
implementation: require("stylus"),
},
},
],
},
],
},
experiments: {
css: true,
},
};webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
implementation: require.resolve("stylus"),
},
},
],
},
],
},
experiments: {
css: true,
},
};Set the module type to css/auto and enable experiments.css to let webpack handle the generated CSS with its built-in CSS support, without any extra loaders or plugins.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto", // Handles the generated CSS using the built-in CSS support of webpack
use: ["stylus-loader"], // Compiles Stylus to CSS
},
],
},
experiments: {
css: true,
},
};The css/auto module type treats *.module.styl files as CSS modules and any other file as plain CSS.
Use type: "css" to always treat the file as plain CSS, or type: "css/module" to always treat it as a CSS module.
The built-in CSS support of webpack is not mandatory, you can still chain the stylus-loader with css-loader and style-loader to immediately apply all styles to the DOM.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
use: [
{
loader: "style-loader", // Creates style nodes from JS strings
},
{
loader: "css-loader", // Translates CSS into CommonJS
},
{
loader: "stylus-loader", // Compiles Stylus to CSS
},
],
},
],
},
};Note that in this case the type and experiments.css options should not be set for this rule, and options like sourceMap have to be enabled for the css-loader too.
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$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
sourceMap: true,
},
},
],
},
],
},
experiments: {
css: true,
},
};webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
stylusOptions: {
use: [require("nib")()],
import: ["nib"],
},
},
},
],
},
],
},
experiments: {
css: true,
},
};Stylus does not provide resolving capabilities in the json() function.
Therefore webpack resolver does not work for .json files.
To handle this, use a 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$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
stylusOptions: {
// Specify the path. where to find files
paths: ["node_modules/vars"],
},
},
},
],
},
],
},
experiments: {
css: true,
},
};The built-in CSS support of webpack always extracts style sheets into dedicated files, so your styles are not dependent on JavaScript, which improves performance and cacheability.
The name of the generated files can be configured using the output.cssFilename and output.cssChunkFilename options.
When you chain the loader with css-loader and style-loader instead, it's recommended to extract the style sheets into a dedicated CSS file in production using the MiniCssExtractPlugin. This way your styles are not dependent on JavaScript.
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 directly from node_modules.
@import 'bootstrap-styl/bootstrap/index.styl';Using ~ prefix is deprecated and can be removed from your code (we recommended), 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, which is different.
Webpack needs to distinguish between bootstrap and ~bootstrap, because CSS and Stylus files have no special syntax for importing relative files.
Writing @import "file" is the same as @import "./file";
If you specify the paths option, modules will be searched in the given paths.
This is the default Stylus behavior.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: [
{
loader: "stylus-loader",
options: {
stylusOptions: {
paths: [path.resolve(__dirname, "node_modules")],
},
},
},
],
},
],
},
experiments: {
css: true,
},
};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.
The built-in CSS support of webpack does this out of the box: every entry point and chunk gets its own style sheet, no extra plugin required.
When you chain the loader with the css-loader instead, use the MiniCssExtractPlugin to extract a style sheet from the bundle.
With the built-in CSS support of webpack, *.module.styl files are treated as CSS modules when the module type is css/auto, and all files are treated as CSS modules when the module type is css/module:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/i,
type: "css/auto",
use: ["stylus-loader"],
},
],
},
experiments: {
css: true,
},
};index.js
import * as styles from "./style.module.styl";
document.body.className = styles.box;We welcome all contributions! If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.