Linting & Formatting

The web app uses oxlint and oxfmt for fast, reliable linting and formatting with minimal configuration.

Why Oxlint?

Blazingly Fast

50-100x faster than ESLintWritten in Rust for maximum performance

Zero Config

Works out of the boxSensible defaults for modern JS/TS

ESLint Compatible

Implements popular ESLint rulesFamiliar rule names and configs

Built for Bun

Native Bun integrationNo Node.js dependencies

Quick Start

Linting and formatting are pre-configured in the starter:

# Lint all files
bun lint

# Format all files
bun format

Configuration

Package Scripts

Defined in package.json:

web/package.json

{
  "scripts": {
    "lint": "oxlint",
    "format": "oxfmt"
  },
  "devDependencies": {
    "oxlint": "^1.43.0",
    "oxfmt": "^0.28.0"
  }
}

Oxlint Configuration (Optional)

By default, oxlint uses sensible defaults. Create an .oxlintrc.json file only if you need custom rules:

.oxlintrc.json

{
  "rules": {
    "no-console": "warn",
    "no-debugger": "error",
    "eqeqeq": "error"
  }
}

The starter does not include an .oxlintrc.json by default. Oxlint works great with zero configuration.

Linting

Run Linter

# Check for issues
bun lint

# Lint specific files
bun lint components/ui/button.tsx

# Lint with auto-fix (when available)
bun lint --fix

Common Rules

Oxlint enforces best practices:

TypeScript
React
Code Quality

No unused variables
Explicit function return types (strict mode)
Consistent type imports
No any type without explicit annotation

Disabling Rules

Disable specific rules with comments:

// Disable for next line
// oxlint-disable-next-line no-console
console.log('Debug info');

// Disable for entire file
// oxlint-disable no-console

// Disable multiple rules
// oxlint-disable-next-line no-console, no-debugger
console.log('Debug');
debugger;

Use disable comments sparingly. If you find yourself disabling the same rule frequently, consider adjusting your configuration.

Formatting

Run Formatter

# Format all files
bun format

# Format specific files
bun format components/ui/button.tsx

# Check formatting without changing files
bun format --check

Formatting Rules

Oxfmt applies consistent style:

Indentation: 2 spaces
Quotes: Double quotes for JSX, single for JS/TS
Semicolons: Always
Trailing commas: ES5 (objects, arrays)
Line length: 100 characters (soft limit)
Arrow functions: Parentheses when needed

Before
After

const Button = ({ variant, children }) => {
  return (
    <button className={cn('base', variant === 'primary' && 'primary')}>
      {children}
    </button>
  )
}

const Button = ({ variant, children }) => {
  return (
    <button
      className={cn("base", variant === "primary" && "primary")}
    >
      {children}
    </button>
  );
};

Editor Integration

VS Code

Install the oxc extension:

Install oxc-vscode
Add to .vscode/settings.json:

.vscode/settings.json

{
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  }
}

Format on save keeps your code consistent without thinking about it.

Other Editors

Oxc supports:

Neovim: oxc.nvim
Zed: Built-in support
Sublime Text: Via LSP

Pre-commit Hooks

Run linting and formatting before commits:

Install husky

bun add -d husky lint-staged

Initialize husky

bunx husky init

Configure lint-staged

package.json

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "oxlint --fix",
      "oxfmt"
    ]
  }
}

Add pre-commit hook

.husky/pre-commit

#!/bin/sh
bunx lint-staged

Now linting and formatting run automatically on staged files before each commit.

CI Integration

Add linting to your CI pipeline:

.github/workflows/lint.yml

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install
        working-directory: web
      
      - name: Run linter
        run: bun lint
        working-directory: web
      
      - name: Check formatting
        run: bun format --check
        working-directory: web

Comparison: Oxlint vs ESLint

Performance
Features
Migration

Tool	Time (1000 files)	Speed
ESLint	~30s	Baseline
Oxlint	~0.3s	100x faster

Feature	ESLint	Oxlint
TypeScript support	✅ Via plugin	✅ Built-in
React support	✅ Via plugin	✅ Built-in
Auto-fix	✅ Some rules	✅ Many rules
Custom rules	✅ Full	⚠️ Limited
Plugin ecosystem	✅ Massive	⚠️ Growing
Configuration	Complex	Minimal

Switching from ESLint:

Remove ESLint packages:

bun remove eslint @typescript-eslint/* eslint-plugin-*

Install oxlint:
```
bun add -d oxlint oxfmt
```

Update scripts:

{
  "scripts": {
    "lint": "oxlint",
    "format": "oxfmt"
  }
}

Remove .eslintrc.* and .prettierrc.* files

Best Practices

Run Before Commit

Use pre-commit hooks to catch issues early

Format on Save

Enable auto-formatting in your editor

Fail CI on Errors

Don’t merge code with linting errors

Keep Config Minimal

Trust the defaults, customize only when needed

Troubleshooting

Oxlint not finding files

By default, oxlint checks all .ts, .tsx, .js, .jsx files. If files are missing:

# Specify file patterns
bun lint "**/*.{ts,tsx}"

# Check ignore patterns
cat .gitignore

Formatting conflicts with editor

Make sure your editor is using oxfmt, not Prettier or another formatter:

.vscode/settings.json

{
  "editor.defaultFormatter": "oxc.oxc-vscode"
}

Pre-commit hook not running

Ensure husky is initialized:

bunx husky init
chmod +x .husky/pre-commit

Next Steps

Testing

Add tests to complement linting

Project Structure

Organize code following conventions

Oxc Docs

Official Oxc documentation

Getting Started

Development

Quality

Why Oxlint?

Blazingly Fast

Zero Config

ESLint Compatible

Built for Bun

Quick Start

Configuration

Package Scripts

Oxlint Configuration (Optional)

Linting

Run Linter

Common Rules

Disabling Rules

Formatting

Run Formatter

Formatting Rules

Editor Integration

VS Code

Other Editors

Pre-commit Hooks

CI Integration

Comparison: Oxlint vs ESLint

Best Practices

Run Before Commit

Format on Save

Fail CI on Errors

Keep Config Minimal

Troubleshooting

Next Steps

Testing

Project Structure

Oxc Docs

Build docs developers (and LLMs) love

Getting Started

Development

Quality

​Why Oxlint?

Blazingly Fast

Zero Config

ESLint Compatible

Built for Bun

​Quick Start

​Configuration

​Package Scripts

​Oxlint Configuration (Optional)

​Linting

​Run Linter

​Common Rules

​Disabling Rules

​Formatting

​Run Formatter

​Formatting Rules

​Editor Integration

​VS Code

​Other Editors

​Pre-commit Hooks

​CI Integration

​Comparison: Oxlint vs ESLint

​Best Practices

Run Before Commit

Format on Save

Fail CI on Errors

Keep Config Minimal

​Troubleshooting

​Next Steps

Testing

Project Structure

Oxc Docs

Build docs developers (and LLMs) love

Why Oxlint?

Quick Start

Configuration

Package Scripts

Oxlint Configuration (Optional)

Linting

Run Linter

Common Rules

Disabling Rules

Formatting

Run Formatter

Formatting Rules

Editor Integration

VS Code

Other Editors

Pre-commit Hooks

CI Integration

Comparison: Oxlint vs ESLint

Best Practices

Troubleshooting

Next Steps