From 5fb221f56f1aae486cf4f9d48a6b2234bf6b19a7 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Mon, 1 Dec 2025 22:19:42 -0700 Subject: [PATCH 1/9] Add a WIP docs page for migrating from Prettier to oxfmt. --- .vitepress/config/en.ts | 4 + .../usage/formatter/migrate-from-prettier.md | 279 ++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 src/docs/guide/usage/formatter/migrate-from-prettier.md diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts index e178002e5d..554b3bf25b 100644 --- a/.vitepress/config/en.ts +++ b/.vitepress/config/en.ts @@ -101,6 +101,10 @@ export const enConfig = defineLocaleConfig("root", { text: "Configuration file reference", link: "/docs/guide/usage/formatter/config-file-reference", }, + { + text: "Migrating from Prettier", + link: "/docs/guide/usage/formatter/migrate-from-prettier", + }, ], }, { text: "Parser", link: "/docs/guide/usage/parser" }, diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md new file mode 100644 index 0000000000..d8e65beba1 --- /dev/null +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -0,0 +1,279 @@ +# Migrating from Prettier to oxfmt + +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. + +## 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 3.7 already for basic configurations, but less-common config options and other features are not yet implemented. + +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. + +Other important considerations when migrating from Prettier to oxfmt: + +- oxfmt's formatting output is closest to Prettier v3.7. If you are using an older version of Prettier, you will see more differences in formatting output. +- oxfmt aims to be mostly compatible with Prettier out-of-the-box, but there may still be some minor differences in formatting output in edge-cases. +- oxfmt uses a `printWidth` of 100 characters by default, whereas Prettier's default is 80. If your Prettier configuration does not set the `printWidth` setting explicitly, you should make sure to set `"printWidth": 80` in your oxfmt config file to minimize differences. +- Prettier plugins are not yet supported. +- Some Prettier options are not supported. See the [oxfmt CLI documentation](/docs/guide/usage/formatter/config-file-reference.html) for the full list of currently-supported options. +- oxfmt supports an `--lsp` flag to spin up a Language Server Protocol server, but editor/IDE integration is still being developed and has not been tested/documented yet for most editors. +- See [the oxfmt FAQ](/docs/guide/usage/formatter.html#faqs) for any other potential caveats or limitations you may need to consider. + +Many of these limitations will be addressed in the future, with the Beta or Stable releases of oxfmt. + +## Step 1: Upgrade Prettier to v3.7 + +This step is optional, but will make it easier to determine which differences between oxfmt and prettier are "real". + +To minimize the number of changes when migrating to oxfmt, you should upgrade Prettier to version 3.7 first and reformat all JS/TS files with it, as it is the latest release of Prettier (from Nov 2025) and will be most similar to the output of oxfmt. + +## Step 2: Install oxfmt + +Install oxfmt as a development dependency with your package manager of choice: + +::: code-group + +```bash [npm] +$ npm add -D oxfmt@latest +``` + +```bash [pnpm] +$ pnpm add -D oxfmt@latest +``` + +```bash [yarn] +$ yarn add -D oxfmt@latest +``` + +```bash [bun] +$ bun add -D oxfmt@latest +``` + +```bash [deno] +$ deno add -D npm:oxfmt@latest +``` + +::: + +## Step 3: Migrate Prettier configuration file + +`.oxfmtrc.jsonc` is the configuration file for oxfmt. Only JSON files are supported. + +A basic .oxfmtrc.jsonc file looks like this: + +```jsonc +{ + "$schema": "./node_modules/oxfmt/configuration_schema.json", + "singleQuote": false, + "printWidth": 100, +} +``` + +If you have a basic `.prettierrc` file, you can simply rename the file with `mv .prettierrc .oxfmtrc.jsonc`. + +If you are using YAML or JavaScript to configure Prettier, you will need to convert the configuration to JSON format manually, although for simple configs this should be trivial. + +### `prettierrc.js` + +Here's an example of migrating a `prettierrc.js` file. + +Before: + +```js +module.exports = { + singleQuote: true, + jsxSingleQuote: true, +}; +``` + +After (`.oxfmtrc.jsonc`): + +```jsonc +{ + "$schema": "./node_modules/oxfmt/configuration_schema.json", + "singleQuote": true, + "jsxSingleQuote": true, + "printWidth": 80, +} +``` + +### `prettierrc.yaml` + +Here's an example of migrating a `prettierrc.yaml` file. + +Before: + +```yaml +trailingComma: "es5" +tabWidth: 4 +semi: false +singleQuote: true +``` + +After (`.oxfmtrc.jsonc`): + +```jsonc +{ + "$schema": "./node_modules/oxfmt/configuration_schema.json", + "trailingComma": "es5", + "tabWidth": 4, + "semi": false, + "singleQuote": true, + "printWidth": 80, +} +``` + +## Step 4: Update Formatting Scripts + +Update any formatting scripts you currently have, for example in `package.json`, shell scripts, or pre-commit scripts. + +### `package.json` scripts + +Before: + +```json +{ + "scripts": { + "format": "prettier --write .", + "format:check": "prettier --check ." + } +} +``` + +After: + +```json +{ + "scripts": { + "format": "oxfmt", + "format:check": "oxfmt --check" + } +} +``` + +### CI Workflows + +Update any CI workflows that run Prettier, particularly `prettier --check`. + +Before: + +```yaml +- name: Check formatting + run: yarn prettier --check . +``` + +After: + +```yaml +- name: Check formatting + run: yarn oxfmt --check +``` + +### Git Hooks (e.g. husky, lint-staged) + +Before: + +```json +"lint-staged": { + "*": "prettier --write" +} +``` + +After: + +```json +"lint-staged": { + "*": "oxfmt --no-error-on-unmatched-pattern" +} +``` + +## Step 5: Run formatter + +Run oxfmt on your codebase to check for any changes and ensure that the configuration was migrated correctly: + +**TODO: Add code blocks for other pkg managers.** + +`yarn oxfmt` (or `npm run oxfmt`, etc.) + +## Step 6: Uninstall Prettier (optional) + +If you no longer need Prettier, you can uninstall it: + +**TODO: Add code blocks for other pkg managers.** + +`yarn remove prettier`, etc. + +## Step 7: Done! + +You have now migrated to oxfmt :) + +Please see the section below for any additional, optional steps you may need to take. + +### Miscellaneous migration steps + +These are only applicable for some setups, so skip them if they don't apply to you. + +#### Update editor integrations + +**TODO: Clarify the status of VS Code integration, and also add a note for potentially using oxfmt in JetBrains IDEs + others via the LSP server.** + +**Note that the oxc VS Code extension includes oxfmt support, but it is experimental and incomplete**. It may not fully work yet, so please be mindful of this before migrating. + +If you have any editor integrations for Prettier, update them to use oxfmt instead. For example, update `.vscode/settings.json` to use oxfmt: + +Before: + +```json +{ + "editor.defaultFormatter": "esbenp.prettier-vscode" +} +``` + +After: + +```json +{ + "editor.defaultFormatter": "oxc.oxc-vscode" +} +``` + +And update `.vscode/extensions.json` to recommend the oxc extension instead of Prettier. + +Before: + +```json +{ + "recommendations": [ + "esbenp.prettier-vscode" + ] +} +``` + +After: + +```json +{ + "recommendations": [ + "oxc.oxc-vscode" + ] +} +``` + +#### Update CONTRIBUTING.md + +If you have a CONTRIBUTING.md file that references Prettier, update those references to use oxfmt. + +#### Update AGENTS.md/CLAUDE.md + +If you use an AGENTS.md or CLAUDE.md file, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference oxfmt and oxfmt's CLI commands instead. + +#### Update lint rules + +If you have any lint rules that check for Prettier formatting (e.g. `eslint-plugin-prettier`), you should remove them. + +While you're at it, you could also consider migrating to oxlint ;) + +#### Create/update `.git-blame-ignore-revs` + +If you want to avoid extra noise in your `git blame` history, you can add the commit SHA where you reformatted files using oxfmt to your `.git-blame-ignore-revs` file. This will make `git blame` ignore that commit when showing blame information. This file is supported natively by git, and by both GitHub and GitLab. From 28a58b57e62711496dbbcb1b3740e3a653cd0d3e Mon Sep 17 00:00:00 2001 From: Yuji Sugiura Date: Tue, 2 Dec 2025 15:01:11 +0900 Subject: [PATCH 2/9] Up --- .../usage/formatter/migrate-from-prettier.md | 150 +++++++----------- 1 file changed, 55 insertions(+), 95 deletions(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index d8e65beba1..ecd53d38a5 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -1,53 +1,55 @@ -# Migrating from Prettier to oxfmt +# Migrating from Prettier to Oxfmt -If you currently use Prettier as your code formatter, you can follow this guide to migrate to oxfmt. +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. +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. -## Caveats for migrating to oxfmt +## 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 3.7 already for basic configurations, but less-common config options and other features are not yet implemented. +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. -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. +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. -Other important considerations when migrating from Prettier to oxfmt: +Other important considerations when migrating from Prettier to Oxfmt: -- oxfmt's formatting output is closest to Prettier v3.7. If you are using an older version of Prettier, you will see more differences in formatting output. -- oxfmt aims to be mostly compatible with Prettier out-of-the-box, but there may still be some minor differences in formatting output in edge-cases. -- oxfmt uses a `printWidth` of 100 characters by default, whereas Prettier's default is 80. If your Prettier configuration does not set the `printWidth` setting explicitly, you should make sure to set `"printWidth": 80` in your oxfmt config file to minimize differences. +- Oxfmt's formatting output is closest to Prettier v3.7. If you are using an older version of Prettier, you will see more differences in formatting output. +- Oxfmt aims to be mostly compatible with Prettier out-of-the-box, but there may still be some minor differences in formatting output in edge-cases. +- Oxfmt uses a `printWidth` of 100 characters by default, whereas Prettier's default is 80. If your Prettier configuration does not set the `printWidth` setting explicitly, you should make sure to set `"printWidth": 80` in your Oxfmt config file to minimize differences. - Prettier plugins are not yet supported. - Some Prettier options are not supported. See the [oxfmt CLI documentation](/docs/guide/usage/formatter/config-file-reference.html) for the full list of currently-supported options. -- oxfmt supports an `--lsp` flag to spin up a Language Server Protocol server, but editor/IDE integration is still being developed and has not been tested/documented yet for most editors. -- See [the oxfmt FAQ](/docs/guide/usage/formatter.html#faqs) for any other potential caveats or limitations you may need to consider. +- Oxfmt supports an `--lsp` flag to spin up a Language Server Protocol server, but editor/IDE integration is still being developed and has not been tested/documented yet for most editors. -Many of these limitations will be addressed in the future, with the Beta or Stable releases of oxfmt. +Many of these limitations will be addressed in the future, with the Beta or Stable releases of Oxfmt. -## Step 1: Upgrade Prettier to v3.7 +See also [the Oxfmt FAQ](/docs/guide/usage/formatter.html#faqs) for any other potential caveats or limitations you may need to consider. -This step is optional, but will make it easier to determine which differences between oxfmt and prettier are "real". +## Step 1: Upgrade Prettier to v3.7 (Optional) -To minimize the number of changes when migrating to oxfmt, you should upgrade Prettier to version 3.7 first and reformat all JS/TS files with it, as it is the latest release of Prettier (from Nov 2025) and will be most similar to the output of oxfmt. +This step is optional, but will make it easier to determine which differences between Oxfmt and prettier are "real". -## Step 2: Install oxfmt +To minimize the number of changes when migrating to Oxfmt, you should upgrade Prettier to version 3.7 first and reformat all JS/TS files with it, as it is the latest release of Prettier (from Nov 2025) and will be most similar to the output of Oxfmt. -Install oxfmt as a development dependency with your package manager of choice: +## Step 2: Install Oxfmt + +Install Oxfmt as a development dependency with your package manager of choice: ::: code-group ```bash [npm] -$ npm add -D oxfmt@latest +$ npm add -D Oxfmt@latest ``` ```bash [pnpm] -$ pnpm add -D oxfmt@latest +$ pnpm add -D Oxfmt@latest ``` ```bash [yarn] -$ yarn add -D oxfmt@latest +$ yarn add -D Oxfmt@latest ``` ```bash [bun] -$ bun add -D oxfmt@latest +$ bun add -D Oxfmt@latest ``` ```bash [deno] @@ -58,15 +60,14 @@ $ deno add -D npm:oxfmt@latest ## Step 3: Migrate Prettier configuration file -`.oxfmtrc.jsonc` is the configuration file for oxfmt. Only JSON files are supported. +`.oxfmtrc.jsonc` is the configuration file for Oxfmt. Only JSON files are supported. -A basic .oxfmtrc.jsonc file looks like this: +A basic `.oxfmtrc.jsonc` file looks like this: ```jsonc { "$schema": "./node_modules/oxfmt/configuration_schema.json", - "singleQuote": false, - "printWidth": 100, + "printWidth": 80, } ``` @@ -130,24 +131,13 @@ Update any formatting scripts you currently have, for example in `package.json`, ### `package.json` scripts -Before: - -```json +```diff { "scripts": { - "format": "prettier --write .", - "format:check": "prettier --check ." - } -} -``` - -After: - -```json -{ - "scripts": { - "format": "oxfmt", - "format:check": "oxfmt --check" +- "format": "prettier --write .", ++ "format": "oxfmt", +- "format:check": "prettier --check ." ++ "format:check": "oxfmt --check" } } ``` @@ -156,41 +146,24 @@ After: Update any CI workflows that run Prettier, particularly `prettier --check`. -Before: - -```yaml -- name: Check formatting - run: yarn prettier --check . -``` - -After: - -```yaml -- name: Check formatting - run: yarn oxfmt --check +```diff + - name: Check formatting +- run: yarn prettier --check . ++ run: yarn oxfmt --check ``` ### Git Hooks (e.g. husky, lint-staged) -Before: - -```json +```diff "lint-staged": { - "*": "prettier --write" -} -``` - -After: - -```json -"lint-staged": { - "*": "oxfmt --no-error-on-unmatched-pattern" +- "*": "prettier --write --no-error-on-unmatched-pattern" ++ "*": "oxfmt --no-error-on-unmatched-pattern" } ``` ## Step 5: Run formatter -Run oxfmt on your codebase to check for any changes and ensure that the configuration was migrated correctly: +Run Oxfmt on your codebase to check for any changes and ensure that the configuration was migrated correctly: **TODO: Add code blocks for other pkg managers.** @@ -206,21 +179,19 @@ If you no longer need Prettier, you can uninstall it: ## Step 7: Done! -You have now migrated to oxfmt :) +You have now migrated to Oxfmt :) Please see the section below for any additional, optional steps you may need to take. -### Miscellaneous migration steps - These are only applicable for some setups, so skip them if they don't apply to you. -#### Update editor integrations +### Update editor integrations -**TODO: Clarify the status of VS Code integration, and also add a note for potentially using oxfmt in JetBrains IDEs + others via the LSP server.** +**TODO: Clarify the status of VS Code integration, and also add a note for potentially using Oxfmt in JetBrains IDEs + others via the LSP server.** -**Note that the oxc VS Code extension includes oxfmt support, but it is experimental and incomplete**. It may not fully work yet, so please be mindful of this before migrating. +**Note that the oxc VS Code extension includes Oxfmt support, but it is experimental and incomplete**. It may not fully work yet, so please be mindful of this before migrating. -If you have any editor integrations for Prettier, update them to use oxfmt instead. For example, update `.vscode/settings.json` to use oxfmt: +If you have any editor integrations for Prettier, update them to use Oxfmt instead. For example, update `.vscode/settings.json` to use Oxfmt: Before: @@ -240,40 +211,29 @@ After: And update `.vscode/extensions.json` to recommend the oxc extension instead of Prettier. -Before: - -```json -{ - "recommendations": [ - "esbenp.prettier-vscode" - ] -} -``` - -After: - -```json +```diff { "recommendations": [ - "oxc.oxc-vscode" +- "esbenp.prettier-vscode" ++ "oxc.oxc-vscode" ] } ``` -#### Update CONTRIBUTING.md +### Update `CONTRIBUTING.md` -If you have a CONTRIBUTING.md file that references Prettier, update those references to use oxfmt. +If you have a `CONTRIBUTING.md` file that references Prettier, update those references to use Oxfmt. -#### Update AGENTS.md/CLAUDE.md +### Update `AGENTS.md`/`CLAUDE.md` -If you use an AGENTS.md or CLAUDE.md file, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference oxfmt and oxfmt's CLI commands instead. +If you use an `AGENTS.md` or `CLAUDE.md` file, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference Oxfmt and Oxfmt's CLI commands instead. -#### Update lint rules +### Update lint rules If you have any lint rules that check for Prettier formatting (e.g. `eslint-plugin-prettier`), you should remove them. While you're at it, you could also consider migrating to oxlint ;) -#### Create/update `.git-blame-ignore-revs` +### Create/update `.git-blame-ignore-revs` -If you want to avoid extra noise in your `git blame` history, you can add the commit SHA where you reformatted files using oxfmt to your `.git-blame-ignore-revs` file. This will make `git blame` ignore that commit when showing blame information. This file is supported natively by git, and by both GitHub and GitLab. +If you want to avoid extra noise in your `git blame` history, you can add the commit SHA where you reformatted files using Oxfmt to your `.git-blame-ignore-revs` file. This will make `git blame` ignore that commit when showing blame information. This file is supported natively by git, and by both GitHub and GitLab. From 0c619f14128fe9b05371d2f0b33efa23209ea4ca Mon Sep 17 00:00:00 2001 From: Yuji Sugiura Date: Tue, 2 Dec 2025 15:03:40 +0900 Subject: [PATCH 3/9] Add link --- src/docs/guide/usage/formatter/migrate-from-prettier.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index ecd53d38a5..fac428b3d3 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -5,6 +5,9 @@ If you currently use Prettier as your code formatter, you can follow this guide 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. From fe04cefce140fd278f610fe89a4c08be9d31cf6c Mon Sep 17 00:00:00 2001 From: Yuji Sugiura Date: Tue, 2 Dec 2025 15:07:54 +0900 Subject: [PATCH 4/9] Fix case --- src/docs/guide/usage/formatter/migrate-from-prettier.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index fac428b3d3..06b85839ba 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -40,19 +40,19 @@ Install Oxfmt as a development dependency with your package manager of choice: ::: code-group ```bash [npm] -$ npm add -D Oxfmt@latest +$ npm add -D oxfmt@latest ``` ```bash [pnpm] -$ pnpm add -D Oxfmt@latest +$ pnpm add -D oxfmt@latest ``` ```bash [yarn] -$ yarn add -D Oxfmt@latest +$ yarn add -D oxfmt@latest ``` ```bash [bun] -$ bun add -D Oxfmt@latest +$ bun add -D oxfmt@latest ``` ```bash [deno] From c94390e3417c75a6d834411c452cbced4b1d5a7c Mon Sep 17 00:00:00 2001 From: Yuji Sugiura Date: Tue, 2 Dec 2025 15:14:22 +0900 Subject: [PATCH 5/9] Shorten heading --- .../usage/formatter/migrate-from-prettier.md | 32 ++++++------------- 1 file changed, 9 insertions(+), 23 deletions(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index 06b85839ba..ecb5dce6eb 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -168,19 +168,14 @@ Update any CI workflows that run Prettier, particularly `prettier --check`. Run Oxfmt on your codebase to check for any changes and ensure that the configuration was migrated correctly: -**TODO: Add code blocks for other pkg managers.** - -`yarn oxfmt` (or `npm run oxfmt`, etc.) - -## Step 6: Uninstall Prettier (optional) - -If you no longer need Prettier, you can uninstall it: - -**TODO: Add code blocks for other pkg managers.** +```sh +# Your script specified in Step 4 +npm run format +``` -`yarn remove prettier`, etc. +If you no longer need Prettier, you can uninstall for now. -## Step 7: Done! +## Done! You have now migrated to Oxfmt :) @@ -196,19 +191,10 @@ These are only applicable for some setups, so skip them if they don't apply to y If you have any editor integrations for Prettier, update them to use Oxfmt instead. For example, update `.vscode/settings.json` to use Oxfmt: -Before: - -```json -{ - "editor.defaultFormatter": "esbenp.prettier-vscode" -} -``` - -After: - -```json +```diff { - "editor.defaultFormatter": "oxc.oxc-vscode" +- "editor.defaultFormatter": "esbenp.prettier-vscode" ++ "editor.defaultFormatter": "oxc.oxc-vscode" } ``` From 01229a1a37a086def2dac74d4165f7b6eb17d91c Mon Sep 17 00:00:00 2001 From: Yuji Sugiura <6259812+leaysgur@users.noreply.github.com> Date: Tue, 2 Dec 2025 15:18:15 +0900 Subject: [PATCH 6/9] Update src/docs/guide/usage/formatter/migrate-from-prettier.md Co-authored-by: Connor Shea Signed-off-by: Yuji Sugiura <6259812+leaysgur@users.noreply.github.com> --- src/docs/guide/usage/formatter/migrate-from-prettier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index ecb5dce6eb..caf8cc6800 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -215,7 +215,7 @@ If you have a `CONTRIBUTING.md` file that references Prettier, update those refe ### Update `AGENTS.md`/`CLAUDE.md` -If you use an `AGENTS.md` or `CLAUDE.md` file, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference Oxfmt and Oxfmt's CLI commands instead. +If you use an `AGENTS.md` or `CLAUDE.md` file to help LLM tools understand your codebase, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference Oxfmt and Oxfmt's CLI commands instead. ### Update lint rules From f01d8807ac11f62a7bab88ebd9a410b0756f517d Mon Sep 17 00:00:00 2001 From: Yuji Sugiura <6259812+leaysgur@users.noreply.github.com> Date: Tue, 2 Dec 2025 15:18:38 +0900 Subject: [PATCH 7/9] Update src/docs/guide/usage/formatter/migrate-from-prettier.md Co-authored-by: Connor Shea Signed-off-by: Yuji Sugiura <6259812+leaysgur@users.noreply.github.com> --- src/docs/guide/usage/formatter/migrate-from-prettier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index caf8cc6800..08a41f0138 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -29,7 +29,7 @@ See also [the Oxfmt FAQ](/docs/guide/usage/formatter.html#faqs) for any other po ## Step 1: Upgrade Prettier to v3.7 (Optional) -This step is optional, but will make it easier to determine which differences between Oxfmt and prettier are "real". +This step is optional, but will make it easier to determine which differences between Oxfmt and Prettier are "real". To minimize the number of changes when migrating to Oxfmt, you should upgrade Prettier to version 3.7 first and reformat all JS/TS files with it, as it is the latest release of Prettier (from Nov 2025) and will be most similar to the output of Oxfmt. From 241d895a195982027e05fc889c059f4cbe0f28ba Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Sat, 6 Dec 2025 17:35:10 -0700 Subject: [PATCH 8/9] Simplify the migration page. Replace the editor section with a link to the FAQ. Simplify the page about migrating and remove some less-relevant parts. --- .../usage/formatter/migrate-from-prettier.md | 37 ++++--------------- 1 file changed, 8 insertions(+), 29 deletions(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index 08a41f0138..34b23d84e2 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -12,13 +12,14 @@ For the beta milestone, we may provide migration commands. 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. + + 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. Other important considerations when migrating from Prettier to Oxfmt: -- Oxfmt's formatting output is closest to Prettier v3.7. If you are using an older version of Prettier, you will see more differences in formatting output. -- Oxfmt aims to be mostly compatible with Prettier out-of-the-box, but there may still be some minor differences in formatting output in edge-cases. -- Oxfmt uses a `printWidth` of 100 characters by default, whereas Prettier's default is 80. If your Prettier configuration does not set the `printWidth` setting explicitly, you should make sure to set `"printWidth": 80` in your Oxfmt config file to minimize differences. +- Oxfmt's formatting output is closest to Prettier v3.7. You will see more differences migrating from an older version of Prettier. +- Oxfmt uses a `printWidth` of 100 characters by default, whereas Prettier's default is 80. Make sure to set `"printWidth": 80` in `.oxfmtrc.jsonc` to minimize differences if you use the Prettier default. - Prettier plugins are not yet supported. - Some Prettier options are not supported. See the [oxfmt CLI documentation](/docs/guide/usage/formatter/config-file-reference.html) for the full list of currently-supported options. - Oxfmt supports an `--lsp` flag to spin up a Language Server Protocol server, but editor/IDE integration is still being developed and has not been tested/documented yet for most editors. @@ -76,7 +77,7 @@ A basic `.oxfmtrc.jsonc` file looks like this: If you have a basic `.prettierrc` file, you can simply rename the file with `mv .prettierrc .oxfmtrc.jsonc`. -If you are using YAML or JavaScript to configure Prettier, you will need to convert the configuration to JSON format manually, although for simple configs this should be trivial. +If you are using something other than JSON to configure Prettier, you will need to convert the configuration to JSON. ### `prettierrc.js` @@ -185,29 +186,7 @@ These are only applicable for some setups, so skip them if they don't apply to y ### Update editor integrations -**TODO: Clarify the status of VS Code integration, and also add a note for potentially using Oxfmt in JetBrains IDEs + others via the LSP server.** - -**Note that the oxc VS Code extension includes Oxfmt support, but it is experimental and incomplete**. It may not fully work yet, so please be mindful of this before migrating. - -If you have any editor integrations for Prettier, update them to use Oxfmt instead. For example, update `.vscode/settings.json` to use Oxfmt: - -```diff -{ -- "editor.defaultFormatter": "esbenp.prettier-vscode" -+ "editor.defaultFormatter": "oxc.oxc-vscode" -} -``` - -And update `.vscode/extensions.json` to recommend the oxc extension instead of Prettier. - -```diff -{ - "recommendations": [ -- "esbenp.prettier-vscode" -+ "oxc.oxc-vscode" - ] -} -``` +See [the Formatter FAQ](../formatter.md#how-does-editor-integration-work') for details on editor/IDE integration with Oxfmt. ### Update `CONTRIBUTING.md` @@ -219,9 +198,9 @@ If you use an `AGENTS.md` or `CLAUDE.md` file to help LLM tools understand your ### Update lint rules -If you have any lint rules that check for Prettier formatting (e.g. `eslint-plugin-prettier`), you should remove them. +If you have any lint rules that explicitly check for Prettier formatting (e.g. `eslint-plugin-prettier`), you should remove them. -While you're at it, you could also consider migrating to oxlint ;) +While you're at it, you could also consider migrating to [oxlint](../linter.md) ;) ### Create/update `.git-blame-ignore-revs` From 1b6613d8e424e37c1fad15ca223daaca966967ae Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Sat, 6 Dec 2025 17:37:00 -0700 Subject: [PATCH 9/9] Simplify another section. --- src/docs/guide/usage/formatter/migrate-from-prettier.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/docs/guide/usage/formatter/migrate-from-prettier.md b/src/docs/guide/usage/formatter/migrate-from-prettier.md index 34b23d84e2..1bdcc16911 100644 --- a/src/docs/guide/usage/formatter/migrate-from-prettier.md +++ b/src/docs/guide/usage/formatter/migrate-from-prettier.md @@ -188,13 +188,11 @@ These are only applicable for some setups, so skip them if they don't apply to y See [the Formatter FAQ](../formatter.md#how-does-editor-integration-work') for details on editor/IDE integration with Oxfmt. -### Update `CONTRIBUTING.md` +### Update `CONTRIBUTING.md` and `AGENTS.md`/`CLAUDE.md` If you have a `CONTRIBUTING.md` file that references Prettier, update those references to use Oxfmt. -### Update `AGENTS.md`/`CLAUDE.md` - -If you use an `AGENTS.md` or `CLAUDE.md` file to help LLM tools understand your codebase, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference Oxfmt and Oxfmt's CLI commands instead. +If you use an `AGENTS.md` or `CLAUDE.md` file to help LLM tools understand your codebase, you should also check for references to Prettier in those files. ### Update lint rules