# ESLint 10 Migration

**Last Updated:** 2026-03-02

Documentation of the migration from ESLint 8 (legacy `.eslintrc.cjs`) to ESLint 10 (flat config `eslint.config.mjs`).

## Summary

- **Config:** `eslint.config.mjs` (flat config, ESM)
- **ESLint:** ^10.0.2
- **Node.js:** 22 LTS (migrated from Node 20; ESLint 10 requires 20.19+, 22.13+, or 24+)
- **Dependencies:** `@eslint/js`, `eslint-config-prettier` (flat), `globals` ^17.4.0

## Changes Made

### 1. Node.js Upgrade

- **Initial:** Added `.nvmrc` with `20` for local consistency
- **Updated 2026-03-02:** Migrated to Node 22 LTS (see `docs/development/DEPENDENCY_UPDATE_2026.md`)
- Updated `.github/workflows/production-deployment.yml` and `.github/workflows/lighthouse-ci.yml` to use `node-version-file: '.nvmrc'` (Node 22)

### 2. Config Conversion

- **Removed:** `.eslintrc.cjs` (legacy config)
- **Added:** `eslint.config.mjs` with:
  - `defineConfig` from `eslint/config`
  - `js.configs.recommended` from `@eslint/js`
  - `eslint-config-prettier/flat` for Prettier compatibility
  - `ignores` array (replacing `ignorePatterns`)
  - `languageOptions.globals` (replacing `env` and `globals`)
  - 12 override blocks converted to flat config objects with `files` patterns

### 3. New Ignores

- `**/vendor/` – catches `v2/vendor/` (third-party code)
- `**/.venv/`, `.venv/` – Python virtual environment

### 4. `.mjs` Support

- Added override for `**/*.mjs` with Node + browser globals and `no-console: off` (test/dev scripts)

### 5. ESLint 10 New Rules

The following rules were added to `eslint:recommended` in v10:

- **preserve-caught-error** – No new reports in this codebase
- **no-useless-assignment** – No new reports
- **no-unassigned-vars** – No new reports

## Rollback

If migration causes issues:

1. Restore `.eslintrc.cjs` from git
2. Revert `package.json` to `eslint: ^8.57.1`, `eslint-config-prettier: ^9.1.0`
3. Remove `@eslint/js`, `globals` from devDependencies
4. Delete `eslint.config.mjs`
5. Run `npm install`
6. Revert Node version in CI workflows

## Validation

- `npm run lint` – 0 errors
- `npm run format:check` – passes
- `make validate` – all steps pass
- Pre-push hook – runs `npm run validate`

## Related Updates

- **Node.js 22 Migration:** See `docs/development/DEPENDENCY_UPDATE_2026.md` for Node 20 → 22 migration details
- **Dependency Updates:** See `docs/development/DEPENDENCY_UPDATE_2026.md` for complete dependency update log

## References

- [ESLint Migration Guide](https://eslint.org/docs/latest/use/configure/migration-guide)
- [Migrate to v10.x](https://eslint.org/docs/latest/use/migrate-to-10.0.0)
- [eslint-config-prettier flat config](https://github.com/prettier/eslint-config-prettier#flat-config)