ESLint Flat Config dengan Claude Code untuk Proyek Nyata

Jangan biarkan Claude Code menebak seluruh konfigurasi

ESLint adalah alat analisis statis untuk JavaScript dan TypeScript. Analisis statis berarti membaca kode sebelum aplikasi berjalan, supaya Promise yang lupa ditunggu, kesalahan React Hooks, masalah aksesibilitas, import yang berantakan, dan pola rawan bug bisa terlihat lebih awal.

Sejak ESLint v9, Flat Config menjadi format standar. Pada Juni 2026, dokumentasi resmi masih menjadikan eslint.config.js dan eslint.config.mjs sebagai pusat konfigurasi. Namun meminta Claude Code “tolong setup ESLint” masih terlalu kabur. Ia bisa mencampur gaya lama .eslintrc, melewati lint berbasis tipe, atau menyalakan aturan yang membuat CI lambat tanpa menaikkan kualitas.

Workflow yang lebih aman adalah memberi Claude Code kontrak yang jelas: stack proyek, folder hasil generate, command yang wajib lulus, dan aturan yang boleh dilonggarkan hanya di test. Artikel ini merangkum pola yang Masa pakai di dashboard React, situs konten Astro, dan library TypeScript kecil.

Gunakan dokumentasi resmi sebagai rujukan: ESLint Configuration Files, typescript-eslint typed linting, eslint-plugin-astro User Guide, dan Claude Code CLI reference.

Pasang dependency dan scripts terlebih dahulu

Sebelum meminta Claude Code mengedit repository, pasang paket yang sesuai. Paket dasar mencakup ESLint, TypeScript, React, Hooks, aksesibilitas, dan pengurutan import. Tambahkan paket Astro hanya jika proyek memiliki file .astro.

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

# Hanya untuk proyek Astro
npm i -D eslint-plugin-astro astro-eslint-parser

Di package.json, pisahkan perbaikan lokal dan verifikasi CI. lint:fix untuk cleanup lokal. lint dan typecheck adalah command yang harus dijalankan CI. --max-warnings=0 membuat warning menjadi failure; pada repo lama, aktifkan setelah cleanup pertama.

{
  "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 tidak boleh berhenti setelah menulis file konfigurasi. Ia harus menjalankan command yang sama dengan workflow tim.

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

Flat Config untuk TypeScript dan React

Untuk aplikasi React + TypeScript, eslint.config.mjs berikut adalah titik awal yang praktis. projectService: true mengaktifkan lint dengan informasi tipe. Ini kuat, tetapi ada biaya performa, jadi output build dan folder hasil generate harus di-ignore sejak awal.

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"
    }
  }
);

Tujuan konfigurasi ini bukan memaksakan selera gaya, tetapi menurunkan risiko nyata. no-floating-promises menangkap await yang tertinggal. no-misused-promises mengurangi handler async berbahaya di JSX. consistent-type-imports membuat import yang hanya dipakai sebagai tipe tetap jelas. Test boleh punya pengecualian, tetapi kode produksi jangan ikut dilemahkan.

Astro perlu diperlakukan terpisah

File Astro mencampur template, TypeScript frontmatter, pemanggilan komponen, dan script client. Jika config khusus React langsung diterapkan ke .astro, ESLint bisa gagal saat parsing sebelum menemukan masalah penting.

Untuk situs konten Astro, mulai dari config Flat rekomendasi plugin, lalu tambah override kecil untuk .astro. Rule astro/no-set-html-directive berguna untuk blog dan dokumentasi karena injeksi HTML mudah lolos saat review konten.

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"
    }
  }
);

Jangan jadikan ESLint sebagai formatter untuk semuanya. Serahkan format ke Prettier, lalu fokuskan ESLint pada kode berbahaya, aksesibilitas, kesalahan tipe, dan aturan proyek. Lanjutkan dengan panduan konfigurasi Prettier.

Tiga use case nyata

Use case pertama adalah dashboard SaaS. Undangan user, billing, dan perubahan role sangat bergantung pada kode async. Di sini @typescript-eslint/no-floating-promises sebaiknya error, karena satu await yang hilang bisa menjadi insiden produksi.

Use case kedua adalah blog teknis Astro. Pemeriksaan paling bernilai adalah parsing .astro, aksesibilitas, style tidak terpakai, dan HTML berbahaya. Karena banyak halaman dihasilkan otomatis, dist/, .astro/, dan output build wajib di-ignore.

Use case ketiga adalah library TypeScript. API publik harus lebih ketat daripada test. Pertahankan rule kuat untuk type imports, variabel tidak terpakai, dan exports, lalu longgarkan any hanya di test fixtures.

Proyek	Rule yang diperketat	Area yang dilonggarkan
Dashboard React	Promises, Hooks, a11y	Mock Storybook
Blog Astro	.astro, HTML berbahaya, CSS tidak terpakai	Konten hasil generate
Library TypeScript	Type imports, variabel, exports	Test fixtures

Jika ingin validasi sebelum commit, gabungkan dengan Husky + lint-staged. Pada repo besar, pre-commit sebaiknya cepat; typed lint yang berat lebih cocok di CI.

