Bramki jakości kodu JavaScript: Opanowanie konfiguracji haków pre-commit

W ciągle zmieniającym się świecie tworzenia oprogramowania utrzymanie wysokiej jakości kodu jest sprawą nadrzędną. Czysty, dobrze sformatowany i wolny od błędów kod nie tylko zmniejsza koszty utrzymania, ale także sprzyja współpracy i przyspiesza cykle rozwojowe. Jedną z potężnych technik egzekwowania jakości kodu jest wdrożenie bramek jakości kodu za pomocą haków pre-commit. Ten artykuł stanowi kompleksowy przewodnik po konfiguracji haków pre-commit dla projektów JavaScript, umożliwiając automatyzację sprawdzania jakości kodu, zanim jeszcze trafi on do Twojego repozytorium.

Czym są haki pre-commit?

Haki Git to skrypty, które Git wykonuje przed lub po zdarzeniach takich jak commit, push i receive. Haki pre-commit, w szczególności, uruchamiane są przed sfinalizowaniem commita. Dają one kluczową możliwość inspekcji wprowadzanych zmian i zapobiegania commitom, które nie spełniają predefiniowanych standardów jakości. Pomyśl o nich jak o strażnikach, którzy zapobiegają przedostawaniu się kodu niskiej jakości do Twojej bazy kodu.

Dlaczego warto używać haków pre-commit dla jakości kodu JavaScript?

• Wczesne wykrywanie błędów: Haki pre-commit wyłapują problemy z jakością kodu na wczesnym etapie procesu deweloperskiego, zapobiegając ich dalszemu rozprzestrzenianiu. Jest to znacznie bardziej wydajne niż odkrywanie problemów podczas przeglądów kodu lub, co gorsza, na produkcji.
• Zautomatyzowane formatowanie kodu: Zapewnij spójny styl kodu w całym zespole i projekcie. Zautomatyzowane formatowanie zapobiega debatom na temat stylu i przyczynia się do bardziej czytelnej bazy kodu.
• Zmniejszone obciążenie przy przeglądzie kodu: Automatycznie egzekwując standardy kodowania, haki pre-commit zmniejszają obciążenie osób dokonujących przeglądu kodu, pozwalając im skupić się na decyzjach architektonicznych i złożonej logice.
• Poprawiona utrzymywalność kodu: Spójna i wysokiej jakości baza kodu jest łatwiejsza w utrzymaniu i rozwijaniu w czasie.
• Wymuszona spójność: Zapewniają one, że cały kod jest zgodny ze standardami projektu, niezależnie od tego, który programista go napisał. Jest to szczególnie ważne w rozproszonych zespołach pracujących z różnych lokalizacji – powiedzmy z Londynu, Tokio i Buenos Aires – gdzie indywidualne style kodowania mogą się różnić.

Kluczowe narzędzia dla jakości kodu JavaScript

Kilka narzędzi jest powszechnie używanych w połączeniu z hakami pre-commit do automatyzacji sprawdzania jakości kodu JavaScript:

• ESLint: Potężny linter JavaScript, który identyfikuje potencjalne błędy, egzekwuje style kodowania i pomaga poprawić czytelność kodu. Obsługuje szeroki zakres reguł i jest wysoce konfigurowalny.
• Prettier: Arbitralny formatter kodu, który automatycznie formatuje kod, aby był zgodny ze spójnym stylem. Obsługuje JavaScript, TypeScript, JSX i wiele innych języków.
• Husky: Narzędzie ułatwiające zarządzanie hakami Git. Pozwala definiować skrypty, które będą wykonywane na różnych etapach przepływu pracy Git.
• lint-staged: Narzędzie, które uruchamia lintery i formattery tylko na plikach dodanych do przechowalni (staged files), co znacznie przyspiesza proces pre-commit. Zapobiega to niepotrzebnemu sprawdzaniu niezmienionych plików.

