oxfmt

Oxfmt

当工作涉及 Oxfmt 或 Oxc 格式化时，请使用此技能：包括安装和配置、日常使用、迁移 Prettier/Biome、排序扩展、语言支持、编辑器或 CI --check 门禁。

工作流

1. 修改代码前，先检查本地 Oxfmt 配置：
   • oxfmt 的包版本（在 1.0 前仍为 0.x / beta；上次更新时为 0.71）。
   • 配置：优先使用带有 defineConfig 的 oxfmt.config.ts / .mts；也接受 .oxfmtrc.json(c)（每个目录只能使用一种类型）；Vite+ 也可以在 vite.config.* 中使用 fmt（Vite+ 模式下始终关闭嵌套配置）。
   • 剩余的 Prettier/Biome 配置、.prettierignore、脚本（format / format:check）、编辑器默认格式化工具。
2. 对于安装、使用方法、样式选择、排序、单仓库多包配置、与 Oxlint 搭配或故障排查，请先阅读完整指南：usage-guide.md。
3. 如果版本与快照不同，或工作涉及语言支持、排序或迁移，请刷新当前官方文档。从 source-map.md 开始。
4. 更深入的细节请参阅对应的参考文档：
   • 安装、CLI、配置选项、editorconfig：setup-cli-config.md。
   • 语言、排序（imports / Tailwind / package.json / JSDoc）、忽略规则、行内注释：languages-sorting-ignores.md。
   • Prettier/Biome 迁移、共存、CI 和 .vscode 设置：prettier-migration-ci.md。
5. 除非正在迁移或用户要求更改，否则保留项目的打印宽度、引号/分号样式和 experimentalOperatorPosition。
6. 对修改过的路径运行 bunx oxfmt --check（CI）或 bunx oxfmt（写入）进行验证。

核心判断

• Oxfmt 对 JS/TS 兼容 Prettier（目标是与 Prettier 输出一致；与近期 Prettier 输出不一致的差异属于 bug）。它尚未达到 1.0——请固定 lockfile 中的版本。
• 默认模式是写入。CI 门禁为 oxfmt --check（存在差异时退出码为 1；未匹配到文件时退出码为 2）。
• 没有 Prettier 风格的 CLI 样式标志（例如 --no-semi）——样式仅在配置文件中设置。
• 默认 printWidth 为 100，而非 Prettier 的 80。迁移时设置 printWidth: 80，以尽量减少差异。
• 新配置优先使用 oxfmt.config.ts + defineConfig。如果项目已有 .oxfmtrc.json，则保留或继续使用。--init / --migrate 仍会生成 JSON——添加新配置时请转换为 TS。
• 新项目优先使用 ignorePatterns；迁移期间仍可使用 .prettierignore。模式不能使用 ..，也不能匹配配置目录之外的文件。
• .gitignore 适用于遍历/目录目标，不适用于显式指定的文件。作为路径传入的 Git 忽略目录仍会被跳过。
• 内置排序功能（sortImports、sortTailwindcss、sortPackageJson、jsdoc）可替代 Prettier 插件——不支持 Prettier 插件。
• Tailwind：启用 sortTailwindcss；设置 stylesheet（v4）或 config（v3）；在 functions 中列出辅助函数（cn/clsx/…）。路径相对于 Oxfmt 配置文件。
• sortPackageJson 默认启用——请预期 package.json 会出现差异。不需要时可禁用。
• 支持 experimentalOperatorPosition（"start" | "end"，默认值为 "end"）。仍不支持 experimentalTernaries。
• YAML（.yml / .yaml）为原生支持。HTML/Vue/Svelte/Markdown/MDX/Handlebars/MJML 仍由捆绑的 Prettier 3.9.9 提供支持（Vue/Svelte 的 <script> 为原生支持；原生 Markdown 支持正在开发中）。
• 编辑器：格式化和 import/Tailwind 排序由 Oxfmt 负责。将 editor.formatOnSaveMode 设为 "file"（Oxfmt 不支持部分格式化）。未使用项的移除由 Oxlint 通过 source.fixAll.oxc 负责。禁用 TS organizeImports / removeUnusedImports。
• 不要在同一条流水线中同时运行 Oxfmt 与 Prettier 或 Biome 来格式化代码。
• Oxfmt 负责格式化；它不能替代 linter。移除 eslint-plugin-prettier；只有在仍使用 ESLint 时才保留 eslint-config-prettier。
• 在 Oxfmt 支持 Astro 及依赖 Prettier 插件的格式之前，它们可能会成为迁移阻碍。

验证

优先使用仓库自带的命令。对于有实际意义的 Oxfmt 工作，覆盖相关子集：

• 对变更的路径运行 bunx oxfmt --check，或对整个仓库运行，以与 CI 保持一致。
• 本地运行 bunx oxfmt／lint-staged 以应用格式化。
• 迁移到 Prettier 后：抽查 JS/TS 差异；确认 printWidth 和 experimentalOperatorPosition；准备就绪后移除 Prettier 脚本／依赖。
• 排序：确认 sortImports／Tailwind（stylesheet 或 config + functions）／package.json 的行为符合团队预期。
• 更改 Oxc 扩展设置时，冒烟测试编辑器保存时格式化（formatOnSaveMode: "file"）+ source.fixAll.oxc；确认已关闭 TS 整理导入功能。

报告运行了哪些检查、哪些没有运行，以及仍存在的任何 0.x 成熟度或语言支持方面的假设。