SSShooter

注意事項#

この記事ではデフォルトの開発環境は VSCode であり、チーム内でできるだけ開発環境を統一し、エディタの違いやプラグインの互換性の問題を避けることが重要です。

以下で言及されるツールの核心はすべて設定ファイルです。これらの設定ファイルは通常、.js、.yaml、.json などのさまざまな形式で設定できます。または、package.json に直接設定することもできます。以降は関連設定について詳述しませんが、具体的な設定形式は公式ドキュメントで確認できます。この記事では一部の設定項目のみを解析します。

コードスタイル#

コードスタイルの一貫性はプロジェクト協力の基盤であり、ESLint と Prettier を使用することで、コードフォーマットの不一致によるマージコンフリクトを回避し、コードの可読性と保守性を向上させることができます。ESLint と Prettier の理解で触れたことがありますが、以下ではアップグレード版としてより完全に説明します。

ESlint#

この記事で紹介する最初のツールは ESlint で、その機能は次のとおりです：

1. コード規範を提供します。例えば、== ではなく === を使用することを推奨し、変更していない変数には let ではなく const を使用することを推奨するルールです。
2. 次に、コードをフォーマットし、インデントや改行などの問題を制御します。

インストール#

npm install --save-dev eslint

VSCode プラグイン#

プロジェクトに ESlint をインストールすると、ファイルの検証と整理のインターフェースが提供されますが、実際にコードを書く際には、毎回自分で API を調整して現在のファイルを処理するわけにはいきません。この場合、ESlint プラグインを使用する必要があります。プラグインをインストールすると、ショートカットキーを使用して eslint API を呼び出して現在のファイルを処理したり、保存時に自動的に現在のファイルをフォーマットしたりできます。また、コーディングウィンドウでは、警告やエラーコードを黄色や赤の線で示します。

ESlint 本体と VSCode プラグインをインストールした後、いくつかの基本機能を使用できますが、React、Vue、TS などのファイルと連携して使用するには、対応するプラグインをインストールする必要があります（ここで言及しているのは ESlint のプラグインであり、前述の VSCode プラグインとは関係ありません）。後でプラグイン（plugins）に関する問題を詳しく説明します。

設定#

まず、ESlint の設定ファイルを見てみましょう。これは ESLint ルールを設定および拡張するために使用されます。以下はその例です：

{
  "root": true,
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "parserOptions": { "project": ["./tsconfig.json"] },
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/strict-boolean-expressions": [
      2,
      {
        "allowString": false,
        "allowNumber": false
      }
    ]
  },
  "ignorePatterns": ["src/**/*.test.ts", "src/frontend/generated/*"]
}

次に、extends、plugins、rules の 3 つの設定を詳しく解析します。

Extends#

上記で言及したルールは一つや二つではなく、数百条あります。すべてを手動で設定するのは現実的ではないため、Extends を使用できます。

Extends は設定の集合であり、Extends を追加することは一組の設定を追加することと同じです。設定 extends の値を指定する際は、パッケージ名の eslint-config- プレフィックスを無視できます。

多くの大企業は独自の規範を持っています。例えば、フロントエンドコード規範の分野で有名な airbnb の設定ファイルは eslint-config-airbnb であり、インストール後は次のように記述するだけで使用できます：

{
  "extends": "airbnb"
}

ただし…… 個人的には airbnb よりも eslint:recommended または standard を使用することをお勧めします。なぜなら、airbnb は管理が厳しすぎるからです。例えば、no-plusplus や no-underscore-dangle は通常の使用に問題はなく、彼らも許可していますが、元のコーディング習慣とのギャップが大きいため、使用しないことにしました 😂。

もちろん、設定の集合には他の選択肢もあります。例えば eslint-config-alloy などがあります。また、自分の設定集合を公開することも可能で、これは公式に推奨される方法でもあります。

Plugins#