Konfiguracja haków pre-commit: Przewodnik krok po kroku

Oto szczegółowy przewodnik, jak skonfigurować haki pre-commit dla Twojego projektu JavaScript przy użyciu Husky i lint-staged:

Krok 1: Instalacja zależności

Najpierw zainstaluj niezbędne pakiety jako zależności deweloperskie za pomocą npm lub yarn:

            npm install --save-dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

Lub, używając yarn:

            yarn add --dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

Krok 2: Inicjalizacja Husky

Husky upraszcza proces zarządzania hakami Git. Zainicjuj go za pomocą następującego polecenia:

            npx husky install
            

              
                Copy
              
            
          

To utworzy katalog `.husky` w Twoim projekcie, który będzie przechowywał Twoje haki Git.

Krok 3: Konfiguracja haka pre-commit

Dodaj hak pre-commit za pomocą Husky:

            npx husky add .husky/pre-commit "npx lint-staged"
            

              
                Copy
              
            
          

To polecenie tworzy plik `pre-commit` w katalogu `.husky` i dodaje do niego polecenie `npx lint-staged`. Mówi to Gitowi, aby uruchamiał lint-staged przed każdym commitem.

Krok 4: Konfiguracja lint-staged

lint-staged pozwala uruchamiać lintery i formattery tylko na plikach dodanych do przechowalni, co znacznie przyspiesza proces pre-commit. Utwórz plik `lint-staged.config.js` (lub `lint-staged.config.mjs` dla modułów ES) w głównym katalogu projektu i skonfiguruj go w następujący sposób:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
};
            

              
                Copy
              
            
          

Ta konfiguracja informuje lint-staged, aby uruchomił ESLint i Prettier na wszystkich dodanych do przechowalni plikach JavaScript i TypeScript. Flaga `--fix` w ESLint automatycznie naprawia wszelkie błędy lintingu, które można poprawić automatycznie, a flaga `--write` w Prettier formatuje pliki i nadpisuje je sformatowanym kodem.

Alternatywnie, możesz zdefiniować konfigurację bezpośrednio w swoim pliku `package.json`:

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

              
                Copy
              
            
          

Krok 5: Konfiguracja ESLint

Jeśli jeszcze tego nie zrobiłeś, skonfiguruj ESLint dla swojego projektu. Możesz utworzyć plik konfiguracyjny ESLint za pomocą następującego polecenia:

            npx eslint --init
            

              
                Copy
              
            
          

To poprowadzi Cię przez proces tworzenia pliku konfiguracyjnego ESLint (`.eslintrc.js`, `.eslintrc.json` lub `.eslintrc.yml`) w oparciu o wymagania Twojego projektu. Możesz wybrać spośród różnych predefiniowanych konfiguracji lub stworzyć własne, niestandardowe reguły.

Przykładowy `.eslintrc.js`:

            module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true
    },
    ecmaVersion: 12,
    sourceType: 'module'
  },
  plugins: [
    'react',
    '@typescript-eslint'
  ],
  rules: {
    'no-unused-vars': 'warn',
    'react/prop-types': 'off'
  }
};
            

              
                Copy
              
            
          

Ta konfiguracja rozszerza zalecane reguły ESLint, zalecane reguły React, zalecane reguły TypeScript i integruje się z Prettier. Wyłącza również regułę `react/prop-types` i ustawia regułę `no-unused-vars` na ostrzeżenie.

Krok 6: Konfiguracja Prettier

Skonfiguruj Prettier, tworząc plik `.prettierrc.js` (lub `.prettierrc.json`, `.prettierrc.yml` lub `.prettierrc.toml`) w głównym katalogu projektu. Możesz dostosować opcje formatowania Prettier, aby pasowały do wytycznych stylu Twojego projektu.

Przykładowy `.prettierrc.js`:

            module.exports = {
  semi: false,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 120,
  tabWidth: 2
};
            

              
                Copy
              
            
          

