Migrate from Biome to OXC + tsgo

This guide documents the exact migration path used in this repository.

TL;DR

1. Install OXC tooling: oxlint, oxfmt, oxlint-tsgolint.
2. Install tsgo preview: @typescript/native-preview.
3. Replace scripts (lint, format, check) to use OXC + tsgo.
4. Add oxlint.config.ts and oxfmt.json.
5. Remove root biome.json and Biome lint-staged hooks.
6. Keep typescript installed temporarily if astro check requires it.

Introduction

Biome works well, but OXC has first-class dedicated tools for linting and formatting, and tsgo unlocks native high-performance type-checking. This migration adopts those tools while keeping Astro compatibility.

Migration Steps

1. Install dependencies

pnpm add -D oxlint oxfmt oxlint-tsgolint @typescript/native-preview
pnpm remove @biomejs/biome

2. Add OXC configs

• Create oxlint.config.ts
• Create oxfmt.json
• Tune ignores (dist, .astro, snippets folder)
• Add overrides for script files (no-console: off in scripts/**)

3. Update npm scripts

package.json

{
  "scripts": {
    "lint": "oxlint .",
    "lint:fix": "oxlint --fix .",
    "format": "oxfmt --write",
    "format:check": "oxfmt --check",
    "typecheck": "astro check",
    "typecheck:tsgo": "tsgo --noEmit",
    "check": "pnpm lint:md && pnpm lint && pnpm format:check && pnpm typecheck && pnpm style:lint"
  }
}

4. Update lint-staged

Replace Biome command with OXC commands:

.lintstagedrc.json

{
  "*.{js,jsx,ts,tsx,mjs,cjs,json,jsonc}": ["oxlint --fix", "oxfmt --write"]
}

5. Update TypeScript config for TS 6/7 compatibility

• Remove deprecated baseUrl
• Inline path mapping roots
• Keep paths relative to config file

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

6. Update editor settings

In .vscode/settings.json:

• source.fixAll.biome → source.fixAll.oxc
• default formatter → oxc.oxfmt-vscode

Compatibility Notes

• astro check currently requires the typescript package.
• This means full removal of TypeScript 5 is not yet practical in Astro projects.
• Current strategy: use tsgo for native type checking and keep typescript as a compatibility dependency for Astro tooling.

Conclusion

This migration provides faster linting/formatting and a path toward TypeScript 7 native tooling, while preserving existing Astro checks. As soon as Astro fully supports tsgo, the legacy typescript package can be removed.