Plugins は Extends よりも強力で、設定を補完するだけでなく、ESLint のカスタムルールを追加することもできます。プラグインの値を設定する際は、パッケージ名の eslint-plugin- プレフィックスを無視できます。プラグイン内にも設定の集合が含まれることがあり、プラグイン内の設定の集合を使用する際は、plugin:パッケージ名/設定名 の形式を使用します。例えば、plugin/essential です。

eslint-plugin-vue をインストールした後、次のようにプラグインを追加できます。これにより、ESLint に Vue のルールが多数追加されます（注意：これはルールを追加するだけで、ルールが使用されるかどうかは設定していません）：

{
  // ...
  "extends": ["plugin:vue/essential"],
  "plugins": ["vue"]
  // ...
}

さまざまな言語の詳細な設定についてはここで詳述しませんが、eslint-plugin-xxx のドキュメントは一般的に比較的充実したヘルプを提供しています。

Rules#

extends でルールの集合を追加した後、習慣に応じていくつかのルールを微調整する必要があるかもしれません。この場合、rules で単一のルールを設定できます。

ルールのレベルは 3 種類あります：

• "off" or 0 - ルールを無効にする
• "warn" or 1 - ルールを警告として有効にする（終了コードには影響しない）
• "error" or 2 - ルールをエラーとして有効にする（トリガーされた場合の終了コードは 1）

設定方法は次のようになります（一部の特殊ルールには他の設定項目がある場合があります。関連情報はルールの対応ページで取得できます）：

{
  "plugins": ["plugin1"],
  "rules": {
    "eqeqeq": "off",
    "curly": "error",
    "quotes": ["error", "double"],
    "plugin1/rule1": "error"
  }
}

その他の問題#

設定が適用されない場合：

.eslintrc を更新した後、VSCode で新しい設定が適用されない場合は、ctrl shift P を押して Reload Window を選択することで、ESlint プラグインを迅速に再起動できます。

VSCode の保存時自動フォーマット設定は、settings.json を変更します：

// settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
  // "editor.formatOnSave": true,
}

Prettier#

Prettier は現代的なコードフォーマットツールです。ESLint と比較して、コードフォーマットに特化しており、JavaScript、CSS、SCSS、markdown、yaml などの多くの言語を処理できます。Prettier は ESLint が js 系ファイルのみを処理する問題を補完しますが、js という交差点においては、依然としていくつかの追加の互換操作が必要です。

インストール#

npm install --save-dev --save-exact prettier

必ず --save-exact を追加してください。異なるバージョンの prettier は特定のフォーマットを処理する際に差異があるため、チーム全員のフォーマットが同じであることを保証するためには、prettier のバージョンを統一する必要があります。

VSCode プラグイン#

原理は ESLint と同じで、npm インストールは API を提供するだけで、VSCode プラグインをインストールすることでエディタ内で簡単にフォーマットできます。

設定#

Prettier を採用する最大の理由は、スタイルに関する議論を止めることです。

Prettier は、フォーマットに関する議論を減らすために、少数の設定項目のみを提供します。これにより、皆がこの数項目について議論すればよいのです（冗談です）。以下は Prettier のほぼすべての設定で、ファイル名は .prettierrc です：

{
  "arrowParens": "always",
  "bracketSameLine": true,
  "bracketSpacing": true,
  "embeddedLanguageFormatting": "auto",
  "htmlWhitespaceSensitivity": "css",
  "insertPragma": false,
  "jsxSingleQuote": false,
  "printWidth": 80,
  "proseWrap": "preserve",
  "quoteProps": "as-needed",
  "requirePragma": false,
  "semi": true,
  "singleAttributePerLine": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "useTabs": false,
  "vueIndentScriptAndStyle": false
}

ESlint との互換性#

以前、ESLint と Prettier を使用して異なる IDE での協力を快適にする方法で、手動で ESLint と Prettier を互換性を持たせる方法について触れましたが、それは異なるエディタを使用して同期を容易にするための方法に過ぎません。ここでは、ESLint プラグインを使用して互換性を持たせる方法を紹介します。

