Claude Code के साथ ESLint Flat Config सेटअप

Claude Code से पूरी ESLint config अंदाज़े पर न बनवाएँ

ESLint JavaScript और TypeScript के लिए static analysis tool है. Static analysis का मतलब है code चलाने से पहले उसे पढ़कर risky pattern, भूल गए await, React Hooks की गलती, accessibility issue और inconsistent imports पकड़ना.

ESLint v9 के बाद Flat Config मुख्य तरीका बन गया. जून 2026 में official docs भी eslint.config.js और eslint.config.mjs को केंद्र में रखकर config समझाते हैं. लेकिन Claude Code से सिर्फ “ESLint setup कर दो” कहना काफी नहीं है. वह पुरानी .eslintrc style मिला सकता है, type-aware lint छोड़ सकता है, या ऐसी rules जोड़ सकता है जो CI धीमा करें पर quality न बढ़ाएँ.

बेहतर तरीका है Claude Code को साफ contract देना: project stack क्या है, generated folders कौन से हैं, कौन से commands pass होने चाहिए, और tests में कौन सी rules relax हो सकती हैं. यह लेख Masa के React admin app, Astro content site और छोटे TypeScript library में इस्तेमाल किए workflow पर आधारित है.

Official references के लिए ESLint Configuration Files, typescript-eslint typed linting, eslint-plugin-astro User Guide और Claude Code CLI reference देखें.

Dependencies और scripts पहले तय करें

Claude Code से files edit कराने से पहले सही packages install करें. Base setup ESLint, TypeScript, React, Hooks, accessibility और import sorting को cover करता है. Astro packages सिर्फ तब जोड़ें जब project में .astro files हों.

npm i -D eslint @eslint/js typescript typescript-eslint globals
npm i -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y
npm i -D eslint-plugin-simple-import-sort

# सिर्फ Astro projects के लिए
npm i -D eslint-plugin-astro astro-eslint-parser

package.json में local fix और CI verification को अलग रखें. lint:fix local cleanup के लिए है. lint और typecheck CI में चलने चाहिए. --max-warnings=0 warnings को भी failure बनाता है; पुराने project में इसे पहली cleanup के बाद enable करना बेहतर है.

{
  "scripts": {
    "lint": "eslint . --max-warnings=0",
    "lint:fix": "eslint . --fix",
    "lint:debug": "eslint --print-config src/App.tsx > .eslint-debug.json",
    "typecheck": "tsc --noEmit",
    "ci:verify": "npm run lint && npm run typecheck"
  }
}

Claude Code को config file लिखकर रुकना नहीं चाहिए. उसे वही commands चलाने चाहिए जो team बाद में चलाएगी.

package.json scripts
  -> eslint.config.mjs
  -> npm run lint:fix
  -> npm run lint
  -> npm run typecheck
  -> CI gate
  -> remaining diff का Claude Code review

TypeScript/React के लिए Flat Config

React + TypeScript app में यह eslint.config.mjs practical starting point है. projectService: true type information वाला lint enable करता है. यह powerful है, लेकिन cost भी है, इसलिए generated folders और build output को पहले ignore करें.

import js from "@eslint/js";
import globals from "globals";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import simpleImportSort from "eslint-plugin-simple-import-sort";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: [
      "node_modules/",
      "dist/",
      "build/",
      "coverage/",
      ".next/",
      ".astro/",
      "public/",
      "*.min.js"
    ]
  },
  js.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2024
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    ...react.configs.flat.recommended,
    settings: {
      react: { version: "detect" }
    },
    rules: {
      ...react.configs.flat.recommended.rules,
      "react/react-in-jsx-scope": "off",
      "react/prop-types": "off"
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: {
      "react-hooks": reactHooks,
      "jsx-a11y": jsxA11y
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      ...jsxA11y.configs.recommended.rules
    }
  },
  {
    plugins: {
      "simple-import-sort": simpleImportSort
    },
    rules: {
      "simple-import-sort/imports": "error",
      "simple-import-sort/exports": "error",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports", fixStyle: "separate-type-imports" }
      ],
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-misused-promises": [
        "error",
        { checksVoidReturn: { attributes: false } }
      ],
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }
      ],
      "no-console": ["warn", { allow: ["warn", "error"] }]
    }
  },
  {
    files: ["**/*.{js,mjs,cjs}"],
    extends: [tseslint.configs.disableTypeChecked]
  },
  {
    files: ["**/*.{test,spec}.{ts,tsx}", "**/__tests__/**/*.{ts,tsx}"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-unsafe-assignment": "off",
      "@typescript-eslint/no-unsafe-member-access": "off"
    }
  }
);

