企业官网建设流程全解析

React接入@shadcn/lint完整教程：ESLint + Oxlint双配置实战指南

【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint

@shadcn/lint是一个面向 AI Agent 的 Tailwind 设计系统 linter：你用几条配置声明"设计系统里什么是允许的"，它就能在 ESLint 和 Oxlint 下拦截违规代码，并给出基于你组件、变体和主题的智能修复建议。本教程带你从零在 React 项目中完成 ESLint + Oxlint 双配置实战，几分钟即可让 AI 写的 UI 代码自动符合设计规范。

🎯 它和普通 linter 有什么不同？

普通类型检查只会告诉你"不允许写 padding"，而@shadcn/lint会顺带告诉 Agent该怎么改：

"p-4" is not allowed on <Button>: <Button> owns its spacing. Use a size (sm, lg), or margin here or gap on the parent for space around it.

三个核心卖点：

插件核心实现在 packages/lint/src/plugin.ts，规则源码按文件拆分在 packages/lint/src/rules/ 目录下，方便对照阅读。

✅ 安装前：版本要求一览

💡 如果项目同时装了 ESLint 和 Oxlint，只需把插件注册到实际检查 UI 文件的那个，避免重复配置（见 SETUP.md）。

📦 一步安装：ESLint 与 Oxlint 的依赖

两种方案二选一即可，依赖都装到持有 lint 配置的项目根目录：

# ESLint 方案 npm install -D @shadcn/lint eslint @typescript-eslint/parser # Oxlint 方案 npm install -D @shadcn/lint oxlint

🛠️ ESLint 配置实战：5 分钟完成接入

创建（或修改）项目根目录的eslint.config.mjs。如果你的框架已经配好了 ESLint，保留原有的 parser 配置，只追加插件和规则即可：

import { plugin as shadcn } from "@shadcn/lint" import tsParser from "@typescript-eslint/parser" import { defineConfig } from "eslint/config" export default defineConfig([ { files: ["**/*.{js,jsx,ts,tsx}"], languageOptions: { parser: tsParser, parserOptions: { ecmaFeatures: { jsx: true } }, }, plugins: { shadcn }, rules: { "shadcn/no-restyle": ["error", { allow: ["layout"] }], }, }, ])

关键就四步：导入plugin→ 指定 TSX parser → 挂到plugins→ 写规则。上面示例开启了no-restyle并放行布局类（mt-4、w-full这类），完整可运行配置参考仓库自带的 eslint.config.mjs 和官方 docs/react.md。

运行检查：

npx eslint .

⚡ Oxlint 配置实战：一个 JSON 搞定

Oxlint 的配置更简单，在项目根目录创建.oxlintrc.json：

{ "jsPlugins": ["@shadcn/lint"], "rules": { "shadcn/no-restyle": ["error", { "allow": ["layout"] }] } }

运行：

npx oxlint

⚠️ 小提醒：Oxlint 的 JS 插件 API 目前处于 alpha 阶段，两条配置方式支持的规则、选项、contracts完全一致，可以按团队习惯任选。

🚦 该开启哪些规则？6 条规则速查

每条规则的详解和选项见 docs/rules.md，例如 docs/rules/no-restyle.md 里演示了如何用contracts给 Button、CardTitle 各自定规则。

存量项目建议：先以warn级别开启，用--max-warnings锁定数量逐步清零，新代码用error保持严格——完整策略见 docs/adoption.md。

🤖 关键一步：把 lint 交给 AI Agent

这是@shadcn/lint最大的价值所在。两步闭环：

1. 在package.json加 lint 脚本：

{ "scripts": { "lint": "eslint ." } }

2. 在AGENTS.md写一句指令：

After making changes, run `npm run lint` and fix all errors.

官方测试数据显示，接入后 Agent 在超过 150 次任务运行中，几乎都能在一轮修正内把所有违规清零，且修复成本比只给规则文档低 10%~48%。

🩺 常见问题快答

📚 延伸阅读

• 官方文档总览：docs/README.md
• 自动安装提示词（让 Agent 替你配置）：SETUP.md
• 设计系统配置指南（contracts + 自定义消息）：docs/design-systems.md
• 工作原理：docs/how-it-works.md

按照本教程配置完成后，你的 React 项目就拥有了一个"会教 AI 改正"的设计系统守门员——人写的代码、Agent 写的代码，统统逃不过它的检查。🎉

【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint