biome-js

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BiomeJS Skill

BiomeJS 技能指南

Quick guidance for BiomeJS configuration based on Sablier project patterns.

基于Sablier项目模式的BiomeJS配置快速指引。

Core Concepts

核心概念

Extending Shared Configs

扩展共享配置

Extend shared configs via npm package exports. The consuming project must always provide its own

files.includes

jsonc

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

For UI projects, extend both base and ui configs:

jsonc

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

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

files.includes

：

jsonc

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

对于UI项目，同时扩展基础配置和UI配置：

jsonc

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

Monorepo Inheritance

单仓库（Monorepo）继承

In monorepos, workspace configs inherit from root using

"//"

jsonc

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

在单仓库中，工作区配置通过

"//"

继承根目录配置：

jsonc

// packages/my-package/biome.jsonc
{
  "extends": ["//"],
  "overrides": [
    // 包专属的覆盖规则
  ]
}

File Includes Pattern

文件包含模式

Always specify

files.includes

explicitly. Common patterns:

Project Type	Pattern
Library	`*/.{js,json,jsonc,ts}`
UI/Frontend	`*/.{css,js,jsx,json,jsonc,ts,tsx}`
With GraphQL	`*/.{css,graphql,js,jsx,json,jsonc,ts,tsx}`

Exclusions:

!node_modules/**/*

!**/generated

!dist

请始终显式指定

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

Common Overrides

常见覆盖规则

Test Files

测试文件

Relax strict rules in test files:

jsonc

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

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

jsonc

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

Generated/ABI Files

自动生成/ABI文件

Disable sorting and compact formatting for generated code:

jsonc

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

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

jsonc

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

Import Restrictions

导入限制

Enforce barrel imports for specific modules:

jsonc

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

强制特定模块使用桶式导入（barrel imports）：

jsonc

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

Key Rules Reference

关键规则参考

Rule	Default	Rationale
`noFloatingPromises`	error	Floating promises cause bugs
`noUnusedImports`	off	Allow during dev, enforce in pre-commit
`noUnusedVariables`	error	Keep code clean
`useImportType`	warn (separatedType)	Explicit type imports
`useSortedKeys`	on	Consistent object ordering
`useSortedClasses`	warn (UI)	Tailwind class sorting
`useFilenamingConvention`	kebab/camel/Pascal	Flexible naming
`noVoid`	off	Useful for useEffect callbacks
`useTemplate`	off	Allow string concatenation

规则	默认设置	理由
`noFloatingPromises`	error	未处理的Promise会导致bug
`noUnusedImports`	off	开发期间允许，预提交时强制执行
`noUnusedVariables`	error	保持代码简洁
`useImportType`	warn (separatedType)	显式类型导入
`useSortedKeys`	on	统一对象键顺序
`useSortedClasses`	warn (UI)	Tailwind类排序
`useFilenamingConvention`	kebab/camel/Pascal	灵活的命名规则
`noVoid`	off	在useEffect回调中很实用
`useTemplate`	off	允许字符串拼接

Git Hooks Integration

Git Hooks集成

Lint-Staged Configuration

Lint-Staged配置

Standard pattern for pre-commit hooks:

javascript

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

The separate

noUnusedImports

pass enforces import cleanup only at commit time, not during development.

预提交钩子的标准模式：

javascript

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

单独的

noUnusedImports

检查仅在提交时执行导入清理，开发期间不强制执行。

UI-Specific Configuration

UI专属配置

For frontend projects with Tailwind CSS:

jsonc

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

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

jsonc

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

Troubleshooting

故障排除

Common Issues

常见问题

"No files matched": Check

files.includes

patterns match your file structure.

Conflicting rules: Overrides are applied in order; later overrides take precedence.

Schema errors: Use local schema reference for IDE support:

jsonc

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

“未匹配到任何文件”：检查

files.includes

模式是否与你的文件结构匹配。

规则冲突：覆盖规则按顺序应用，后续的覆盖规则优先级更高。

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

jsonc

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

Biome vs Prettier

Biome handles JS/TS/JSON/CSS formatting. Use Prettier for:

Markdown (
```
.md
```
,
```
.mdx
```
)
YAML (
```
.yml
```
,
```
.yaml
```
)

Biome处理JS/TS/JSON/CSS的格式化。以下场景使用Prettier：

Markdown（
```
.md
```
,
```
.mdx
```
）
YAML（
```
.yml
```
,
```
.yaml
```
）

Additional Resources

额外资源

Examples

示例

Working examples in

./examples/

./examples/base-config.jsonc
- Minimal library configuration
./examples/ui-config.jsonc
- Frontend project with Tailwind
./examples/lint-staged.js
- Pre-commit hook configuration

./examples/

目录下的可用示例：

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

Full Documentation

完整文档

For advanced features, migrations, or complete rule reference, consult the official Biome documentation via Context7 MCP:

Use context7 to fetch Biome documentation for [specific topic]

The official docs at biomejs.dev should be consulted as a last resort for features not covered here.

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

Use context7 to fetch Biome documentation for [specific topic]

当本指南未涵盖相关功能时，才应作为最后手段访问biomejs.dev上的官方文档。