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",
},
],
},
};
And run webpack
via your preferred method.
Options
stylusOptions
Type:
type stylusOptions =
| {
use: Array<string | Function>;
include: Array<string>;
import: Array<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: {
use: ["nib"],
include: [path.join(__dirname, "src/styl/config")],
import: ["nib", path.join(__dirname, "src/styl/mixins")],
define: [
["$development", process.env.NODE_ENV === "development"],
["rawVar", 42, true],
],
includeCSS: false,
resolveURL: true,
lineNumbers: true,
hoistAtrules: true,
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) => {
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) => {
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) => {
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",
},
{
loader: "css-loader",
},
{
loader: "stylus-loader",
},
],
},
],
},
};
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",
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",
},
{
loader: "css-loader",
},
{
loader: "stylus-loader",
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: {
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")],
},
},
},
],
},
],
},
};
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:
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
License
MIT