Ta konfiguracja ustawia Prettier na używanie pojedynczych cudzysłowów, brak średników, końcowe przecinki, szerokość linii 120 znaków i szerokość tabulacji 2 spacje.

Alternatywnie, możesz zdefiniować konfigurację Prettier wewnątrz `package.json`:

            {
  "prettier": {
    "semi": false,
    "trailingComma": "all",
    "singleQuote": true,
    "printWidth": 120,
    "tabWidth": 2
  }
}
            

              
                Copy
              
            
          

Krok 7: Testowanie konfiguracji

Aby przetestować swoją konfigurację, dodaj kilka zmian do przechowalni i spróbuj je zatwierdzić. Na przykład:

            git add .
            

              
                Copy
              
            
          

            git commit -m "Test pre-commit hook"
            

              
                Copy
              
            
          

Jeśli wystąpią jakiekolwiek problemy z lintingiem lub formatowaniem, ESLint i Prettier automatycznie je naprawią (jeśli to możliwe) lub zgłoszą błędy. Jeśli błędy zostaną zgłoszone, commit zostanie przerwany, co pozwoli Ci naprawić problemy przed ponownym zatwierdzeniem.

Zaawansowane opcje konfiguracji

Używanie różnych linterów i formatterów

Możesz łatwo zintegrować inne lintery i formattery z konfiguracją haka pre-commit. Na przykład, możesz użyć Stylelint do lintingu plików CSS lub SASS:

            npm install --save-dev stylelint stylelint-config-standard
            

              
                Copy
              
            
          

Następnie zaktualizuj swój plik `lint-staged.config.js`, aby uwzględnić Stylelint:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

Uruchamianie testów przed commitem

Możesz również uruchamiać swoje testy jednostkowe jako część haka pre-commit. Pomaga to zapewnić, że Twój kod działa poprawnie, zanim zostanie zatwierdzony. Zakładając, że używasz Jest:

            npm install --save-dev jest
            

              
                Copy
              
            
          

Zaktualizuj swój plik `lint-staged.config.js`, aby uwzględnić polecenie testowe:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write', 'jest --findRelatedTests'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

Flaga `--findRelatedTests` mówi Jestowi, aby uruchamiał tylko testy związane ze zmienionymi plikami, co znacznie przyspiesza proces.

Pominięcie haków pre-commit

W niektórych przypadkach możesz chcieć tymczasowo pominąć haki pre-commit. Możesz to zrobić, używając flagi `--no-verify` z poleceniem `git commit`:

            git commit --no-verify -m "Commit message"
            

              
                Copy
              
            
          

Jednakże, generalnie zaleca się unikanie pomijania haków, chyba że jest to absolutnie konieczne, ponieważ odgrywają one kluczową rolę w utrzymaniu jakości kodu.

Rozwiązywanie typowych problemów

• Haki nie uruchamiają się: Upewnij się, że Husky jest poprawnie zainstalowany i zainicjowany, oraz że katalog `.husky` istnieje w głównym katalogu Twojego projektu. Sprawdź również, czy plik `pre-commit` w katalogu `.husky` jest wykonywalny.
• Błędy lintingu nie są naprawiane: Upewnij się, że używasz flagi `--fix` z ESLint, oraz że Twoja konfiguracja ESLint jest ustawiona na automatyczne naprawianie pewnych typów błędów.
• Prettier nie formatuje plików: Upewnij się, że używasz flagi `--write` z Prettier, oraz że Twoja konfiguracja Prettier jest poprawnie ustawiona.
• Wolne haki pre-commit: Użyj lint-staged, aby uruchamiać lintery i formattery tylko na plikach dodanych do przechowalni. Rozważ również optymalizację konfiguracji ESLint i Prettier, aby zminimalizować liczbę sprawdzanych reguł i ustawień.
• Konfliktujące konfiguracje: Upewnij się, że Twoje konfiguracje ESLint i Prettier nie kolidują ze sobą. Jeśli tak się dzieje, być może będziesz musiał dostosować jedną lub obie konfiguracje, aby rozwiązać konflikty. Rozważ użycie współdzielonej konfiguracji, takiej jak `eslint-config-prettier` i `eslint-plugin-prettier`, aby uniknąć konfliktów.