Tambahkan gerbang CI

Lulus lokal belum cukup. CI harus menjalankan command yang sama dengan aturan yang sama. Untuk GitHub Actions, workflow minimal ini cukup untuk banyak proyek.

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

Jika repo lama menghasilkan ratusan error, jangan langsung menjalankan eslint --fix ke seluruh tree dan mengirim diff besar. Kelompokkan dulu berdasarkan rule, lalu minta Claude Code memperbaiki batch kecil.

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

lint:debug menampilkan config final untuk satu file. Gunakan saat rule React menyentuh .astro secara keliru, atau saat pengecualian test bocor ke kode produksi.

Template prompt untuk Claude Code

Template 1: setup baru.

Tambahkan ESLint Flat Config ke repository ini.
Stack-nya TypeScript + React. Baca package.json, tsconfig, dan setup lint yang sudah ada terlebih dahulu.
Buat eslint.config.mjs dan lanjutkan sampai npm run lint serta npm run typecheck lulus.
Hindari autofix yang bisa mengubah behavior. Jika perlu, jelaskan alasannya sebelum menerapkan.

Template 2: memperbaiki error lint.

Saya akan paste output npm run lint.
Kelompokkan error berdasarkan rule, perbaiki kategori berisiko rendah lebih dulu, dan jaga diff tetap kecil.
Gunakan eslint-disable hanya sebagai opsi terakhir. Jika digunakan, tambahkan alasan satu baris.
Setelah perubahan, jalankan npm run lint dan npm run typecheck.

Template 3: dukungan Astro.

Review konfigurasi ESLint untuk situs Astro ini.
Pisahkan config untuk .astro, .ts, dan .tsx. Gunakan config Flat rekomendasi eslint-plugin-astro.
Set astro/no-set-html-directive menjadi error dan pastikan rule React tidak keliru diterapkan ke seluruh file .astro.

Template 4: investigasi CI.

Job lint di GitHub Actions gagal.
Bandingkan versi Node, npm, ESLint, dan plugin antara lokal dan CI.
Buat command reproduksi, lalu pisahkan solusi menjadi perubahan config, update dependency, atau perubahan source code.
Terapkan diff aman paling kecil.

Claude Code membutuhkan file yang harus dibaca, command yang harus dijalankan, dan batasan yang jelas. “Fix lint” terlalu lemah. “Jangan melemahkan rule produksi dan buktikan dengan command ini” jauh lebih aman.

Jebakan umum

Jebakan pertama adalah menyalin chain extends lama dari .eslintrc ke Flat Config. Bentuknya berbeda. Jika harus memakai shared config lama, cek kompatibilitas, tetapi prioritaskan contoh Flat dari dokumentasi plugin.

Jebakan kedua adalah menerapkan typed lint ke semua file. projectService: true kuat, tetapi bundle, output generate, dan build artifact membuat CI lambat. Tulis ignores sebelum menambah rule.

Jebakan ketiga adalah menerima diff autofix yang terlalu besar. Pengurutan import, type imports, variabel tidak terpakai, dan formatting bisa menyembunyikan perubahan behavior. Masa biasanya memecah rollout pertama menjadi Promises, imports, dan rule framework.

Jebakan keempat adalah membiarkan warning selamanya. Warning yang tidak pernah memblokir akan menjadi noise. Pakai error untuk kebijakan tim, warn untuk edukasi sementara, dan jangan aktifkan rule dengan sinyal lemah.

Jebakan kelima adalah tidak menjelaskan intent ke Claude Code. Katakan apakah aksesibilitas kritis, apakah test fixtures boleh memakai any, atau apakah API publik harus strict. Batasan seperti ini menghasilkan config yang lebih tepat daripada rekomendasi generik.

Ringkasan

ESLint Flat Config membuat cakupan rule lebih terlihat karena konfigurasi proyek berada di satu tempat. Nilai Claude Code bukan hanya membuat file itu sekali, tetapi membaca codebase, menjalankan check, dan menyesuaikan tanpa menurunkan standar penting.

Mulai dari baseline yang benar untuk React/TypeScript atau Astro. Masukkan npm run lint dan npm run typecheck ke CI. Setelah itu gunakan template prompt di atas untuk perbaikan kecil, dan review manual setiap eslint-disable atau diff besar dari --fix.

Untuk workflow lengkap, gabungkan dengan Prettier dan Husky + lint-staged. Jika perlu prompt review dan checklist rollout yang bisa dipakai ulang, lihat halaman produk ClaudeCodeLab.

Hasil uji praktik

Masa mencoba konfigurasi ini pada dashboard React kecil dan starter blog Astro. Run pertama menemukan banyak noise urutan import dan beberapa Promise yang tidak ditangani. Satu diff besar dari eslint --fix sulit direview, jadi memisahkan Promises, imports, dan rule keamanan Astro bekerja lebih baik. Flow yang paling repeatable adalah mengunci npm run lint dan npm run typecheck di CI, menempelkan log gagal ke Claude Code, lalu meminta perbaikan kecil dengan command pembuktian.