Formatting & Linting

Learn how to format with Oxfmt and lint with Oxlint.

The starter kit uses Oxfmt for formatting and Oxlint for linting. The tools have separate configuration and commands so a formatting change never hides a lint failure.

Type-aware linting is enabled Oxlint loads its TypeScript, React, import, accessibility and Next.js plugins with type-aware analysis. Run the repository scripts from the project root so the linter can resolve the local TypeScript configuration.

Format and fix on save

The recommended VS Code workspace settings use the Oxc extension for both formatting and safe lint fixes:

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": "always"
  },
  "oxc.fmt.configPath": ".oxfmtrc.json",
  "oxc.fixKind": "safe_fix_or_suggestion",
  "oxc.typeAware": true
}

Change editor.formatOnSave to false and remove the source.fixAll.oxc action if you prefer to run the commands manually.

Manual commands

Use non-writing commands in CI and before reviewing a change:

Command	Purpose
`npm run format`	Check formatting with Oxfmt
`npm run lint`	Check lint rules with Oxlint
`npm run check`	Run linting and then the formatting check

Use the writing variants when you intentionally want to change files:

Command	Purpose
`npm run format:write`	Format supported files with Oxfmt
`npm run lint:write`	Apply safe Oxlint fixes
`npm run check:write`	Apply lint fixes and then format the project

Always review the resulting diff. Automated fixes can be valid while still changing code in a way you did not intend.

Configuration

Oxlint reads .oxlintrc.json. The shipped configuration enables TypeScript, React, import, JSX accessibility, Next.js and Oxc rules. Generated output, coverage, migration files and test reports are ignored.

Oxfmt reads .oxfmtrc.json. It defines the print width, quote and semicolon style, import sorting and Tailwind CSS class sorting. Migration files and generated or vendored output are excluded from formatting.

Keep tool exclusions in these configuration files rather than adding ad hoc flags to package scripts. That keeps editor, local and CI behavior aligned.

Editor integration

Install the Oxc VS Code extension. The repository already recommends it through .vscode/extensions.json and sets it as the default formatter in .vscode/settings.json.

If VS Code still uses an older formatter:

Disable the older workspace formatter extension for this repository.
Run Format Document With... and choose Oxc.
Select Configure Default Formatter and choose Oxc.
Reload the editor after installing or upgrading the extension.

Pre-commit behavior

The Husky pre-commit hook runs lint-staged. JavaScript and TypeScript files receive safe Oxlint fixes followed by Oxfmt. JSON, CSS, Markdown and MDX files are formatted with Oxfmt. Database migration files are deliberately excluded.

The pre-push hook runs npm run typecheck. These hooks are a fast guardrail, not a replacement for the complete test and build checks in CI.