stylus-loader
一个用于 webpack 的 Stylus 加载器。将 Stylus 文件编译为 CSS。
入门
首先，你需要安装 stylus 和 stylus-loader
npm install stylus stylus-loader --save-dev
或
yarn add -D stylus stylus-loader
或
pnpm add -D stylus stylus-loader
然后将加载器添加到你的 webpack 配置中。例如：
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl$/,
loader: "stylus-loader", // compiles Styl to CSS
},
],
},
};最后，使用你通常使用的方法运行 webpack（例如，通过 CLI 或 npm 脚本）。
选项
stylusOptions
类型
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>;默认值：{}
你可以通过 加载器选项 中的 stylusOptions 属性，将任何 Stylus 特定的选项传递给 stylus-loader。
请参阅 Stylus 文档。
破折号命名（dash-case）的选项应以驼峰命名（camelCase）编写。
object
使用一个对象将选项传递给 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.org.cn/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.org.cn/docs/executable.html
*
* @type {boolean}
* @default false
*/
lineNumbers: true,
/**
* Move @import and @charset to the top.
*
* @see https://stylus.org.cn/docs/executable.html
*
* @type {boolean}
* @default false
*/
hoistAtrules: true,
/**
* Compress CSS output.
* In the "production" mode is `true` by default
*
* @see https://stylus.org.cn/docs/executable.html
*
* @type {boolean}
* @default false
*/
compress: true,
},
},
},
],
},
],
},
};function
允许根据加载器上下文设置传递给 Stylus 的选项。
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.cn/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 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 webpackImporter = boolean;默认值：true
启用/禁用默认的 Webpack 导入器。
在某些情况下，这可以提高性能。请谨慎使用，因为别名和以 ~ 开头的 @import at-rules 将不起作用。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.styl/i,
use: [
"style-loader",
"css-loader",
{
loader: "stylus-loader",
options: {
webpackImporter: false,
},
},
],
},
],
},
};additionalData
类型
type additionalData =
| string
| (
content: string | Buffer,
loaderContext: LoaderContext,
meta: any
) => string;默认值：undefined
在实际入口文件之前预置 Stylus 代码。在这种情况下，stylus-loader 不会覆盖源文件，而只是预置入口文件内容。
当你的某些 Stylus 变量依赖于环境时，这尤其有用。
[!注意]
由于你正在注入代码，这会破坏入口文件中的源映射。通常有比这更简单的解决方案，例如使用多个 Stylus 入口文件。
string
module.exports = {
module: {
rules: [
{
test: /\.styl/,
use: [
"style-loader",
"css-loader",
{
loader: "stylus-loader",
options: {
additionalData: `@env: ${process.env.NODE_ENV};`,
},
},
],
},
],
},
};function
同步
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.cn/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;
},
},
},
],
},
],
},
};异步
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.cn/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 implementation = Function | string;implementation 选项允许你指定要使用的 Stylus 实现。它会覆盖本地安装的 stylus 的 peerDependency 版本。
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"),
},
},
],
},
],
},
};示例
普通用法
将 stylus-loader 与 css-loader 和 style-loader 链式结合使用，以便立即将所有样式应用于 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
},
],
},
],
},
};源映射
要为 CSS 启用源映射，您需要在加载器选项中传递 sourceMap 属性。如果未传递此属性，加载器将遵循 devtool 中设置的 webpack 源映射设置。
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,
},
},
],
},
],
},
};将 nib 与 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"],
},
},
},
],
},
],
},
};导入 JSON 文件
Stylus 不在 json() 函数中提供解析能力。因此 webpack 解析器不适用于 .json 文件。要处理此问题，请使用 stylus 解析器。
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"],
},
},
},
],
},
],
},
};生产环境
通常，建议在生产环境中使用 MiniCssExtractPlugin 将样式表提取到专门的 CSS 文件中。这样你的样式就不依赖于 JavaScript。
webpack 解析器
Webpack 提供了一种高级的文件解析机制。stylus-loader 在处理查询时会应用 webpack 解析器。因此，你可以直接从 node_modules 导入 Stylus 模块。
@import 'bootstrap-styl/bootstrap/index.styl';
使用 ~ 前缀已被弃用，可以从你的代码中删除（我们推荐），但出于历史原因我们仍然支持它。
为什么可以删除它？加载器会首先尝试将 @import/@require 解析为相对路径，如果无法解析，加载器将尝试在 node_modules 中解析 @import/@require。
只需在它们前面加上 ~，这会告诉 webpack 去查找 modules。
@import "~bootstrap-styl/bootstrap/index.styl";
只使用 ~ 前缀很重要，因为 ~/ 会解析到用户主目录，这是不同的。
Webpack 需要区分 bootstrap 和 ~bootstrap，因为 CSS 和 Stylus 文件没有用于导入相对文件的特殊语法。
编写 @import "file" 与 @import "./file"; 相同。
Stylus 解析器
如果你指定 paths 选项，模块将在给定的 paths 中搜索。这是 Stylus 的默认行为。
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")],
},
},
},
],
},
],
},
};提取样式表
使用 webpack 打包 CSS 有一些优点，例如在开发中引用带有哈希 URL 的图像和字体，或使用热模块替换。然而，在生产环境中，根据 JS 执行来应用样式表并不是一个好主意。渲染可能会延迟，甚至可能出现FOUC (无样式内容闪烁)。因此，在最终的生产构建中将它们作为单独的文件通常仍然更好。
有两种方法可以从捆绑包中提取样式表
extract-loader（更简单，但专门用于 css-loader 的输出）- MiniCssExtractPlugin (更复杂，但适用于所有用例)
贡献
我们欢迎所有贡献！如果您是新用户，请在提交问题或拉取请求之前花一些时间阅读我们的贡献指南。