ESLint が Prettier の作業を完全に引き継ぐには、eslint-plugin-prettier が必要です。その原理は、eslint-config-prettier を使用してすべての Prettier 関連ルールを無効にし、プラグインを通じて Prettier のルールを ESLint に統合して検証することです。これを実現するためには、次の 1 行の設定が必要です：

{
  "extends": ["plugin:prettier/recommended"]
}

設定 "extends": ["plugin:prettier/recommended"] を追加すると、以下の設定が充填されます：

{
  "extends": ["prettier"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error",
    "arrow-body-style": "off",
    "prefer-arrow-callback": "off"
  }
}

その他の問題#

特殊なルール：

Prettier が上書きしたいくつかの特殊ルールに注意してください。例えば、vue/html-self-closing などのルールはデフォルトで無効になりますので、必要に応じて rules で設定してください。

提交門禁#

以上はコードフォーマットを統一するためのツールですが、コードがコードリポジトリにコミットされる際にフォーマットされていることを保証するものではありません。husky を使用すると、コミット前にコードをチェックし、コミットされるコードがチームの規範に従っていることを確認できます。

Husky#

Git hooks made easy 🐶 woof!

husky は npm プロジェクトに Git hook を介入させる能力を提供します。すべての Git hook をサポートしていますが、一般的には pre-commit と commit-msg のみを使用します。

pre-commit はコミット前のチェックに使用され、commit-msg はコミットメッセージの検証に使用されます。

# husky をインストール
npm install husky --save-dev
# Git hook を有効化
npx husky install
# npm の prepare コマンドを設定し、依存関係のインストール後に特定のスクリプトを自動的に実行します
# 注意：pkg を使用するには npm 7 以上が必要です
npm pkg set scripts.prepare="husky install"

pkg を使用できない場合は、package.json に直接設定できます：

{
  "scripts": {
    "prepare": "husky install"
  }
}

その後、husky add <file> [cmd] の形式で hook をトリガーするコマンドを追加できます。次に、pre-commit と commit-msg で使用する lint-staged と commitlint について紹介します。

lint-staged#

ステージされた git ファイルに対してリンターを実行し、💩 がコードベースに滑り込むのを防ぎます！

ESLint を新たに導入したコードベースでは、毎回すべてのファイルをチェックし、通らなければコミットを許可しないのは少し厳しいですよね？ lint-staged を使用すると、現在のコミットファイルのみを検証し、プロジェクトのコードスタイルを段階的に更新できます。

インストール#

npm install --save-dev lint-staged

設定#

設定ファイル名は .lintstagedrc です。lint-staged の設定は比較的短いため、package.json の lint-staged オブジェクトに直接書くことができます。

設定例：

{
  "src/**/*.{ts,js}": ["eslint --cache --fix"],
  "src/**/*.{json,less}": ["prettier --write"]
}

husky トリガー#

# husky がインストールされている前提で実行
npx husky add .husky/pre-commit "npx lint-staged"

commitlint#

commitlint は、コミットメッセージが規範に従っているかどうかを検証できます。

簡単に言うと、次のような形式です：type(scope?): subject。実際の例は次のようになります：feat(blog): add comment section。詳細な規範は理解するためのセマンティックコミットを参照してください。

インストール#

npm install --save-dev @commitlint/config-conventional @commitlint/cli

設定#

設定ファイル名は .commitlintrc で、設定例は次のとおりです：

{
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新機能（feature）
        'fix', // バグ修正
        'docs', // ドキュメント（documentation）
        'style', // スタイル（コードの実行に影響しない変更）
        'refactor', // リファクタリング（新機能でもバグ修正でもないコードの変更）
        'test', // テストの追加
        'revert', // ロールバック
        'chore', // ビルドプロセスや補助ツールの変更
        'perf', // パフォーマンスの最適化
        'types' // typescript 型定義ファイルの変更
      ]
    ],
    'type-case': [0],
    'type-empty': [0],
    'scope-empty': [0],
    'scope-case': [0],
    'subject-full-stop': [0, 'never'],
    'subject-case': [0, 'never'],
    'header-max-length': [0, 'always', 72]
  }
}

Github でより完全な記入例を確認できます。

husky トリガー#