इस config का goal style preference नहीं, real risk कम करना है. no-floating-promises missing await पकड़ता है. no-misused-promises JSX handlers में risky async use कम करता है. consistent-type-imports type-only imports को साफ रखता है. Tests में कुछ छूट दी जा सकती है, लेकिन production code कमजोर नहीं होना चाहिए.

Astro में .astro files अलग रखें

Astro file में template, TypeScript frontmatter, component calls और client scripts साथ आते हैं. React-only config को सीधे .astro पर लगाने से parsing fail हो सकती है.

Astro content site में plugin की Flat recommended configs से शुरू करें और .astro के लिए छोटा override जोड़ें. astro/no-set-html-directive blogs और docs में उपयोगी है, क्योंकि HTML injection editorial review में आसानी से छूट सकता है.

import js from "@eslint/js";
import astro from "eslint-plugin-astro";
import globals from "globals";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: ["dist/", ".astro/", "node_modules/", "public/"]
  },
  js.configs.recommended,
  ...astro.configs["flat/recommended"],
  ...astro.configs["jsx-a11y-recommended"],
  ...tseslint.configs.recommendedTypeChecked,
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.astro"],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser,
        extraFileExtensions: [".astro"],
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      "astro/no-set-html-directive": "error",
      "astro/no-unused-define-vars-in-style": "error"
    }
  }
);

ESLint को universal formatter न बनाएँ. Formatting Prettier को दें, और ESLint को unsafe code, accessibility, type mistakes और project conventions पर focus कराएँ. आगे के लिए Prettier config guide देखें.

तीन practical use cases

Use case 1 SaaS admin panel है. User invite, billing update और role change में async code बहुत होता है. यहाँ @typescript-eslint/no-floating-promises को error रखना चाहिए, क्योंकि missing await production incident बन सकता है.

Use case 2 Astro technical blog है. यहाँ सबसे valuable checks हैं .astro parsing, accessibility, unused styles और unsafe HTML. Generated pages ज्यादा हों तो dist/, .astro/ और build output ignore करना जरूरी है.

Use case 3 TypeScript library है. Public API tests से ज्यादा strict होनी चाहिए. Type imports, unused variables और exports पर strict rules रखें, और any को सिर्फ test fixtures में relax करें.

Project	Strict rules	Relax areas
React admin	Promises, Hooks, a11y	Storybook mocks
Astro blog	.astro, unsafe HTML, unused CSS	Generated content
TypeScript library	Type imports, unused vars, exports	Test fixtures

Commit से पहले quick check चाहिए तो Husky + lint-staged guide जोड़ें. बड़े repo में pre-commit हल्का रखें और heavy typed lint CI में चलाएँ.

CI gate जोड़ें

Local pass होना काफी नहीं है. CI को वही commands चलाने चाहिए. GitHub Actions में यह minimal workflow काफी projects के लिए काम करता है.

name: code-quality

on:
  pull_request:
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

अगर existing repo में बहुत errors आएँ, तो पूरे repo पर एक साथ eslint --fix न चलाएँ. पहले rule के हिसाब से group करें, फिर Claude Code से छोटे batches में fix कराएँ.

npm run lint
npm run lint:fix
npm run lint
npm run typecheck
npm run lint:debug

lint:debug किसी file पर final resolved config दिखाता है. इससे पता चलता है कि React rule गलती से .astro पर लग रही है या test exception production code में leak हो रही है.

