vite-plugin-stylelint
v5.3.1vite-plugin-stylelint
Vite Stylelint 插件,默认在 transform
生命周期中运行 Stylelint,支持自定义。
支持 Vite v2 ~ v5。要求 node>=18
。
你可能需要 Vite ESLint 插件。
安装
npm install vite-plugin-stylelint -D
vite-plugin-stylelint
不会为你安装和配置 Stylelint。你应该自己处理这些。
Stylelint@16
npm install stylelint@^16 -D
Stylelint@15
npm install stylelint@^15 -D
Stylelint@14
npm install stylelint@^14 -D
Stylelint@13
npm install stylelint@^13 @types/stylelint@^13 -D
使用
// vite.config.ts
import { defineConfig } from 'vite';
import stylelint from 'vite-plugin-stylelint';
export default defineConfig({
plugins: [stylelint(options)],
});
选项
你可以给这个插件传递 Stylelint shared options 和 Node.js API options。
// vite.config.ts
import { defineConfig } from 'vite';
import stylelint from 'vite-plugin-stylelint';
export default defineConfig({
plugins: [
stylelint({
// 推荐启用自动修复
fix: true,
...,
}),
],
});
额外的选项和解释列写在下方。
test
- 类型:
boolean
- 默认值:
false
在 test
模式下运行 Stylelint。查看 命令行界面 和 配置 Vitest 了解更多。
dev
- 类型:
boolean
- 默认值:
true
在 serve
命令下运行 Stylelint。查看 命令行界面 了解更多。
build
- 类型:
boolean
- 默认值:
false
在 build
命令下运行 Stylelint。查看 命令行界面 了解更多。
cache
- 类型:
boolean
- 默认值:
true
启用时,存储已处理的文件的结果。默认启用以提高速度。
cacheLocation
- 类型:
string
- 默认值:
.stylelintcache
缓存位置的文件或目录的路径。.stylelintcache
是 Stylelint 的默认缓存位置。
include
- 类型:
string | string[]
- 默认值:
['src/**/*.{css,scss,sass,less,styl,vue,svelte}']
这个选项指定你想要校验的文件模式。在绝大部分情况下,你并不需要调整它,除非你正在使用 Nuxt 等框架,或者 include
和 exclude
范围有重合。
如果你正在使用插件默认设置,插件只会在 transform
生命周期中调用 stylelint.lint。这个选项值会被用于 创建一个过滤器 来确定是否该调用以及调用参数。这意味着选项值需要满足 [email protected] 的要求。
如果你启用了 lintOnStart
选项,插件还会在 buildStart
生命周期中调用 stylelint.lint
。这个选项值不会用于创建过滤器,而是直接用作调用参数。这意味着这个选项值还需要满足 [email protected] 的要求。
如果你禁用了 lintDirtyOnly
选项,插件每次调用 stylelint.lint
时都会将该选项值作为调用参数。这意味着这个选项值也需要满足 [email protected]
的要求。
exclude
- 类型:
string | string[]
- 默认值:
['node_modules', 'virtual:']
这个选项指定你不想要校验的文件模式。在绝大部分情况下,你并不需要调整它,除非你正在使用 Nuxt 等框架,或者 include
和 exclude
范围有重合。
如果你正在使用插件默认设置,插件只会在 transform
生命周期中调用 stylelint.lint。这个选项值会被用于 创建一个过滤器 来确定是否该调用以及调用参数。这意味着选项值需要满足 [email protected] 的要求。
如果你启用了 lintOnStart
选项或者禁用了 lintDirtyOnly
选项,这个选项值不会生效。你需要调整 include
值以包含该选项值。
stylelintPath
- 类型:
string
- 默认值:
'stylelint'
Stylelint 路径,用于校验文件。底层使用使用 dynamic import。请先阅读 Vite server.fs 选项。
formatter
- 类型:
StylelintFormatterType | StylelintFormatter
- 默认值:
'string'
格式化器的名称、路径或函数实现。
用于 设置格式化器,以便将校验结果转换为人类或机器可读的字符串。
lintInWorker
- 类型:
boolean
- 默认值:
false
在 worker 校验。默认禁用。
在 worker 中校验时,Vite 的构建过程会更快。即使终端显示了错误,Vite 的构建过程也不会停止。
这与 vite-plugin-checker 类似,但 vite-plugin-checker 可以在浏览器中显示错误。
lintOnStart
- 类型:
boolean
- 默认值:
false
在 buildStart
生命周期中校验 include
选项指定的文件一次以发现潜在的错误。默认禁用。
如果你没有缓存而且没有启用 lintInWorker
,这将大大降低 Vite 的初次启动速度。
lintDirtyOnly
- 类型:
boolean
- 默认值:
true
在 buildStart
生命周期之外运行 Stylelint 时,只校验修改过的文件。默认启用。
禁用时,会校验 include
选项值对应的文件。
chokidar
- 类型:
boolean
- 默认值:
false
在 Chokidar change
事件中而不是在 transform
生命周期中运行 Stylelint。默认禁用。
启用后,可以校验通过 @import
导入的样式文件。
如果你启用这个选项,建议也启用 lintOnStart
。
emitError
- 类型:
boolean
- 默认值:
true
输出发现的错误。默认启用。
emitErrorAsWarning
- 类型:
boolean
- 默认值:
false
将发现的错误作为警告输出。默认禁用,但你可能会在开发原型时启用这个。
emitWarning
- 类型:
boolean
- 默认值:
true
输出发现的警告。默认启用。
emitWarningAsError
- 类型:
boolean
- 默认值:
false
将发现的警告作为错误输出。默认禁用。
FAQ
我需要这个插件吗?
绝大部分情况下不需要。
在 Webpack 使用 stylelint-webpack-plugin 是很常见的,而这个插件在 Vite 中做着几乎一样的事情。
但是,我们的 IDE 可能已经提供了我们需要的所有信息。对于 VSCode,我们只需要添加 Stylelint 插件。 WebStorm 已经内置了这个功能。我们也可以在命令行或者 CI 中运行 Stylelint。
我们有这么多方法运行 Stylelint,没有太大必要在 Vite 中运行 Stylelint,这也就意味着我们在绝大部分情况下不需要这个插件。
如果你真的很需要查看错误和警告,请尝试启用 lintInWorker
选项,它会在 console 中打印信息。
或者尝试一下 vite-plugin-checker,它会在浏览器中打印信息。
Cache 失效
- 禁用
cache
选项。 - 或删除缓存文件(默认是
.stylelintcache
),手动修复错误后重启 Vite。
这个问题应该只会在启动 Vite 出现校验错误时出现。如果你有更好的解决方案,欢迎 PR。:)
使用这个插件时 Vite
很慢
- 试试启用
lintInWorker
选项。 - 或试试 vite-plugin-checker。
- 或在 Vite 外直接运行 Stylelint。
例子
查看 examples。
改动日志
查看 CHANGELOG.md。
致谢
最初从 gxmari007/vite-plugin-eslint 分叉出来。
License
MIT