docs(oxfmt): Follow recent updates (#716)

leaysgur · web-flow · commit b62bcb8a3efd · 2025-12-19T16:38:16.000+08:00
diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts
@@ -93,6 +93,14 @@ export const enConfig = defineLocaleConfig("root", {
               link: "/docs/guide/usage/formatter",
               collapsed: true,
               items: [
+                {
+                  text: "Configuration",
+                  link: "/docs/guide/usage/formatter/config",
+                },
+                {
+                  text: "Integration",
+                  link: "/docs/guide/usage/formatter/integration",
+                },
                 {
                   text: "CLI reference",
                   link: "/docs/guide/usage/formatter/cli",
diff --git a/src/docs/guide/usage/formatter.md b/src/docs/guide/usage/formatter.md
@@ -10,7 +10,36 @@ Please join the discussion!
 > RFC: Formatter · oxc-project/oxc · Discussion #13608\
 > https://github.com/oxc-project/oxc/discussions/13608
 
-Waiting on oxfmt to implement additional features? Consider using [@prettier/plugin-oxc](https://github.com/prettier/prettier/tree/main/packages/plugin-oxc) in Prettier to gain some parsing speed in the meantime.
+Waiting on Oxfmt to implement additional features? Consider using [@prettier/plugin-oxc](https://github.com/prettier/prettier/tree/main/packages/plugin-oxc) in Prettier to gain some parsing speed in the meantime.
+:::
+
+## Features
+
+- Support many kinds of file types
+  - JS/TS(X): Supported by `oxc_formatter`
+  - All file types supported by Prettier by default
+- Faster alternative of Prettier CLI
+  - Over [30×](/blog/2025-12-01-oxfmt-alpha.html#performance) faster than Prettier’s experimental CLI without cache
+- Experimental but usable features
+  - Native sort-imports
+  - Native sort-packagejson
+
+## Supported languages
+
+- JS, JSX
+- TS, TSX
+- JSON, JSONC, JSON5
+- YAML
+- HTML, Angular, Vue, MJML
+- Ember, Handlebars
+- CSS, SCSS, Less
+- GraphQL
+- Markdown, MDX
+
+:::warning
+
+Note that the `embeddedLanguageFormatting` option is not fully supported in JS/TS files. And for now, it is disabled by default.
+
 :::
 
 ## Installation
@@ -65,78 +94,44 @@ $ bun add -D oxfmt
 
 ## Command-line Interface
 
-`oxfmt` works like `prettier --write .` by default.
+`oxfmt` CLI works like `prettier --write .` by default.
 
-Formatting config options like `--no-semi` are not supported via CLI flags, we recommend setting these via the configuration file instead. This will ensure that the CLI and editor integrations always use the same settings.
+Formatting config options like `--no-semi` are not supported via CLI flags.
+We recommend setting these via the configuration file instead. This will ensure that the CLI and editor integrations always use the same settings.
 
 Globs in positional paths are not expanded. (You can rely on your shell.) But `!`-prefixed exclude paths do support glob expansion.
 
 See more details in the [CLI reference](./formatter/cli).
 
-## Configuration file
-
-By default, `oxfmt` automatically tries to find the nearest `.oxfmtrc.json` or `.oxfmtrc.jsonc` file from the current working directory. If not found, the default configuration options are used.
+## Node.js API
 
-You can also specify your config file with the `-c yourconfig.jsonc` flag.
+`oxfmt` is also available via Node.js API: `format()` function.
 
-Almost all formatting options are compatible with Prettier's [options](https://prettier.io/docs/options).
-So you can migrate from Prettier by simply renaming `.prettierrc.json` to `.oxfmtrc.jsonc`.
+```ts
+import { format } from "oxfmt";
+import type { FormatOptions } from "oxfmt";
 
-We also recommend adding the `$schema` to the config file after copying it:
+const INPUT = `let a=42;`;
+const options: FormatOptions = {
+  semi: false,
+};
 
-```json
-{
-  "$schema": "./node_modules/oxfmt/configuration_schema.json"
-}
+const { code, errors } = await format("a.js", INPUT, options);
+console.log(code); // "let a = 42"
 ```
 
-You can see the full JSON schema for the config file here:
-
-> https://github.com/oxc-project/oxc/blob/main/npm/oxfmt/configuration_schema.json
-
-See also [Configuration File](./formatter/config-file-reference).
-
-## Ignore file
-
-By default, `oxfmt` automatically finds the `.gitignore` and `.prettierignore` files from the current working directory.
+## System Requirements
 
-Also you can specify your ignore file by `--ignore-path your.ignore` flag.
-
-VCS directories like `.git` and `.svn` are always ignored. Also global and nested ignores are not respected.
-
-In addition, `.oxfmtrc.json(c)` supports an `ignorePatterns` field.
-
-## Pre-commit hook
-
-If you want to auto-format staged files with oxfmt in a git pre-commit hook, you can use `oxfmt --no-error-on-unmatched-pattern`.
-
-This command is equivalent to `prettier --no-error-on-unmatched-pattern --write`, and will format all matched files that are supported by oxfmt. The `--no-error-on-unmatched-pattern` flag ensures that oxfmt will not raise errors if there are no supported files passed into the command by your pre-commit hook tool (e.g. only Ruby files are staged).
-
-You can also pass `--check` to only _check_ the formatting of files, and bail if any files are incorrectly formatted.
-
-If you are using a pre-commit hook via husky/lint-staged, you can run oxfmt with it by updating your package.json like so:
-
-```json
-"lint-staged": {
-  "*": "oxfmt --no-error-on-unmatched-pattern"
-},
-```
+- **Node.js**: >= 20.19.0 or >= 22.12.0
+- **Platforms**: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, and win32-x64
 
 ## FAQs
 
-### What kinds of files are supported?
-
-Currently, only JavaScript and TypeScript files are supported (using all common JS/TS extensions and filenames, including `.js`, `.jsx`, `.ts`, `.mjs`, etc.).
-JSX is always available in JS files, but for TypeScript, the `.tsx` extension is required to use JSX syntax.
-
-Embedded parts like CSS-in-JS have experimental partial support.
-By specifying `embeddedLanguageFormatting: auto`, non-substitution templates will be formatted.
-
 ### What is the compatibility with Prettier?
 
-We're following the `main` branch of Prettier, not the `latest` release.
+For JS/TS files, we're tested against the `v3.7.3` of Prettier.
 
-For other differences, please see this discussion.
+For known differences, please see this discussion.
 
 > `Oxfmt` differences with `Prettier` · oxc-project/oxc · Discussion #14669\
 > https://github.com/oxc-project/oxc/discussions/14669
@@ -148,24 +143,23 @@ The following are NOT currently supported:
 - `prettier` field in `package.json`
 - File formats other than `.json(c)`
 - Nested configs in sub directories
-- `override` field
-- Respect `.editorconfig`
+- `overrides` field
+- Nested `.editorconfig` in sub directories
 - `experimentalTernaries` and `experimentalOperatorPosition` option
 
-Also, if `printWidth` is not specified, its default value is `100`. This differs from Prettier's default.
+Also, if `printWidth` is not specified, its default value is `100`. This differs from Prettier's default `80`.
 
 ### Are Prettier plugins supported?
 
-Currently, they are not supported.
-
-For import sorting functionality, we provide experimental behavior based on `eslint-plugin-perfectionist/sort-imports` through the `experimentalSortImports` configuration option.
+Currently, NOT supported.
 
-### How does editor integration work?
+However, for import sorting functionality, we provide experimental behavior based on `eslint-plugin-perfectionist/sort-imports` through the `experimentalSortImports` option.
 
-For VS Code, the Oxc extension is available from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) and [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode).
+And for `prettier-plugin-packagejson`, we have the `experimentalSortPackageJson` option, which is enabled by default.
 
-For other editors, by running `oxfmt --lsp` you can start a language server that responds to standard `textDocument/formatting` requests.
+See more details in the [Configuration file reference](./formatter/config-file-reference).
 
-Formatting via stdin and stdout are not supported, but we have confirmed that some editors and extensions can work with the CLI by configuring them to use temporary files.
+### Why are nested scripts and code blocks not formatted?
 
-However, these methods have some limitations, such as not supporting formatting of embedded parts.
+Currently, the `embeddedLanguageFormatting` option is `off` by default.
+Please set it to `auto` in your config file.
diff --git a/src/docs/guide/usage/formatter/config.md b/src/docs/guide/usage/formatter/config.md
@@ -0,0 +1,49 @@
+# Configuration
+
+## `.oxfmtrc.json(c)`
+
+We support `.json` or `.jsonc` config file.
+
+Almost all formatting options are compatible with Prettier's [options](https://prettier.io/docs/options).
+
+We also recommend adding the `$schema` to the config file:
+
+```json
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json"
+}
+```
+
+For full reference, see also [Configuration file reference](./config-file-reference).
+
+By default, `oxfmt` automatically tries to find the nearest `.oxfmtrc.json` or `.oxfmtrc.jsonc` file from the current working directory. If not found, the default configuration options are used.
+
+You can also specify your config file with the `-c yourconfig.jsonc` flag.
+
+## `.editorconfig`
+
+`.editorconfig` file is also supported by Oxfmt.
+
+And these fields will override default options.
+
+- `end_of_line`: `endOfLine`
+- `indent_style`: `useTabs`
+- `indent_size`: `tabWidth`
+- `max_line_length`: `printWidth`
+
+If both `.editorconfig` and `.oxfmtrc.json` has the same field, `.oxfmtrc` will win.
+
+By default, `oxfmt` automatically tries to find the nearest `.editorconfig` file from the current working directory.
+
+Unlike Prettier, Oxfmt does not respect `root = true` and does not merge nested `.editorconfig` files.
+
+## Ignore files
+
+By default, `oxfmt` automatically finds the `.gitignore` and `.prettierignore` files from the current working directory.
+
+Also you can specify your ignore file by `--ignore-path your.ignore` flag.
+In addition, `.oxfmtrc.json(c)` supports an `ignorePatterns` field.
+
+Global and nested ignores are not respected.
+
+VCS directories like `.git` and `.svn` are always ignored, also popular lock files are also ignored.
diff --git a/src/docs/guide/usage/formatter/integration.md b/src/docs/guide/usage/formatter/integration.md
@@ -0,0 +1,37 @@
+# Integration
+
+## Editor
+
+For VS Code, the Oxc extension is available from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) and [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode).
+
+For other editors, by running `oxfmt --lsp` you can start a language server that responds to standard `textDocument/formatting` requests.
+
+:::warning
+
+Currently, LSP support has some limitations, such as not supporting formatting of embedded parts in JS/TS files, non-JS files support.
+
+:::
+
+Formatting via stdin and stdout are also supported.
+
+```sh
+cat foo/bar.js | oxfmt --stdin-filepath f.js --config ./path/to/config.json
+```
+
+In addition, we have confirmed that some editors and extensions can work with the CLI by configuring them to use temporary files.
+
+## Pre-commit hook
+
+If you want to auto-format staged files with Oxfmt in a git pre-commit hook, you can use `oxfmt --no-error-on-unmatched-pattern`.
+
+This command is equivalent to `prettier --no-error-on-unmatched-pattern --write`, and will format all matched files that are supported by oxfmt. The `--no-error-on-unmatched-pattern` flag ensures that Oxfmt will not raise errors if there are no supported files passed into the command by your pre-commit hook tool (e.g. only Ruby files are staged).
+
+You can also pass `--check` to only _check_ the formatting of files, and bail if any files are incorrectly formatted.
+
+If you are using a pre-commit hook via husky/lint-staged, you can run Oxfmt with it by updating your package.json like so:
+
+```json
+"lint-staged": {
+  "*": "oxfmt --no-error-on-unmatched-pattern"
+},
+```
diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md
@@ -3,18 +3,12 @@
 If you currently use Prettier as your code formatter, you can follow this guide to migrate to Oxfmt.
 
 Note that Oxfmt is in alpha, and may not be suitable for production use in complex setups.
-For the beta milestone, we may provide migration commands.
-
-> oxfmt: `--migrate prettier` · Issue #15849 · oxc-project/oxc\
-> https://github.com/oxc-project/oxc/issues/15849
 
 ## Caveats for migrating to Oxfmt
 
-Before migrating, ensure that the current release of the Oxfmt alpha meets your project's needs. It is almost entirely compatible with Prettier v3.7 already for basic configurations, but less-common config options and other features are not yet implemented.
-
-<!-- TODO: Remove this note when oxfmt 0.17.0 ships with many of the missing languages. -->
+Before migrating, ensure that the current release of the Oxfmt alpha meets your project's needs.
 
-The Oxfmt alpha only supports formatting JavaScript and TypeScript files (including those with JSX syntax). If you need support for non-JSX frameworks like Vue or Ember, or other languages like JSON, YAML, or Markdown, you will likely want to wait.
+It is almost entirely compatible with Prettier v3.7 already for basic configurations, but less-common config options and other features are not yet implemented.
 
 Other important considerations when migrating from Prettier to Oxfmt:
 
@@ -79,6 +73,14 @@ If you have a basic `.prettierrc` file, you can simply rename the file with `mv
 
 If you are using something other than JSON to configure Prettier, you will need to convert the configuration to JSON.
 
+In either case, you can use the migrate command in your project root directory.
+
+```sh
+oxfmt --migrate prettier
+```
+
+This command automatically finds your configuration file and converts it to `.oxfmtrc.json` if possible.
+
 ### `prettierrc.js`
 
 Here's an example of migrating a `prettierrc.js` file.