Claude Code prompt templates

Template 1: नया setup.

इस repository में ESLint Flat Config जोड़ें.
Stack TypeScript + React है. पहले package.json, tsconfig और existing lint setup पढ़ें.
eslint.config.mjs बनाएँ और npm run lint तथा npm run typecheck pass होने तक fix करें.
Behavior बदलने वाले autofix से बचें. जरूरी हो तो पहले reason बताएं.

Template 2: lint errors fix.

मैं npm run lint output paste करूँगा.
Errors को rule के हिसाब से group करें, low-risk categories पहले fix करें, और diff छोटा रखें.
eslint-disable को last resort रखें. अगर use करें तो एक line reason लिखें.
Changes के बाद npm run lint और npm run typecheck चलाएँ.

Template 3: Astro support.

इस Astro site की ESLint config review करें.
.astro, .ts और .tsx के लिए config अलग करें. eslint-plugin-astro की Flat recommended config use करें.
astro/no-set-html-directive को error करें और confirm करें कि React rules पूरी .astro file पर गलत तरीके से लागू नहीं हो रहीं.

Template 4: CI failure.

GitHub Actions lint job fail हो रहा है.
Local और CI में Node, npm, ESLint और plugin versions compare करें.
Reproduction command बनाएँ, फिर fix को config change, dependency update या source-code change में अलग करें.
सबसे छोटा safe diff apply करें.

Claude Code को files, commands और boundaries चाहिए. “lint fix करो” कमजोर prompt है. “production rules कमजोर न करें और इन commands से prove करें” ज्यादा safe है.

Common pitfalls

पहला pitfall पुरानी .eslintrc की extends chain को Flat Config में copy करना है. Shape अलग है. अगर पुरानी shared config चाहिए, तो compatibility देखें; लेकिन पहले plugin docs के Flat examples चुनें.

दूसरा pitfall typed linting को हर file पर लगाना है. projectService: true useful है, पर generated files और bundles CI धीमा करते हैं. ignores पहले लिखें.

तीसरा pitfall बहुत बड़ा autofix diff है. Import sorting, type imports, unused variables और formatting एक साथ बदलें तो real behavior change छुप सकता है. Masa first rollout में Promise, import और framework rules को अलग करता है.

चौथा pitfall warning को हमेशा छोड़ देना है. जो warning कभी block नहीं करती, वह noise बन जाती है. Team policy के लिए error, temporary learning के लिए warn, और weak signal rule को न जोड़ें.

पाँचवाँ pitfall intent न बताना है. Claude Code को बताएं कि accessibility critical है, test fixtures में any allowed है, या public API strict होनी चाहिए. इससे generic config से बेहतर result आता है.

Summary

ESLint Flat Config rules का scope साफ करता है, क्योंकि project config एक जगह रहती है. Claude Code की value सिर्फ file generate करना नहीं है; वह codebase पढ़ सकता है, checks चला सकता है और standards कमजोर किए बिना config adjust कर सकता है.

पहले React/TypeScript या Astro के लिए सही baseline चुनें. npm run lint और npm run typecheck को CI में डालें. फिर ऊपर के prompts से छोटे fixes माँगें, और हर eslint-disable या बड़े --fix diff को human review दें.

पूरे workflow के लिए Prettier guide और Husky + lint-staged जोड़ें. Reusable review prompts और rollout checklists चाहिए हों तो ClaudeCodeLab products देखें.

वास्तविक परीक्षण का परिणाम

Masa ने यह setup एक छोटे React admin app और Astro blog starter में लगाया. पहली run में import order noise और कई unhandled Promises मिले. एक बड़ा eslint --fix diff review करना कठिन था, इसलिए Promises, imports और Astro safety rules को अलग batches में fix करना बेहतर रहा. सबसे repeatable flow था npm run lint और npm run typecheck को CI में lock करना, failure logs Claude Code को देना, और छोटे proof-based fixes माँगना.