# husky がインストールされている前提で実行
npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'

パッケージマネージャー#

固定のパッケージマネージャーを使用します。一般的に以下のいくつかの選択肢があります：

• npm
• yarn < v2
• yarn ≥ v2
• performant npm (pnpm)

いくつかの管理者の違いを迅速に理解したい場合は、《速通 npm、yarn、pnpm》を参照してください。また、《JavaScript パッケージマネージャーの比較：npm、Yarn、または pnpm？》を強くお勧めします。内容が包括的で明確であり、以下のパフォーマンス比較図を引用します：

好みや互換性に応じて選択できますが、どの管理者を選択しても、非必要時には lock ファイルを削除しないでください！！！ 依存関係をインストールする際、管理者は依存バージョンを計算する必要があり、非常に時間がかかります。lock があれば、lock リストに従って直接インストールできます。

ただし、lock がある場合、依存関係のダウンロード先は固定されるため、リポジトリの設定は無効になり、継続的インテグレーション時に注意が必要です。

P.S. 異なる管理者で husky を設定する際に若干の違いがあるかもしれません。

エンジンバージョン#

依存関係の lock ファイルを保持している場合、現在のアプリケーションに適合する node バージョンを記録することも非常に重要です。異なる node バージョンは異なる依存関係をダウンロードさせる可能性があり、依存関係が現在の node バージョンに適合しない場合もあります。また、古いプロジェクトでは、古い node バージョンでなければ実行できない場合がありますが、引き継ぐ際にどのバージョンを使用しているか全くわからないというのは非常に困ります。

この問題を解決するために、package.json で node と npm のバージョンを指定できます：

{
  "engines": {
    "node": ">=0.10.3 <15",
    "npm": "~1.0.20"
  }
}

チームの人数が多く、プロジェクトが多い場合、皆のバージョンが異なることがよくあります。必要に応じて、node バージョン管理ツールを使用することをお勧めします。ここでは、以下の 3 つを推奨します：

• nvm unix, macOS nvm-windows Windows
• n macOS, Linux
• fnm macOS, Windows, Linux

基本的に、一行のコマンドでバージョンをインストールし、一行のコマンドでバージョンを切り替えることができ、非常に便利です。

.npmrc#

ファイル名に rc が含まれていることから、.npmrc の役割はプロジェクトレベルの npm 設定を追加することです。例えば：

• リポジトリを変更することができます。会社によっては独自のミラーがある場合があり、.npmrc で設定することで、毎回インストール時に一連のパラメータを持ち歩く必要がなく、全体の設定に影響を与えません。
• また、面倒な sass のようなバイナリパッケージのダウンロード先を追加することもできます。

registry=https://mirrors.huaweicloud.com/repository/npm/
sass_binary_site=https://npm.taobao.org/mirrors/node-sass/

ブランチ戦略#

ブランチ戦略を選択します。以下の 3 つの戦略を選択するか、これらの戦略を基にしてチームに最も適した戦略を調整できます：

• GitFlow
• OneFlow
• AoneFlow

まとめ#

• ESlint と Prettier を使用してコード規範とコードスタイルを制御します。
• VSCode プラグインを追加して、現在のファイルを迅速にフォーマットします。
• 提出門禁を追加して、バージョン管理にアップロードされるコードが規範に従っていることを保証します。
• husky を使用してコミットフックを追加し、コミットの成功を制御します。
• lint-staged は、今回のコミットファイルのみをチェックし、プロジェクトのコード規範を段階的に制御するのに役立ちます。
• commitlint はコミットメッセージの可読性を保証します。
• チーム内で統一のパッケージマネージャーを使用し、依存関係の lock ファイルを保持します。
• エンジンバージョンを固定し、依存関係の変化を防ぎ、古いプロジェクトがどのバージョンで実行されるかわからないという困難を避けます。
• .npmrc を使用してリポジトリなどの設定を固定します。
• ブランチ戦略を選択し、コードの履歴をより整然とします。

皆さん、見ていて漏れがあると思ったり、わからないことがあれば、また補足します！