# Migration Guide Flat Config

Migrating from v5.x (legacy `.eslintrc.*`) to v6.0.0+ (flat config only):

## Step-by-Step Migration

1. **Update ESLint to v9+**

   ```bash
   # Using pnpm (recommended)
   pnpm add eslint@^9.0.0 --save-dev --save-exact

   # Using npm
   npm install eslint@^9.0.0 --save-dev --save-exact
   ```

2. **Update @bitfactory/eslint-config**

   ```bash
   # Using pnpm (recommended)
   pnpm add @bitfactory/eslint-config@^6.0.0 --save-dev --save-exact

   # Using npm
   npm install @bitfactory/eslint-config@^6.0.0 --save-dev --save-exact
   ```

3. **Install required dependencies** _(optional)_

   If your project doesn't use `.npmrc` with `auto-install-peers=true`, install peer dependencies manually.
   This includes `eslint-config-flat-gitignore`, which is needed for automatic `.gitignore` integration.
   See [Peer Dependencies](01-installation.md#peer-dependencies) for details.

   ```bash
   # Using pnpm
   pnpm dlx install-peerdeps --dev --extra-args="-E" @bitfactory/eslint-config@^6.0.0

   # Using npm
   npx install-peerdeps --dev --extra-args="-E" @bitfactory/eslint-config@^6.0.0
   ```

4. **Remove legacy ESLint configuration**

   - Remove `.eslintrc.js`, `.eslintrc.json`, `.eslintrc.yml`, or `.eslintrc.yaml`
   - Remove `.eslintignore` (no longer needed with flat config and gitignore plugin)

5. **Update package.json scripts**

   Remove `ESLINT_USE_FLAT_CONFIG=false` environment variable from your scripts if present:

   ```json
   {
     "scripts": {
       "lint": "eslint .",
       "lint:fix": "eslint . --fix"
     }
   }
   ```

6. **Create new flat config file**

   - Review your existing legacy config to identify custom rules, plugins, and configurations
   - Create `eslint.config.js` using examples from [Configuration Examples](02-configuration.md#configuration-examples) as a base
   - **Preserve all customizations** from your old config:
     - Custom rules (add them as additional config objects after the base configs)
     - Custom plugins (see [Custom Configuration](02-configuration.md#custom-configuration) for examples)
     - Project-specific overrides (file patterns, language options, etc.)
   - **Include gitignore plugin** in your config (already installed via peer dependencies):

     ```js
     import bitfactoryBase from '@bitfactory/eslint-config';
     import gitignore from 'eslint-config-flat-gitignore';

     export default [
         gitignore(), // Automatically ignore .gitignore patterns
         ...bitfactoryBase,
     ];
     ```

7. **Test your configuration**

   ```bash
   # Using pnpm
   pnpm run lint

   # Using npm
   npm run lint
   ```