Add docs (#76)

* feat: add readme * feat: add CONTRIBUTING guide * feat: add docs about eslint flat config * feat: add eslint vscode config * feat: add docs about tseslint * docs: add comment to eslint configs * docs: add typescript-eslint to install instruction * feat: update README.md eslint example * feat: add prettier vscode setup * docs: add package detail * feat: add vscode setup for stylelint * feat: add vscode setup for typescript * docs: add monorepo warning in stylelint * chore: changeset * Revert "chore: changeset" This reverts commit 4259e94. * chore: changeset
VirtualLiveLab · Apr 25, 2024 · b8264e5 · b8264e5
1 parent 65202a5
commit b8264e5
Show file tree

Hide file tree

Showing 16 changed files with 397 additions and 13 deletions.
diff --git a/.changeset/new-bikes-rhyme.md b/.changeset/new-bikes-rhyme.md
@@ -0,0 +1,8 @@
+---
+"@virtual-live-lab/stylelint-config": patch
+"@virtual-live-lab/prettier-config": patch
+"@virtual-live-lab/eslint-config": patch
+"@virtual-live-lab/tsconfig": patch
+---
+
+add documentation
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,20 @@
+
+# How to contribute
+
+## Did you find a bug?
+
+If you have problems with the presets or configs working, please post an Issue. A GitHub repository that can reproduce the issue would be greatly appreciated. Also, please include any relevant editor extension versions or settings that may be affected.
+
+## Modify the codes
+
+If you want to modify the code, fork the repository and create a pull request. Please follow the guidelines below.
+
+1. Please open an issue before creating a pull request.
+2. Fork the repository.
+3. Create a branch for your changes. Branch name should include the issue number.
+4. modify the code.
+5. commit your changes. We recommend to use [conventional commit](https://www.conventionalcommits.org/ja/v1.0.0/).
+6. Run `pnpm run build` at the root of the repository and ensure that there are no errors.
+7. Run `pnpm run changeset` at the root of the repository and select the package you want to modify, then input your changes.
+8. Congratulations! You are ready to create a pull request.
+9. You should include `closes #<issue number>` or `fixes #<issue number>` in the pull request description. It will automatically close the issue when the pull request is merged.
diff --git a/README.md b/README.md
@@ -0,0 +1,34 @@
+
+# @virtual-live-lab/js-config
+
+このリポジトリは、バーチャルライブ研究会(VLL)内で利用されるJavaScript / TypeScript関連のツールチェインの設定を統一するためのライブラリリポジトリです。
+
+`packages`以下に各パッケージを配置したモノレポになっており、[changesets](https://github.com/changesets/changesets)を用いてリリースフローを自動化しています。
+
+現時点で以下のパッケージが含まれています。
+
+- ESLint: `@virtual-live-lab/eslint-config`
+  - Lint / error check for JavaScript / TypeScript
+- Prettier: `@virtual-live-lab/prettier-config`
+  - Code formatter for JavaScript / TypeScript / CSS and more
+- Stylelint: `@virtual-live-lab/stylelint-config`
+  - Lint / error check for CSS / SCSS
+- TypeScript: `@virtual-live-lab/tsconfig`
+  - TypeScript configuration presets
+
+今後JS / TSユーテリティライブラリを追加する可能性があります。
+
+## パッケージごとの詳細
+
+### インストール方法
+
+各packageのREADMEを参照してください。
+
+### 各パッケージごとのドキュメント
+
+各packageの`docs`ディレクトリを参照してください。
+
+## Contribution
+
+部員及び外部の方からのContributionを歓迎します。
+詳しくは`CONTRIBUTING.md`を参照してください。
diff --git a/packages/eslint-config/README.md b/packages/eslint-config/README.md
@@ -28,21 +28,19 @@ npm install eslint \
 npm install eslint \
   @virtual-live-lab/eslint-config \
   typescript \
+  typescript-eslint \
   --save-dev
 ```
 
 ## presets
 
 This package has some presets to zero-config use.
 
-> [!WARNING]
-> Next.js is not supported by the preset because each version of the framework has a different version of the ESLint package.
-
 ### JavaScript Preset
 
 ```js
 // eslint.config.mjs
-export { default } from "@virtual-live-lab/eslint-config/js"
+export { default } from "@virtual-live-lab/eslint-config/presets/js"
 ```
 
 ### TypeScript Preset
@@ -51,7 +49,7 @@ Extends `js` preset.
 
 ```js
 // eslint.config.mjs
-export { default } from "@virtual-live-lab/eslint-config/ts"
+export { default } from "@virtual-live-lab/eslint-config/presets/ts"
 ```
 
 ### React Preset
@@ -60,7 +58,23 @@ Extends `ts` preset.
 
 ```js
 // eslint.config.mjs
-export { default } from "@virtual-live-lab/eslint-config/react"
+export { default } from "@virtual-live-lab/eslint-config/presets/react"
+```
+
+### Next.js Preset
+
+Extends `ts` and `react` preset.
+
+> [!TIP]
+> you need to install `eslint-config-next` package as devDependencies.
+> Normally, it will be installed automatically when use `create-next-app`.
+
+> [!WARNING]
+> This preset may be removed in the future. Please read the comments in `src/base/nextjs.ts` for more information.
+
+```js
+// eslint.config.mjs
+export { default } from "@virtual-live-lab/eslint-config/presets/nextjs"
 ```
 
 ### Astro Preset
@@ -69,7 +83,7 @@ Extends `ts` and `react` presets.
 
 ```js
 // eslint.config.mjs
-export { default } from "@virtual-live-lab/eslint-config/astro"
+export { default } from "@virtual-live-lab/eslint-config/presets/astro"
 ```
 
 ## Addons
@@ -81,23 +95,29 @@ This package has some addon configurations.
 ```js
 // eslint.config.mjs
 import jsxA11y from "@virtual-live-lab/eslint-config/addons/jsxA11y"
-import ts from "@virtual-live-lab/eslint-config/ts"
+import ts from "@virtual-live-lab/eslint-config/presets/ts"
 
-const config = [...ts, ...jsxA11y]
+import tseslint from "typescript-eslint"
 
-export default config
+export default tseslint.config(
+  ...ts,
+  ...jsxA11y
+)
 ```
 
 ### Tailwind CSS
 
 ```js
 // eslint.config.mjs
 import tailwind from "@virtual-live-lab/eslint-config/addons/tailwind"
-import ts from "@virtual-live-lab/eslint-config/ts"
+import ts from "@virtual-live-lab/eslint-config/presets/ts"
 
-const config = [...ts, ...jsxA11y]
+import tseslint from "typescript-eslint"
 
-export default config
+export default tseslint.config(
+  ...ts,
+  ...tailwind
+)
 ```
 
 ## License

diff --git a/packages/eslint-config/docs/flat-config.md b/packages/eslint-config/docs/flat-config.md
@@ -0,0 +1,77 @@
+
+# Flat Configについて
+
+Flat Configは、ESLint v9でデフォルトになった新しいESLintの設定ファイルの形式です。
+今後`.eslintrc.js`フォーマットの設定はサポートされなくなり、また古い形式の設定ファイルと互換を取るための`FlatCompat`が提供されているので、
+このパッケージでは**Flat Configのみをサポート**する判断をしました。
+
+FlatConfigのドキュメントはここから読めます。
+
+<https://eslint.org/docs/latest/use/configure/configuration-files>
+
+## Flat Configを拡張する
+
+すべてのPresetかAddonは`TSESLint.FlatConfig.ConfigArray`の型になっています。
+ただし、例外的に`@virtual-live-lab/eslint-config/presets/js`のjsプリセットのみ`ESLint.Linter.FlatConfig[]`になっています。
+
+ただし、VLLでは基本的にTypeScriptを使いますので、`tseslint.config()`関数を使って`TSESLint`ベースで設定を拡張することを強く推奨します。
+
+> [!TIP]
+> 下の例で示した`languageOptions`の設定は場合によって必要になります。まだ完全な理由を解明できていません。詳細は`tseslint.md`を参照してください。
+
+```js
+import ts from "@virtual-live-lab/eslint-config/presets/ts";
+import hogehoge from "eslint-config-hogehoge";
+
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  ...ts,
+  ...hogehoge.configs.recommended,
+  languageOptions: {
+    parser: tseslint.parser,
+  },
+);
+```
+
+TypeScriptを使わない場合は、`ESLint.Linter.FlatConfig[]`を使ってください。
+
+<details>
+  <summary>`ESLint.Linter.FlatConfig[]`形式での拡張</summary>
+
+> [!WARNING]
+> この設定方法は推奨されません
+
+```js
+import js from "@virtual-live-lab/eslint-config/presets/js";
+import hogehoge from "eslint-config-hogehoge";
+
+/* @type {import("eslint").Linter.FlatConfig[]} */
+export default [
+  ...js,
+  ...hoehoge.configs.recommended
+];
+```
+
+</details>
+
+## `.eslintrc.js`形式との互換性
+
+`presets`や`addons`にないかつFlat Configに対応していないものも、
+
+```js
+import { compat } from "@virtual-live-lab/eslint-config";
+
+export default [
+  ...compat.extends("plugin:hogehoge/recommended")
+];
+```
+
+のようにすることで`.eslintrc.js`形式のsyntaxのルールを利用できます。
+
+`compat`は以下のドキュメントで説明されている`FlatCompat`のbaseDirectoryを自動的に設定してインスタンス化したあとのものです。
+<https://eslint.org/docs/latest/use/configure/migration-guide#using-eslintrc-configs-in-flat-config>
+
+なお、`FlatCompat`から利用できる機能の詳細はこちらから確認できます。
+
+<https://github.com/eslint/eslintrc#usage>
diff --git a/packages/eslint-config/docs/tseslint.md b/packages/eslint-config/docs/tseslint.md
@@ -0,0 +1,49 @@
+
+# typescript-eslintについて
+
+VLLでは基本的にTypeScriptを利用しますが、ESLintは本来TypeScriptに対応していません。そこで、[typescript-eslint](https://github.com/typescript-eslint/typescript-eslint)を利用します。
+
+## Lint with type information
+
+typescript-eslintはTypeScriptの型情報を用いた高度なLintingができますが、稀に型情報を正しく読み取れずにエラーが出る場合があります。
+
+その場合は、以下の手順で対処してください。
+
+1. プリセットのimport方法を変更する
+
+```diff
+- export { default } from "@virtual-live-lab/eslint-config/presets/ts";
++ import ts from "@virtual-live-lab/eslint-config/presets/ts";
+
+```
+
+2. typescript-eslintを使ってexportする
+
+```diff
+import ts from "@virtual-live-lab/eslint-config/presets/ts";
+
++ import tseslint from "typescript-eslint";
+
++ export default tseslint.config(
++ ...ts,
++ );
+```
+
+3. TypeScript parserを設定する
+
+```diff
+
+import ts from "@virtual-live-lab/eslint-config/presets/ts";
+
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+...ts,
++   languageOptions: {
++     parser: tseslint.parser,
++   },
+);
+
+```
+
+もしこれで治らない場合はIssueを立ててください。
diff --git a/packages/eslint-config/docs/vscode-setup.md b/packages/eslint-config/docs/vscode-setup.md
@@ -0,0 +1,53 @@
+
+# Setup ESLint with VSCode
+
+VLLでは基本的にVSCodeの利用を推奨しています。ここではVSCodeにESLintを統合してこのリポジトリのプリセットを動かすための設定を説明します。
+
+## ESLint VSCode Extension
+
+[Marketplace](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)からインストールしてください。
+
+## VSCode configuration
+
+### Essentials
+
+基本的にこのpackageのプリセットを使う場合以下の設定が必須となります。
+`<repository>/.vscode/settings.json`に追記してください。
+
+```json
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+  },
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact"
+  ],
+  "eslint.experimental.useFlatConfig": true,
+  "eslint.options": {
+    "overrideConfigFile": "eslint.config.mjs"
+  },
+  "eslint.workingDirectories": [
+    {
+      "mode": "auto"
+    }
+  ],
+}
+```
+
+### Use with Astro
+
+上の設定の`eslint.validate`を以下のように変更してください。
+
+```json
+{
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "astro"
+  ],
+}
diff --git a/packages/eslint-config/src/addons/tailwind.ts b/packages/eslint-config/src/addons/tailwind.ts
@@ -3,6 +3,12 @@ import { compat } from "../lib/compat"
 const tailwind = [
   ...compat.extends("plugin:tailwindcss/recommended"),
   ...compat.config({
+    /*
+    tailwind-variantsを併用する際に、`ignoredKeys`に
+    `responsiveVariants`が追加されていないのでWarningが出る
+    そのため、こちら側で`ignoredKeys`に`responsiveVariants`を追加している
+    本家にPRを送るのでMergeされたらいらなくなる
+    */
     rules: {
       "tailwindcss/no-custom-classname": [
         "warn",

diff --git a/packages/eslint-config/src/base/astro.ts b/packages/eslint-config/src/base/astro.ts
@@ -5,6 +5,8 @@ import eslintPluginAstro from "eslint-plugin-astro"
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
 const astroConfig: Linter.FlatConfig[] = [
   ...eslintPluginAstro.configs["flat/recommended"],
+  // flat/jsx-a11y-strictは、eslint-plugin-jsx-a11yの設定をベースにしているので、
+  // インストールされていないとエラーになるが、このパッケージはdependenciesに含まれているので問題ない
   // @ts-expect-error no types
   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
   ...eslintPluginAstro.configs["flat/jsx-a11y-strict"],

diff --git a/packages/eslint-config/src/base/nextjs.ts b/packages/eslint-config/src/base/nextjs.ts
@@ -5,6 +5,13 @@ import { reactConfig } from "./react"
 
 const nextJsConfig: Linter.FlatConfig[] = [
   ...reactConfig,
+  /*
+   この設定は、利用側のnode_modulesからnext/core-web-vitalsを探すので、
+  利用側でeslint-config-nextがインストールされている必要がある
+  Next.js側がFlat Configに対応した場合は更新が必要。
+  Flat対応に際して、このpackageでeslint-config-nextを持ちたくないので、
+  Next.jsプリセットを削除するBreaking Changeを行う可能性が高い
+  */
   ...compat.extends("next/core-web-vitals"),
 ]
 

diff --git a/packages/eslint-config/src/base/typescript.ts b/packages/eslint-config/src/base/typescript.ts
@@ -14,6 +14,7 @@ const tsConfig = tseslint.config({
     },
   },
   rules: {
+    // SEE: https://zenn.dev/cybozu_frontend/articles/ts-eslint-v6-guide
     // stylistic を有効にしたため v5 の recommended にないルールを無効化
     "@typescript-eslint/array-type": "off",
     "@typescript-eslint/ban-tslint-comment": "off",