biome-js

BiomeJS 技能

根据 Sablier 项目模式提供的 BiomeJS 配置快速指南。

核心概念

扩展共享配置

通过 npm 包导出扩展共享配置。使用该配置的项目必须始终提供自己的 files.includes：

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["@sablier/devkit/biome"],
  "files": {
    "includes": ["**/*.{js,json,jsonc,ts}", "!node_modules/**/*"]
  }
}

对于 UI 项目，同时扩展 base 和 ui 配置：

{
  "extends": ["@sablier/devkit/biome/base", "@sablier/devkit/biome/ui"],
  "files": {
    "includes": ["**/*.{css,js,jsx,json,jsonc,ts,tsx}"]
  }
}

Monorepo 继承

在 monorepo 中，工作区配置通过 "//" 继承根配置：

// packages/my-package/biome.jsonc
{
  "extends": ["//"],
  "overrides": [
    // package-specific overrides
  ]
}

文件包含模式

始终显式指定 files.includes。常见模式：

项目类型	模式
库	**/*.{js,json,jsonc,ts}
UI/前端	**/*.{css,js,jsx,json,jsonc,ts,tsx}
含 GraphQL	**/*.{css,graphql,js,jsx,json,jsonc,ts,tsx}

排除项：!node_modules/**/*、!**/generated、!dist

常见覆盖配置

测试文件

放宽测试文件中的严格规则：

{
  "overrides": [
    {
      "includes": ["**/tests/**/*.ts", "**/*.test.ts"],
      "linter": {
        "rules": {
          "style": {
            "noNonNullAssertion": "off"
          },
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

生成文件/ABI 文件

禁用生成代码的排序和紧凑格式化：

{
  "overrides": [
    {
      "includes": ["**/abi/**/*.ts", "**/generated/**/*.ts"],
      "assist": {
        "actions": {
          "source": {
            "useSortedKeys": "off"
          }
        }
      },
      "javascript": {
        "formatter": {
          "expand": "never"
        }
      }
    }
  ]
}

导入限制

对指定模块强制使用 barrel 导入：

{
  "overrides": [
    {
      "includes": ["src/**/*.{ts,tsx}"],
      "linter": {
        "rules": {
          "correctness": {
            "noRestrictedImports": {
              "level": "error",
              "options": {
                "paths": {
                  "@/core": "Import from @/core (barrel) instead of subpaths"
                }
              }
            }
          }
        }
      }
    }
  ]
}

关键规则参考

规则	默认值	原因
noFloatingPromises	error	未处理的 Promise 会导致错误
noUnusedImports	off	开发期间允许，提交前检查
noUnusedVariables	error	保持代码整洁
useImportType	warn (separatedType)	显式导入类型
useSortedKeys	on	保持对象键顺序一致
useSortedClasses	warn (UI)	对 Tailwind 类排序
useFilenamingConvention	kebab/camel/Pascal	命名方式灵活
noVoid	off	对 useEffect 回调很有用
useTemplate	off	允许字符串拼接

Git 钩子集成

Lint-Staged 配置

提交前钩子的标准模式：

// .lintstagedrc.js
module.exports = {
  "*.{json,jsonc,ts,tsx}": "bun biome check --write",
  "*.{md,yml,yaml}": "bun prettier --cache --write",
  "*.{ts,tsx}": "bun biome check --write --only=correctness/noUnusedImports",
};

单独运行的 noUnusedImports 检查仅在提交时执行导入清理，不会在开发期间执行。

UI 专用配置

对于使用 Tailwind CSS 的前端项目：

{
  "css": {
    "parser": {
      "tailwindDirectives": true
    }
  },
  "assist": {
    "actions": {
      "source": {
        "useSortedAttributes": "on"
      }
    }
  },
  "linter": {
    "rules": {
      "nursery": {
        "useSortedClasses": {
          "fix": "safe",
          "level": "warn",
          "options": {
            "attributes": ["classList"],
            "functions": ["clsx", "cva", "cn", "tv", "tw"]
          }
        }
      }
    }
  }
}

Biome v2.4.0+ 会自动为 *.module.css 启用 CSS Modules 解析，因此通常不需要显式设置 "cssModules": true，除非项目需要非标准行为。

Biome v2.4+ 说明

• biome check 和 biome ci 现在支持 --only 和 --skip，可针对特定规则或操作运行。
• biome check --write 现在在应用修复时也会进行格式化。
• 配置查找现在也支持隐藏文件：.biome.json 和 .biome.jsonc。
• 配置查找现在也支持用户配置目录（例如，Linux/macOS 上的 $HOME/.config/biome 或等效目录）。
• 新的格式化选项 formatter.trailingNewline 可禁用末尾换行符的插入。
• HTML 格式化器的行为在 v2.4.0 中发生了显著变化；如果启用了格式化器支持，HTML/Vue/Svelte/Astro 文件可能会出现较大的差异。

故障排除

常见问题

“No files matched”：检查 files.includes 模式是否匹配你的文件结构。

规则冲突：覆盖配置按顺序应用；后面的覆盖配置优先级更高。

架构错误：使用本地架构引用以获得 IDE 支持：

"$schema": "./node_modules/@biomejs/biome/configuration_schema.json"

Biome 与 Prettier

Biome 可处理 JS/TS/JSON/CSS 格式化。以下文件请使用 Prettier：

• Markdown（.md、.mdx）
• YAML（.yml、.yaml）

其他资源

示例

./examples/ 中的可运行示例：

• ./examples/base-config.jsonc - 最简库配置
• ./examples/ui-config.jsonc - 使用 Tailwind 的前端项目
• ./examples/lint-staged.js - 提交前钩子配置

完整文档

如需了解高级功能、迁移或完整规则参考，请通过 Context7 MCP 查阅 Biome 官方文档：

Use context7 to fetch Biome documentation for [specific topic]

对于此处未涵盖的功能，请将 biomejs.dev 上的官方文档作为最后的参考来源。