oxfmt

Oxfmt — Oxc 格式化工具

Oxfmt 是一款兼容 Prettier、适用于 JavaScript 生态系统的格式化工具。目前，它通过了 Prettier JS/TS 测试套件中约 95% 的测试。它支持格式化 JavaScript、JSX、TypeScript、TSX、JSON、JSONC、JSON5、YAML、TOML、HTML、Angular、Vue、CSS、SCSS、Less、Markdown、MDX、GraphQL、Ember 和 Handlebars。

何时使用 oxfmt

• 在已安装 oxfmt 的项目中修改代码后
• 为新的 JS/TS 项目设置格式化
• 从 Prettier 迁移到 oxfmt
• 配置格式化规则、编辑器集成或 CI 检查

快速参考

安装

# Pick your package manager
npm add -D oxfmt
pnpm add -D oxfmt
yarn add -D oxfmt
bun add -D oxfmt

在 package.json 中添加脚本：

{
  "scripts": {
    "fmt": "oxfmt",
    "fmt:check": "oxfmt --check"
  }
}

不带参数运行 oxfmt 会格式化当前目录（类似于 prettier --write .）。

CLI 标志

标志	用途
--check	检查格式，不写入文件（格式不符时退出码为 1）
--list-different	列出会发生更改的文件
--write	格式化并原地写入（默认）
--init	使用默认值创建 .oxfmtrc.json
--migrate=prettier	将 .prettierrc 转换为 .oxfmtrc.json
--migrate=biome	将 Biome 配置转换为 .oxfmtrc.json
-c PATH	使用指定的配置文件
--ignore-path PATH	指定自定义忽略文件（可重复使用）
--with-node-modules	包含 node_modules/（默认跳过）
--no-error-on-unmatched-pattern	匹配不到 glob 时不报错
--stdin-filepath PATH	格式化标准输入，并使用 PATH 推断解析器
--threads N	线程数（单核时设为 1）
--lsp	启动 LSP 服务（供编辑器使用）

CLI 不支持将格式化选项作为标志使用（例如，不支持 --no-semi）。请改用配置文件，以确保 CLI、编辑器和 CI 的格式化规则保持一致。

配置

Oxfmt 会从当前目录开始向上查找 .oxfmtrc.json 或 .oxfmtrc.jsonc。

生成基础配置：

oxfmt --init

核心选项

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 100,       // Line width limit (default: 100, Prettier default is 80)
  "tabWidth": 2,           // Spaces per indent level
  "useTabs": false,        // Tabs vs spaces
  "semi": true,            // Semicolons
  "singleQuote": false,    // Quote style
  "trailingComma": "all",  // Trailing commas in multi-line
  "insertFinalNewline": true
}

注意：oxfmt 的 printWidth 默认值为 100，而 Prettier 的默认值为 80。迁移时，请决定采用哪个值。

按文件覆盖配置

{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": { "printWidth": 120 }
    },
    {
      "files": ["*.json"],
      "excludeFiles": ["package.json"],
      "options": { "tabWidth": 4 }
    }
  ]
}

内置功能

这些功能默认禁用，但可以在配置中启用：

• sortImports — 对 import 语句排序
• sortTailwindcss — 对 Tailwind CSS 类排序
• sortPackageJson — 对 package.json 字段排序（默认启用）

忽略模式

在配置文件中添加 ignorePatterns，或使用 .oxfmtignore / .prettierignore 文件：

{
  "ignorePatterns": ["dist/", "coverage/", "*.min.js"]
}

.editorconfig 支持

Oxfmt 会读取以下 .editorconfig 属性（仅采用最近的文件，不合并）：

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

从 Prettier 迁移

# Install oxfmt
pnpm add -D oxfmt

# Auto-convert .prettierrc → .oxfmtrc.json
oxfmt --migrate=prettier

# Format everything so the diff is clean
pnpm oxfmt

# Replace Prettier scripts in package.json
# "prettier --write ."  → "oxfmt"
# "prettier --check ."  → "oxfmt --check"

迁移后，请检查生成的 .oxfmtrc.json，尤其是 printWidth，因为其默认值已从 80 改为 100。

编辑器集成

编辑器扩展会使用本地的 oxfmt --lsp，因此必须在项目中安装 oxfmt。

VS Code / Cursor： 从 VS Code Marketplace 安装“Oxc”扩展。推荐的团队设置如下：

.vscode/extensions.json：

{ "recommendations": ["oxc.oxc-vscode"] }

.vscode/settings.json：

{
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.formatOnSave": true
}

Zed： 从 Zed 的市场安装 oxc 扩展。

JetBrains（IntelliJ / WebStorm）： 从 JetBrains Marketplace 安装。

Neovim：

• 使用 nvim-lspconfig：运行 npm i -g oxfmt，然后运行 vim.lsp.enable('oxfmt')
• 使用 conform.nvim：为 js/ts/json/vue 设置 formatters_by_ft
• 使用 coc.nvim：运行 :CocInstall coc-oxc

其他兼容 LSP 的编辑器（Emacs、Helix、Sublime）： 将其指向 oxfmt --lsp。

不支持 LSP 的编辑器： 通过标准输入传入：cat file.js | oxfmt --stdin-filepath file.js

CI 设置

GitHub Actions：

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run fmt:check

GitLab CI：

oxfmt:
  image: node:lts
  stage: test
  before_script:
    - npm install
  script:
    - npm run fmt:check

自动修复（GitHub）： 使用 autofix.ci——运行 oxfmt（不带 --check），并让该操作提交修复结果。

Pre-commit hook（lint-staged）

{
  "lint-staged": {
    "*": "oxfmt --no-error-on-unmatched-pattern"
  }
}

使用 --no-error-on-unmatched-pattern，避免不支持的文件类型导致错误。

Node.js API

import { format } from "oxfmt";

const result = format("foo.ts", "const   x:string   =   1", {
  semi: false,
  singleQuote: true,
});
console.log(result); // const x: string = 1

代码更改后的工作流

在启用了 oxfmt 的项目中修改文件后：

1. 运行 pnpm oxfmt（或项目的 fmt 脚本）来格式化已更改的文件
2. 如果在 CI 或检查场景中，请改用 --check，以验证而不写入文件

格式化工具运行速度足够快，可以处理整个项目；除非通过 stdin 管道传入，否则无需指定单个文件。