ESLint Kurulumu ve JavaScript Kod Standartları

Yazar:komut.io ekibi
0 Yorum

Bir JavaScript projesini devraldığınızda ilk baktığınız şey nedir? Ben her zaman package.json dosyasına bakarım. Eğer orada eslint görmüyorsam, o projede beklediğimden fazla vakit geçireceğimi biliyorum. ESLint, bir projede kod kalitesini tutarlı tutmanın en pratik yollarından biri ve bu yazıda kurulumdan ileri seviye konfigürasyona kadar gerçek dünya deneyimlerimden bahsedeceğim.

ESLint Nedir ve Neden Önemlidir

ESLint, JavaScript ve TypeScript kodlarını statik olarak analiz eden bir araç. “Statik analiz” derken kodu çalıştırmadan, sadece kaynak kodu okuyarak hataları ve kötü pratikleri tespit etmesini kastediyorum. Bu, CI/CD pipeline’larında çok değerli çünkü kodu deploy etmeden önce sorunları yakalayabiliyorsunuz.

Bir ekipte 5-6 kişi JavaScript yazıyorsa, herkesin farklı alışkanlıkları var demektir. Kimi var kullanır, kimi let ve const. Kimi noktalı virgül koyar, kimi koymaz. Kimi tek tırnak sever, kimi çift tırnak. Bu farklılıklar kod review süreçlerini yavaşlatır, diff’leri kirletir ve uzun vadede bakım maliyetini artırır. ESLint bu kaosun önüne geçer.

Kurulum: Node.js Ortamının Hazırlanması

ESLint’i kurmadan önce Node.js ortamınızın hazır olması gerekiyor. Bunu atlayıp direkt kuruluma geçen birçok kişinin sonradan sorun yaşadığını gördüm.

# Node.js versiyonunu kontrol et
node --version
npm --version

# Node.js 12 ve üzeri gerekiyor, ama 16+ önerilir
# nvm kullanıyorsanız:
nvm install 18
nvm use 18

Proje dizininde package.json yoksa önce onu oluşturmanız gerekiyor:

mkdir my-project && cd my-project
npm init -y

ESLint Kurulumu

ESLint’i global kurmak yerine her zaman proje bazında kurmayı tercih ediyorum. Global kurulum, farklı projelerde farklı ESLint versiyonlarına ihtiyaç duyduğunuzda baş ağrısı yaratır.

# Proje bazında kurulum (önerilen)
npm install --save-dev eslint

# Ya da yarn kullanıyorsanız
yarn add --dev eslint

# pnpm tercih edenler için
pnpm add --save-dev eslint

Kurulumdan sonra ESLint’in konfigürasyon dosyasını oluşturmanın en kolay yolu init komutu:

# ESLint konfigürasyon sihirbazını başlat
npx eslint --init

Bu komut size birkaç soru sorar:

  • How would you like to use ESLint? Genellikle “To check syntax, find problems, and enforce code style” seçeneğini seçin
  • What type of modules does your project use? Projenize göre CommonJS veya ES Modules seçin
  • Which framework does your project use? React, Vue ya da None
  • Does your project use TypeScript? TypeScript kullanıyorsanız yes deyin
  • Where does your code run? Browser, Node veya ikisi birden

Sihirbaz cevaplarınıza göre otomatik olarak bir .eslintrc.json ya da .eslintrc.js dosyası oluşturur ve gerekli paketleri yükler.

Konfigürasyon Dosyasını Anlamak

İşte basit bir .eslintrc.json örneği:

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended"
  ],
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "rules": {
    "no-unused-vars": "warn",
    "no-console": "warn",
    "eqeqeq": "error",
    "semi": ["error", "always"],
    "quotes": ["error", "single"],
    "indent": ["error", 2],
    "no-var": "error",
    "prefer-const": "error"
  }
}

Kural seviyelerini anlamak önemli:

  • “off” ya da 0: Kural devre dışı
  • “warn” ya da 1: Uyarı verir ama build’i bozmaz
  • “error” ya da 2: Hata verir, CI/CD’yi durdurabilir

eqeqeq kuralına dikkat edin. == yerine === kullanmayı zorlar. JavaScript’te == ile yapılan karşılaştırmalar tip dönüşümü yaptığı için beklenmedik sonuçlar verebilir. Bu kural olmadan 0 == "" gibi ifadeler true döner ve debug etmesi çok zor hatalar çıkar.

Gerçek Dünya: Mevcut Bir Projeye ESLint Eklemek

Yeni bir projeye ESLint eklemek kolay, ama mevcut büyük bir projeye eklerken dikkatli olmak gerekiyor. Bir keresinde 50.000 satır JavaScript kodu olan bir projeye ESLint eklediğimde ilk çalıştırmada 2.347 hata aldım. Takımın morali yerle bir oldu.