Najlepsze praktyki dotyczące haków pre-commit

• Utrzymuj szybkość haków: Wolne haki mogą znacznie wpłynąć na produktywność deweloperów. Używaj lint-staged, aby przetwarzać tylko pliki dodane do przechowalni i optymalizuj konfiguracje linterów i formatterów.
• Dostarczaj jasne komunikaty o błędach: Gdy hak zawiedzie, dostarczaj jasne i informacyjne komunikaty o błędach, aby pokierować deweloperów, jak naprawić problemy.
• Automatyzuj jak najwięcej: Automatyzuj formatowanie kodu i linting, aby zminimalizować wysiłek manualny i zapewnić spójność.
• Edukuj swój zespół: Upewnij się, że wszyscy członkowie zespołu rozumieją cel haków pre-commit i wiedzą, jak skutecznie z nich korzystać.
• Używaj spójnej konfiguracji: Utrzymuj spójną konfigurację dla ESLint, Prettier i innych narzędzi w całym projekcie. Pomoże to zapewnić, że cały kod jest formatowany i lintowany w ten sam sposób. Rozważ użycie współdzielonego pakietu konfiguracyjnego, który można łatwo instalować i aktualizować w wielu projektach.
• Testuj swoje haki: Regularnie testuj swoje haki pre-commit, aby upewnić się, że działają poprawnie i nie powodują żadnych nieoczekiwanych problemów.

Globalne uwarunkowania

Pracując w globalnie rozproszonych zespołach, weź pod uwagę następujące kwestie:

• Spójne wersje narzędzi: Upewnij się, że wszyscy członkowie zespołu używają tych samych wersji ESLint, Prettier, Husky i lint-staged. Można to osiągnąć, określając wersje w pliku `package.json` i używając menedżera pakietów, takiego jak npm lub yarn, do instalacji zależności.
• Zgodność międzyplatformowa: Przetestuj swoje haki pre-commit na różnych systemach operacyjnych (Windows, macOS, Linux), aby upewnić się, że działają poprawnie na wszystkich platformach. Używaj narzędzi i poleceń międzyplatformowych, gdy tylko jest to możliwe.
• Różnice w strefach czasowych: Bądź świadomy różnic w strefach czasowych podczas komunikacji z członkami zespołu na temat problemów z hakami pre-commit. Dostarczaj jasne instrukcje i przykłady, aby pomóc im szybko rozwiązać problemy.
• Wsparcie dla języków: Jeśli Twój projekt obejmuje pracę z wieloma językami, upewnij się, że Twoje haki pre-commit obsługują wszystkie języki używane w projekcie. Może być konieczne zainstalowanie dodatkowych linterów i formatterów dla każdego języka.

Podsumowanie

Wdrożenie haków pre-commit to skuteczny sposób na egzekwowanie jakości kodu, poprawę współpracy w zespole i redukcję kosztów utrzymania w projektach JavaScript. Integrując narzędzia takie jak ESLint, Prettier, Husky i lint-staged, możesz zautomatyzować formatowanie kodu, linting i testowanie, zapewniając, że do Twojego repozytorium trafia tylko kod wysokiej jakości. Postępując zgodnie z krokami opisanymi w tym przewodniku, możesz skonfigurować solidną bramkę jakości kodu, która pomoże Ci budować czystsze, łatwiejsze w utrzymaniu i bardziej niezawodne aplikacje JavaScript. Zastosuj tę praktykę i podnieś poziom przepływu pracy swojego zespołu już dziś.