Skip to content

Commit 1146d72

Browse files
LGLabGregLGLabGreg
committed
chore: migrate to oxc
1 parent 0be5c2e commit 1146d72

42 files changed

Lines changed: 2096 additions & 4025 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/migrate-oxfmt/SKILL.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
name: migrate-oxfmt
3+
description: Guide for migrating a project from Prettier or Biome to Oxfmt. Use when asked to migrate, convert, or switch a JavaScript/TypeScript project's formatter from Prettier or Biome to Oxfmt.
4+
---
5+
6+
This skill guides you through migrating a JavaScript/TypeScript project from Prettier or Biome to [Oxfmt](https://oxc.rs/docs/guide/usage/formatter).
7+
8+
## Overview
9+
10+
Oxfmt is a high-performance, Prettier-compatible code formatter. Most Prettier options are supported directly.
11+
12+
An automated migration tool is built into oxfmt, supporting both Prettier and Biome as migration sources.
13+
14+
## Step 1: Run Automated Migration
15+
16+
### From Prettier
17+
18+
```bash
19+
npx oxfmt@latest --migrate prettier
20+
```
21+
22+
This will:
23+
24+
- Find and read your Prettier config (any format Prettier supports)
25+
- Create `.oxfmtrc.json` with migrated options
26+
- Migrate `.prettierignore` patterns to `ignorePatterns`
27+
- Migrate `prettier-plugin-tailwindcss` options to `sortTailwindcss`
28+
- Detect `prettier-plugin-packagejson` and enable `sortPackageJson`
29+
30+
### From Biome
31+
32+
```bash
33+
npx oxfmt@latest --migrate biome
34+
```
35+
36+
This will:
37+
38+
- Find and read `biome.json` or `biome.jsonc`
39+
- Create `.oxfmtrc.json` with migrated options
40+
- Migrate negated patterns from `files.includes` to `ignorePatterns`
41+
- Map Biome's two-level config (`formatter.*` and `javascript.formatter.*`) to oxfmt options
42+
43+
Biome option mapping:
44+
45+
| Biome | oxfmt |
46+
| ----------------------------------------------------------- | --------------------------------- |
47+
| `formatter.indentStyle` (`"tab"`/`"space"`) | `useTabs` (`true`/`false`) |
48+
| `formatter.indentWidth` | `tabWidth` |
49+
| `formatter.lineWidth` | `printWidth` |
50+
| `javascript.formatter.quoteStyle` | `singleQuote` |
51+
| `javascript.formatter.jsxQuoteStyle` | `jsxSingleQuote` |
52+
| `javascript.formatter.quoteProperties` (`"asNeeded"`) | `quoteProps` (`"as-needed"`) |
53+
| `javascript.formatter.trailingCommas` | `trailingComma` |
54+
| `javascript.formatter.semicolons` (`"always"`/`"asNeeded"`) | `semi` (`true`/`false`) |
55+
| `javascript.formatter.arrowParentheses` (`"asNeeded"`) | `arrowParens` (`"avoid"`) |
56+
| `formatter.bracketSameLine` | `bracketSameLine` |
57+
| `formatter.bracketSpacing` | `bracketSpacing` |
58+
| `formatter.attributePosition` (`"multiline"`) | `singleAttributePerLine` (`true`) |
59+
60+
Notes (both sources):
61+
62+
- Fails if `.oxfmtrc.json` already exists. Delete it first if you want to re-run.
63+
- If no source config is found, creates a blank `.oxfmtrc.json` instead.
64+
- `overrides` cannot be auto-migrated for either source and must be converted manually.
65+
66+
## Step 2: Review Generated Config
67+
68+
After migration, review the generated `.oxfmtrc.json` for these key differences:
69+
70+
### printWidth
71+
72+
Prettier and Biome default is 80, oxfmt default is 100. The migration tool sets `printWidth: 80` if not specified in your source config. Decide whether to keep 80 or adopt 100.
73+
74+
### Unsupported Options (Prettier only)
75+
76+
These Prettier options are skipped during migration:
77+
78+
| Option | Status |
79+
| ------------------------------ | ------------------------------------------------ |
80+
| `endOfLine: "auto"` | Not supported. Use `"lf"` or `"crlf"` explicitly |
81+
| `experimentalTernaries` | Not supported in JS/TS files yet |
82+
| `experimentalOperatorPosition` | Not supported in JS/TS files yet |
83+
84+
### sortPackageJson (Prettier only)
85+
86+
Enabled by default in oxfmt, but the migration tool disables it unless `prettier-plugin-packagejson` was detected. Review whether you want this enabled.
87+
88+
Note: Oxfmt's sorting algorithm differs from `prettier-plugin-packagejson`.
89+
90+
### embeddedLanguageFormatting (Prettier only)
91+
92+
Embedded language formatting (e.g., CSS-in-JS) generally works, but some formatting may differ from Prettier.
93+
94+
### overrides
95+
96+
The `overrides` field cannot be auto-migrated from either Prettier or Biome. Convert manually:
97+
98+
```json
99+
{
100+
"overrides": [
101+
{
102+
"files": ["*.md"],
103+
"options": { "tabWidth": 4 }
104+
}
105+
]
106+
}
107+
```
108+
109+
### Nested Config
110+
111+
Oxfmt does not support nested configuration files (e.g., a separate `.oxfmtrc.json` in a subdirectory). If your project used per-directory Prettier or Biome configs, consolidate them using `overrides` with file glob patterns, or run oxfmt separately per directory with different working directories.
112+
113+
### Prettier-Compatible Options
114+
115+
These options transfer directly with the same behavior:
116+
`tabWidth`, `useTabs`, `semi`, `singleQuote`, `jsxSingleQuote`, `quoteProps`, `trailingComma`, `arrowParens`, `bracketSpacing`, `bracketSameLine`, `endOfLine`, `proseWrap`, `htmlWhitespaceSensitivity`, `singleAttributePerLine`, `vueIndentScriptAndStyle`
117+
118+
## Step 3: Configure Oxfmt Extensions
119+
120+
Oxfmt offers features not available in Prettier:
121+
122+
### sortImports
123+
124+
Sort import statements, inspired by `eslint-plugin-perfectionist/sort-imports` (disabled by default):
125+
126+
```json
127+
{
128+
"sortImports": {
129+
"partitionByNewline": true,
130+
"newlinesBetween": false
131+
}
132+
}
133+
```
134+
135+
### sortTailwindcss
136+
137+
Replaces `prettier-plugin-tailwindcss`. Auto-migrated with renamed options:
138+
139+
| Prettier (top-level) | oxfmt (`sortTailwindcss.*`) |
140+
| ---------------------------- | --------------------------- |
141+
| `tailwindConfig` | `config` |
142+
| `tailwindStylesheet` | `stylesheet` |
143+
| `tailwindFunctions` | `functions` |
144+
| `tailwindAttributes` | `attributes` |
145+
| `tailwindPreserveWhitespace` | `preserveWhitespace` |
146+
| `tailwindPreserveDuplicates` | `preserveDuplicates` |
147+
148+
### Other Extensions
149+
150+
| Option | Default | Description |
151+
| -------------------- | ------- | ---------------------------------------------------------------------------- |
152+
| `insertFinalNewline` | `true` | Whether to add a final newline at end of file |
153+
| `sortPackageJson` | `true` | Sort `package.json` keys. Set `{ "sortScripts": true }` to also sort scripts |
154+
155+
## Step 4: Update CI and Scripts
156+
157+
Replace formatter commands with oxfmt:
158+
159+
```bash
160+
# Before (Prettier)
161+
npx prettier --write .
162+
npx prettier --check .
163+
164+
# Before (Biome)
165+
npx biome format --write .
166+
npx biome check .
167+
168+
# After
169+
npx oxfmt@latest
170+
npx oxfmt@latest --check
171+
```
172+
173+
### Common CLI Options
174+
175+
| Prettier / Biome | oxfmt |
176+
| ----------------------------------------------- | -------------------------------------------- |
177+
| `prettier --write .` / `biome format --write .` | `oxfmt` (default: cwd, `--write` mode) |
178+
| `prettier --check .` / `biome check .` | `oxfmt --check` |
179+
| `prettier --list-different .` | `oxfmt --list-different` |
180+
| `prettier --config path` | `oxfmt --config path` |
181+
| `prettier --ignore-path .prettierignore` | `oxfmt --ignore-path .prettierignore` |
182+
| `cat file \| prettier --stdin-filepath=file.ts` | `cat file \| oxfmt --stdin-filepath=file.ts` |
183+
184+
### File Type Coverage
185+
186+
- JS/TS: Formatted natively by oxfmt
187+
- TOML: Formatted natively (via taplo)
188+
- CSS, HTML, YAML, Markdown, GraphQL, etc.: Delegated to Prettier internally (when using `npx oxfmt`)
189+
190+
## Tips
191+
192+
- EditorConfig: Oxfmt reads `.editorconfig` automatically for `useTabs`, `tabWidth`, `endOfLine`, `insertFinalNewline`, and `printWidth`. Options in `.oxfmtrc.json` take precedence.
193+
- CI: Use `npx oxfmt@latest --check` to enforce formatting in CI.
194+
- LSP: Run `oxfmt --lsp` for editor integration via Language Server Protocol.
195+
- Schema support: Add `"$schema": "./node_modules/oxfmt/configuration_schema.json"` to `.oxfmtrc.json` for editor autocompletion.
196+
- Init: Run `npx oxfmt@latest --init` to create a default `.oxfmtrc.json` without migration.
197+
198+
## References
199+
200+
- [CLI Reference](https://oxc.rs/docs/guide/usage/formatter/cli.html)
201+
- [Config File Reference](https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html)
202+
- [Unsupported Features](https://oxc.rs/docs/guide/usage/formatter/unsupported-features.html)

‎.agents/skills/migrate-oxlint/SKILL.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
name: migrate-oxlint
3+
description: Guide for migrating a project from ESLint to Oxlint. Use when asked to migrate, convert, or switch a JavaScript/TypeScript project's linter from ESLint to Oxlint.
4+
---
5+
6+
This skill guides you through migrating a JavaScript/TypeScript project from ESLint to [Oxlint](https://oxc.rs/docs/guide/usage/linter/).
7+
8+
## Overview
9+
10+
Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.
11+
12+
An official migration tool is available: [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate)
13+
14+
## Step 1: Run Automated Migration
15+
16+
Run the migration tool in the project root:
17+
18+
```bash
19+
npx @oxlint/migrate
20+
```
21+
22+
This reads your ESLint flat config and generates a `.oxlintrc.json` file.
23+
24+
### Key Options
25+
26+
| Option | Description |
27+
| --------------------------- | ------------------------------------------------------------------------- |
28+
| `--merge` | Merge with an existing `.oxlintrc.json` instead of overwriting |
29+
| `--type-aware` | Include type-aware rules (requires running oxlint with `--type-aware`) |
30+
| `--with-nursery` | Include experimental rules still under development |
31+
| `--js-plugins [bool]` | Enable/disable ESLint plugin migration via `jsPlugins` (default: enabled) |
32+
| `--details` | List rules that could not be migrated |
33+
| `--replace-eslint-comments` | Convert `// eslint-disable` comments to `// oxlint-disable` |
34+
| `--output-file <file>` | Specify output path (default: `.oxlintrc.json`) |
35+
36+
If your ESLint config is not at the default location, pass the path explicitly:
37+
38+
```bash
39+
npx @oxlint/migrate ./path/to/eslint.config.js
40+
```
41+
42+
## Step 2: Review Generated Config
43+
44+
After migration, review the generated `.oxlintrc.json`.
45+
46+
### Plugin Mapping
47+
48+
The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:
49+
50+
| ESLint Plugin | Oxlint Plugin Name |
51+
| --------------------------------------------------- | ------------------ |
52+
| `@typescript-eslint/eslint-plugin` | `typescript` |
53+
| `eslint-plugin-react` / `eslint-plugin-react-hooks` | `react` |
54+
| `eslint-plugin-import` / `eslint-plugin-import-x` | `import` |
55+
| `eslint-plugin-unicorn` | `unicorn` |
56+
| `eslint-plugin-jsx-a11y` | `jsx-a11y` |
57+
| `eslint-plugin-react-perf` | `react-perf` |
58+
| `eslint-plugin-promise` | `promise` |
59+
| `eslint-plugin-jest` | `jest` |
60+
| `@vitest/eslint-plugin` | `vitest` |
61+
| `eslint-plugin-jsdoc` | `jsdoc` |
62+
| `eslint-plugin-next` | `nextjs` |
63+
| `eslint-plugin-node` | `node` |
64+
| `eslint-plugin-vue` | `vue` |
65+
66+
Default plugins (enabled when `plugins` field is omitted): `unicorn`, `typescript`, `oxc`.
67+
Setting the `plugins` array explicitly overrides these defaults.
68+
69+
### Rule Categories
70+
71+
Oxlint groups rules into categories for bulk configuration:
72+
73+
```json
74+
{
75+
"categories": {
76+
"correctness": "warn",
77+
"suspicious": "warn"
78+
}
79+
}
80+
```
81+
82+
Available categories: `correctness` (default: enabled), `suspicious`, `pedantic`, `perf`, `style`, `restriction`, `nursery`.
83+
84+
Individual rule settings in `rules` override category settings.
85+
86+
### Check Unmigrated Rules
87+
88+
Run with `--details` to see which ESLint rules could not be migrated:
89+
90+
```bash
91+
npx @oxlint/migrate --details
92+
```
93+
94+
Review the output and decide whether to keep ESLint for those rules or find oxlint alternatives.
95+
96+
## Step 3: Handle Unsupported Features
97+
98+
Some features require manual attention:
99+
100+
- Local plugins (relative path imports): Must be migrated manually to `jsPlugins`
101+
- `eslint-plugin-prettier`: Not supported. Use [oxfmt](https://oxc.rs/docs/guide/usage/formatter) instead
102+
- `settings` in override configs: Oxlint does not support `settings` inside `overrides` blocks
103+
- ESLint v9+ plugins: Not all work with oxlint's JS Plugins API. Test with `--js-plugins`
104+
105+
### External ESLint Plugins
106+
107+
For ESLint plugins without a built-in oxlint equivalent, use the `jsPlugins` field to load them:
108+
109+
```json
110+
{
111+
"jsPlugins": ["eslint-plugin-custom"],
112+
"rules": {
113+
"custom/my-rule": "warn"
114+
}
115+
}
116+
```
117+
118+
## Step 4: Update CI and Scripts
119+
120+
Replace ESLint commands with oxlint. Path arguments are optional; oxlint defaults to the current working directory.
121+
122+
```bash
123+
# Before
124+
npx eslint src/
125+
npx eslint --fix src/
126+
127+
# After
128+
npx oxlint@latest
129+
npx oxlint@latest --fix
130+
```
131+
132+
### Common CLI Options
133+
134+
| ESLint | oxlint |
135+
| ------------------------- | ---------------------------------------------- |
136+
| `eslint .` | `oxlint` (default: cwd) |
137+
| `eslint src/` | `oxlint src/` |
138+
| `eslint --fix` | `oxlint --fix` |
139+
| `eslint --max-warnings 0` | `oxlint --deny-warnings` or `--max-warnings 0` |
140+
| `eslint --format json` | `oxlint --format json` |
141+
| `eslint -c config.json` | `oxlint --config config.json` |
142+
143+
Additional oxlint options:
144+
145+
- `--type-aware`: Enable rules requiring TypeScript type information
146+
- `--tsconfig <path>`: Specify tsconfig.json path for type-aware linting
147+
148+
## Tips
149+
150+
- Start gradually: Enable `correctness` rules first (the default), then progressively add `suspicious`, `pedantic`, etc.
151+
- Run alongside ESLint: Oxlint is designed to complement ESLint during migration. You can run both until all rules are covered.
152+
- Disable comments work: `// eslint-disable` and `// eslint-disable-next-line` comments are supported by oxlint. Use `--replace-eslint-comments` to convert them to `// oxlint-disable` if desired.
153+
- List available rules: Run `npx oxlint@latest --rules` to see all supported rules.
154+
- Schema support: Add `"$schema": "./node_modules/oxlint/configuration_schema.json"` to `.oxlintrc.json` for editor autocompletion.
155+
- Output formats: `default`, `stylish`, `json`, `github`, `gitlab`, `junit`, `checkstyle`, `unix`
156+
157+
## References
158+
159+
- [CLI Reference](https://oxc.rs/docs/guide/usage/linter/cli.html)
160+
- [Config File Reference](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html)

‎.claude/skills/migrate-oxfmt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.agents/skills/migrate-oxfmt

‎.claude/skills/migrate-oxlint‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.agents/skills/migrate-oxlint

0 commit comments

Comments
 (0)