Bu durumda yapılacak en akıllıca şey kademeli geçiş:

# Mevcut projedeki hataları önce dosyaya döküp analiz edin
npx eslint src/ --format json > eslint-report.json

# Sadece belirli bir dizini kontrol edin
npx eslint src/components/ --ext .js,.jsx

# Otomatik düzeltilebilecek sorunları otomatik düzelt
npx eslint src/ --fix

--fix bayrağı büyük bir zaman tasarrufu sağlar. Girinti, noktalı virgül, tırnak gibi formatlama sorunlarının büyük çoğunluğunu otomatik düzeltir. Ama mantıksal hataları düzeltemez, onları kendiniz çözmeniz gerekir.

Kademeli geçiş için .eslintignore dosyasını kullanabilirsiniz:

# .eslintignore dosyası oluştur
cat > .eslintignore << 'EOF'
node_modules/
dist/
build/
coverage/
# Henüz düzeltilmemiş legacy kodlar
src/legacy/
EOF

Popüler ESLint Konfigürasyonları

Her şeyi sıfırdan yazmak zorunda değilsiniz. Endüstride yaygın kullanılan hazır konfigürasyonlar var.

Airbnb Konfigürasyonu: En katı ve en yaygın kullanılan konfigürasyonlardan biri. React projeleri için özellikle popüler.

# Airbnb konfigürasyonu kurulumu
npm install --save-dev eslint-config-airbnb eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-react eslint-plugin-react-hooks

# Sadece JavaScript (React olmayan) için
npm install --save-dev eslint-config-airbnb-base eslint-plugin-import
{
  "extends": ["airbnb"],
  "rules": {
    "react/jsx-filename-extension": [1, { "extensions": [".js", ".jsx"] }],
    "no-console": "off"
  }
}

Google Konfigürasyonu:

npm install --save-dev eslint-config-google

Standard Konfigürasyonu: Noktalı virgül kullanmayan, minimal bir stil tercih ediyorsanız:

npm install --save-dev eslint-config-standard eslint-plugin-n eslint-plugin-promise

TypeScript ile ESLint Kullanımı

Günümüzde TypeScript kullanan projelerde ESLint kurulumu biraz farklı. @typescript-eslint paketlerini kullanmak gerekiyor:

npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

TypeScript projesi için .eslintrc.json:

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "parserOptions": {
    "project": "./tsconfig.json",
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "rules": {
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-unused-vars": ["error", {
      "argsIgnorePattern": "^_"
    }],
    "@typescript-eslint/no-floating-promises": "error"
  }
}

@typescript-eslint/no-floating-promises kuralına özellikle dikkat edin. Await etmeden bırakılan Promise’leri yakalar. Node.js backend projelerinde bu kurala uyulmaması ciddi sorunlara yol açabiliyor.

package.json’a Script Ekleme

ESLint’i her seferinde uzun komutlarla çalıştırmak yerine package.json‘a script ekleyin:

{
  "scripts": {
    "lint": "eslint src/ --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint src/ --ext .js,.jsx,.ts,.tsx --fix",
    "lint:ci": "eslint src/ --ext .js,.jsx,.ts,.tsx --max-warnings 0"
  }
}

lint: Geliştirme sırasında kullanılır, uyarıları gösterir. lint:fix: Otomatik düzeltme yapar. lint:ci: CI/CD için kullanılır. --max-warnings 0 bayrağı uyarı bile olsa çıkışı başarısız sayar.

CI ortamında mutlaka lint:ci scriptini kullanın. Yoksa uyarılar birikerek zamanla görmezden gelinen bir listeye dönüşür.

Git Hooks ile Entegrasyon

ESLint’i sadece CI’da çalıştırmak yetmez. Commit aşamasında da çalıştırmak, sorunların erken yakalanmasını sağlar. husky ve lint-staged bu iş için biçilmiş kaftan:

npm install --save-dev husky lint-staged

# Husky'yi aktif et
npx husky install

# package.json'a prepare scripti ekle (npm install sonrası otomatik çalışsın)
npm pkg set scripts.prepare="husky install"

# Pre-commit hook oluştur
npx husky add .husky/pre-commit "npx lint-staged"

package.json‘a lint-staged konfigürasyonu ekleyin:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "git add"
    ]
  }
}

Bu konfigürasyonla sadece commit edilecek dosyalar lint edilir. Büyük projelerde tüm projeyi her commit’te lint etmek çok zaman alır, lint-staged bu problemi çözer.

VS Code Entegrasyonu

IDE entegrasyonu olmadan ESLint’in değeri yarıya iner. VS Code kullanıcıları için ESLint eklentisi kurulumu şart:

VS Code’da Ctrl+Shift+X ile eklenti marketine gidin ve “ESLint” aratın. Microsoft’un resmi ESLint eklentisini kurun.

Proje bazında VS Code ayarları için .vscode/settings.json dosyası oluşturun:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.run": "onType"
}

Bu ayarlarla dosyayı kaydettiğinizde ESLint otomatik olarak düzeltebileceği sorunları düzeltir. Geliştirici deneyimini ciddi ölçüde iyileştirir.

Özel Kurallar Yazma

Standart kurallar yetmediğinde kendi ESLint kuralınızı yazabilirsiniz. Bu biraz ileri seviye ama büyük ekiplerde çok işe yarıyor.

Örneğin, projenizdeki tüm async fonksiyonların try-catch içermesini zorunlu kılmak istiyorsanız:

// eslint-local-rules.js
module.exports = {
  "require-try-catch-in-async": {
    meta: {
      type: "suggestion",
      docs: {
        description: "Async fonksiyonlarda try-catch kullanımını zorunlu kılar",
      },
      schema: []
    },
    create(context) {
      return {
        AsyncFunctionDeclaration(node) {
          const body = node.body.body;
          const hasTryCatch = body.some(
            statement => statement.type === "TryStatement"
          );
          if (!hasTryCatch && body.length > 0) {
            context.report({
              node,
              message: "Async fonksiyonlar try-catch bloğu içermelidir."
            });
          }
        }
      };
    }
  }
};

Özel kuralları kullanmak için eslint-plugin-local-rules paketini kullanabilirsiniz.

CI/CD Pipeline’ına Entegrasyon

GitHub Actions ile ESLint entegrasyonu:

# .github/workflows/lint.yml
name: Lint

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint:ci

npm ci kullanmaya dikkat edin, npm install yerine. CI ortamında package-lock.json‘a sadık kalarak tutarlı kurulum yapmanızı sağlar.

Yaygın Sorunlar ve Çözümleri

“Parsing error: The keyword ‘import’ is reserved” hatası alıyorsanız:

{
  "parserOptions": {
    "ecmaVersion": 2015,
    "sourceType": "module"
  }
}

ESLint çok yavaş çalışıyorsa büyük projelerde cache kullanın:

npx eslint src/ --cache --cache-location .eslintcache

.gitignore‘a .eslintcache eklemeyi unutmayın.

Belirli bir satırda kuralı devre dışı bırakmak gerekiyorsa:

// eslint-disable-next-line no-console
console.log('Bu sadece debug için');

/* eslint-disable no-alert */
alert('Evet biliyorum, alert kullanmamalıyım');
/* eslint-enable no-alert */

Ama bu direktifleri aşırı kullanmaktan kaçının. Eğer bir kuralı sürekli devre dışı bırakıyorsanız, ya kural yanlış seçilmiştir ya da kodunuzda yapısal bir sorun vardır.

Prettier ile Birlikte Kullanım

ESLint ve Prettier birlikte kullanıldığında çakışmalar çıkabilir. ESLint bazı formatlama kurallarını da içerdiği için Prettier ile çelişir. Bunu çözmek için:

npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier
{
  "extends": [
    "eslint:recommended",
    "plugin:prettier/recommended"
  ],
  "rules": {
    "prettier/prettier": ["error", {
      "singleQuote": true,
      "semi": true,
      "tabWidth": 2,
      "trailingComma": "es5"
    }]
  }
}

eslint-config-prettier ESLint’in Prettier ile çakışan kurallarını devre dışı bırakır. plugin:prettier/recommended ise hem bu devre dışı bırakmayı yapar hem de Prettier kurallarını ESLint kuralı olarak çalıştırır.

Sonuç

ESLint kurulumu tek başına bir hedef değil, kod kalitesini artırmanın başlangıcı. Şu sırayla ilerleyin:

  • Önce proje bazında ESLint kurun ve temel kurallarla başlayın
  • Mevcut projeye ekliyorsanız kademeli geçiş yapın, tüm hataları birden düzeltmeye çalışmayın
  • Git hooks ile commit aşamasında lint kontrolü ekleyin
  • CI/CD pipeline’ınıza ESLint adımı ekleyin ve --max-warnings 0 kullanın
  • IDE entegrasyonunu ekip genelinde standart hale getirin

En önemli nokta şu: Kurallar konusunda ekiple mutabık kalın. Dayatılan kurallar dirençle karşılaşır. ESLint konfigürasyonunu birlikte oluşturduğunuzda herkes sahiplenir ve uyum çok daha kolay olur. Yeni bir kural eklemek istediğinizde pull request açın, ekip tartışsın ve karar versin. ESLint sadece bir araç, asıl değer onu kullanan ekibin geliştirdiği ortak anlayışta.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir