@veracity/vui/skills/migrate-eslint-to-oxlint/SKILL.md

Veracity UI is a React component library crafted for use within Veracity applications and pages. Based on Styled Components and @xstyled.

---
name: migrate-eslint-to-oxlint
description: >
  Migrate from ESLint to Oxlint. Use when setting up Oxlint in a new project,
  transitioning from ESLint, configuring Oxlint rules, integrating Oxfmt,
  or updating CI/CD pipelines for linting and formatting.
metadata:
  type: setup
  library: '@veracity/vui'
  library_version: '5.2.2'
---

# Migrate from ESLint to Oxlint

Oxlint is a high-performance, zero-config linter built in Rust. It's 100x faster than ESLint and is the standard for the VUI monorepo and new VUI projects.

## Why Migrate?

- 🚀 **100x faster** linting performance
- 📦 Zero-config setup with sensible defaults
- 🔧 Drop-in replacement for most ESLint rules
- 🧹 Cleaner output and better error messages
- 🎯 Built-in support for TypeScript, React, Vue, and more

## Quick Start

### Step 1: Install Oxlint & Oxfmt

```bash
npm install --save-dev oxlint@latest oxfmt@latest
```

Or use the VUI monorepo config:

```bash
npm install --save-dev @veracity/oxlint-config
```

### Step 2: Create Config

Create `oxlint.config.ts` at your project root:

```typescript
import {createRequire} from 'module';

const require = createRequire(import.meta.url);
const baseConfig = require('@veracity/oxlint-config');

export default {
  ...baseConfig,
  ignorePatterns: ['node_modules/', 'dist/', '.next/'],
};
```

Or standalone (no base config):

```typescript
export default {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
  rules: {
    no_console: 'warn',
    no_unused_variables: 'error',
  },
};
```

### Step 3: Update package.json

```json
{
  "scripts": {
    "lint": "oxlint",
    "lint:fix": "oxlint --fix",
    "format": "oxfmt"
  }
}
```

### Step 4: Remove Old ESLint Files

```bash
rm -f .eslintrc.js .eslintrc.json .eslintignore .eslintcache
```

### Step 5: Test

```bash
npm run lint
npm run format
```

## Rule Mapping

Most ESLint rules map directly to Oxlint:

| ESLint                | Oxlint                               |
| --------------------- | ------------------------------------ |
| `no-unused-vars`      | `no_unused_variables`                |
| `react/jsx-key`       | `jsx_key`                            |
| `typescript-eslint/*` | Native TS support (no plugin needed) |
| `no-console`          | `no_console`                         |
| `prefer-const`        | `prefer_const`                       |

See [Oxlint Rule Catalog](https://oxc-project.github.io/docs/guide/rules.html) for complete mappings.

## Formatting with Oxfmt

Oxfmt is Oxlint's paired formatter (like Prettier, but Rust-based and faster).

Create `.oxfmt.toml` or `oxfmt.config.ts`:

```toml
line_length = 120
print_width = 120
single_quotes = true
trailing_comma = "all"
use_spaces = true
indent_size = 2
```

Or in TypeScript:

```typescript
export default {
  lineLength: 120,
  printWidth: 120,
  singleQuotes: true,
  trailingComma: 'all',
  useSpaces: true,
  indentSize: 2,
};
```

Usage:

```bash
# Check
oxfmt --check

# Fix
oxfmt --write

# In npm scripts
"format": "oxfmt",
"format:check": "oxfmt --check"
```

## VUI Monorepo Configs

Available configs from `@veracity/oxlint-config`:

- `@veracity/oxlint-config` — Base config
- `@veracity/oxlint-config/core` — Core rules
- `@veracity/oxlint-config/storybook` — Storybook-specific rules
- `@veracity/oxlint-config/vitest` — Vitest-specific rules
- `@veracity/oxlint-config/playwright` — Playwright-specific rules
- `@veracity/oxlint-config/tanstack` — TanStack (React Query) specific rules

Example for Storybook:

```typescript
import {createRequire} from 'module';

const require = createRequire(import.meta.url);
const baseConfig = require('@veracity/oxlint-config/storybook');

export default {
  ...baseConfig,
  ignorePatterns: ['storybook-static/', 'website/'],
};
```

## CI/CD Integration

If your `package.json` scripts are updated, no CI changes needed:

```yaml
- name: Lint
  run: npm run lint

- name: Format Check
  run: npm run format:check
```

The commands stay the same.

## Common Issues

### "Cannot find module '@veracity/oxlint-config'"

Ensure you've installed the package:

```bash
npm install --save-dev @veracity/oxlint-config
```

### Oxlint ignores errors that ESLint caught

Check [Oxlint Rule Catalog](https://oxc-project.github.io/docs/guide/rules.html). Some ESLint rules don't have Oxlint equivalents:

- Use TypeScript strict mode for type checks
- Use Prettier/Oxfmt for formatting
- File an issue with Oxlint to request the rule

### ESLint plugins no longer work

Oxlint doesn't have a plugin system. Its rules are pre-built and optimized:

- ✅ React rules built-in
- ✅ TypeScript support native
- ✅ Import checking included
- ⚠️ Custom plugins not supported

For unsupported checks, use TypeScript strict mode or custom build scripts.

### Performance is slow

Oxlint should be fast by default. If slow:

1. Check `ignorePatterns` — ensure `node_modules/` is excluded
2. Run `oxlint --version` to confirm latest version
3. Profile with `oxlint --debug` if necessary

## Verification Checklist

- [ ] Oxlint and Oxfmt installed
- [ ] `oxlint.config.ts` created and valid
- [ ] `package.json` scripts updated
- [ ] Old ESLint files removed
- [ ] `npm run lint` runs without errors
- [ ] `npm run format` runs without errors
- [ ] CI/CD pipeline still passes
- [ ] Pre-commit hooks updated (if using Husky, lint-staged, etc.)
- [ ] Team members notified

## References

- [Oxlint Official Docs](https://oxc-project.github.io/)
- [Oxlint Rule Catalog](https://oxc-project.github.io/docs/guide/rules.html)
- [Oxfmt Formatter](https://oxc-project.github.io/docs/guide/formatter.html)
- [VUI Setup Guide](./setup-vui/SKILL.md)
- [ESLint vs Oxlint Comparison](https://oxc-project.github.io/docs/guide/comparison.html)

## Deprecated: @veracity/eslint-config

The `@veracity/eslint-config` package is deprecated but maintained for backward compatibility. It will be removed in VUI v5.0.0.

If still using ESLint:

```bash
npm install @veracity/eslint-config --save-dev
```

```javascript
// .eslintrc.js
module.exports = {
  extends: ['@veracity/eslint-config/recommended'],
};
```

Plan your migration accordingly.