From b8264e5162fdee078d1505203411f83db0f50941 Mon Sep 17 00:00:00 2001 From: Kentaro Suzuki Date: Thu, 25 Apr 2024 12:02:38 +0900 Subject: [PATCH] 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 4259e94c0ec0fc4f2f3e31bdaf068cb397088de5. * chore: changeset --- .changeset/new-bikes-rhyme.md | 8 ++ CONTRIBUTING.md | 20 +++++ README.md | 34 ++++++++ packages/eslint-config/README.md | 46 +++++++---- packages/eslint-config/docs/flat-config.md | 77 +++++++++++++++++++ packages/eslint-config/docs/tseslint.md | 49 ++++++++++++ packages/eslint-config/docs/vscode-setup.md | 53 +++++++++++++ packages/eslint-config/src/addons/tailwind.ts | 6 ++ packages/eslint-config/src/base/astro.ts | 2 + packages/eslint-config/src/base/nextjs.ts | 7 ++ packages/eslint-config/src/base/typescript.ts | 1 + packages/eslint-config/src/lib/compat.ts | 1 + packages/prettier-config/docs/vscode-setup.md | 36 +++++++++ packages/stylelint-config/README.md | 3 + .../stylelint-config/docs/vscode-setup.md | 40 ++++++++++ packages/tsconfig/docs/vscode-setup.md | 27 +++++++ 16 files changed, 397 insertions(+), 13 deletions(-) create mode 100644 .changeset/new-bikes-rhyme.md create mode 100644 CONTRIBUTING.md create mode 100644 packages/eslint-config/docs/flat-config.md create mode 100644 packages/eslint-config/docs/tseslint.md create mode 100644 packages/eslint-config/docs/vscode-setup.md create mode 100644 packages/prettier-config/docs/vscode-setup.md create mode 100644 packages/stylelint-config/docs/vscode-setup.md create mode 100644 packages/tsconfig/docs/vscode-setup.md diff --git a/.changeset/new-bikes-rhyme.md b/.changeset/new-bikes-rhyme.md new file mode 100644 index 0000000..f7ed2a9 --- /dev/null +++ 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 new file mode 100644 index 0000000..f64c15d --- /dev/null +++ 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 #` or `fixes #` 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 index e69de29..143ad44 100644 --- 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 index de85c77..a778e4d 100644 --- a/packages/eslint-config/README.md +++ b/packages/eslint-config/README.md @@ -28,6 +28,7 @@ npm install eslint \ npm install eslint \ @virtual-live-lab/eslint-config \ typescript \ + typescript-eslint \ --save-dev ``` @@ -35,14 +36,11 @@ npm install eslint \ 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,11 +95,14 @@ 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 @@ -93,11 +110,14 @@ export default config ```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 new file mode 100644 index 0000000..61a571a --- /dev/null +++ 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のドキュメントはここから読めます。 + + + +## 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[]`を使ってください。 + +
+ `ESLint.Linter.FlatConfig[]`形式での拡張 + +> [!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 +]; +``` + +
+ +## `.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を自動的に設定してインスタンス化したあとのものです。 + + +なお、`FlatCompat`から利用できる機能の詳細はこちらから確認できます。 + + diff --git a/packages/eslint-config/docs/tseslint.md b/packages/eslint-config/docs/tseslint.md new file mode 100644 index 0000000..8fa0422 --- /dev/null +++ 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 new file mode 100644 index 0000000..5250cda --- /dev/null +++ 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のプリセットを使う場合以下の設定が必須となります。 +`/.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 index 9aea10b..1ba64f2 100644 --- 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 index 8bef6cd..1d7ab64 100644 --- 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 index a42b8ff..a676b54 100644 --- 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 index e5507b6..f2d6d2f 100644 --- 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", diff --git a/packages/eslint-config/src/lib/compat.ts b/packages/eslint-config/src/lib/compat.ts index fd80ebf..6f6ab5f 100644 --- a/packages/eslint-config/src/lib/compat.ts +++ b/packages/eslint-config/src/lib/compat.ts @@ -2,6 +2,7 @@ import { FlatCompat } from "@eslint/eslintrc" import { __dirname } from "./dir" +// 最も近いpackage.jsonを探索して、そのディレクトリをbaseDirectoryとして設定 const compat = new FlatCompat({ baseDirectory: __dirname }) export { compat } diff --git a/packages/prettier-config/docs/vscode-setup.md b/packages/prettier-config/docs/vscode-setup.md new file mode 100644 index 0000000..b996fc0 --- /dev/null +++ b/packages/prettier-config/docs/vscode-setup.md @@ -0,0 +1,36 @@ + +# Setup Prettier with VSCode + +VLLでは基本的にVSCodeの利用を推奨しています。ここではVSCodeにPrettierを統合してこのリポジトリのプリセットを動かすための設定を説明します。 + +## Prettier VSCode Extension + +[Marketplace](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)からインストールしてください。 + +## VSCode configuration + +### Essentials + +基本的にこのpackageのプリセットを使う場合以下の設定が必須となります。 +`/.vscode/settings.json`に追記してください。 + +> [!TIP] +> もしこの設定をしてPrettierが使われない場合はユーザー設定で言語に対するデフォルトフォーマッタが設定されている可能性があります。 +> +> その場合は言語ごとのdefault formatterを上書きする設定を追加してください。 + +```json +{ + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true, +} +``` + +### Use with Astro + +上の設定に以下を追加してください。 + +```json +{ + "prettier.documentSelectors": ["**/*.astro"] +} diff --git a/packages/stylelint-config/README.md b/packages/stylelint-config/README.md index afa2948..3d2129f 100644 --- a/packages/stylelint-config/README.md +++ b/packages/stylelint-config/README.md @@ -7,6 +7,9 @@ Stylelint configuration for Virtual Live Lab. ## Installation +> [!WARNING] +> monorepoを利用してる場合、利用するすべてのワークスペースでインストールしてください。 + ### Use for css ```bash diff --git a/packages/stylelint-config/docs/vscode-setup.md b/packages/stylelint-config/docs/vscode-setup.md new file mode 100644 index 0000000..2f43f36 --- /dev/null +++ b/packages/stylelint-config/docs/vscode-setup.md @@ -0,0 +1,40 @@ + +# Setup Stylelint with VSCode + +VLLでは基本的にVSCodeの利用を推奨しています。ここではVSCodeにStylelintを統合してこのリポジトリのプリセットを動かすための設定を説明します。 + +## Stylelint VSCode Extension + +[Marketplace](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)からインストールしてください。 + +## VSCode configuration + +### Essentials + +基本的にこのpackageのプリセットを使う場合以下の設定が必須となります。 +`/.vscode/settings.json`に追記してください。 + +> [!TIP] +> `stylelint.packageManager`をnpm, yarn, pnpmの中からリポジトリに合わせたものに変更してください。`bun`はないようです。 +> +> 設定しなかった場合、稀にStylelint VSCode Extensionがインストールされたstylelintの検出に失敗することがあります。 + +```json +{ + "editor.codeActionsOnSave": { + "source.fixAll.stylelint": "explicit" + }, + "stylelint.validate": ["css", "postcss", "scss"], + "stylelint.packageManager": "PROJECT_PACKAGE_MANAGER", +} +``` + +### Use with Astro + +上の設定の`stylelint.validate`を以下のように変更してください。 + +```json +{ + "stylelint.validate": ["css", "postcss", "scss", "astro"], +} +``` diff --git a/packages/tsconfig/docs/vscode-setup.md b/packages/tsconfig/docs/vscode-setup.md new file mode 100644 index 0000000..0308963 --- /dev/null +++ b/packages/tsconfig/docs/vscode-setup.md @@ -0,0 +1,27 @@ + +# Setup TypeScript with VSCode + +VLLでは基本的にVSCodeの利用を推奨しています。ここではVSCodeにStylelintを統合してこのリポジトリのプリセットを動かすための設定を説明します。 + +## VSCode configuration + +VSCodeはもともとTypeScriptをサポートしているので特に拡張機能は必要ありません。 +(というかTypeScriptもVSCodeもMicrosoft製なので。) + +以下の設定を`/.vscode/settings.json`に追記してください。 + +> [!TIP] +> monorepoを利用している場合、ワークスペースルートにtypescriptをインストールする必要があります。 +> +> **基本的にpnpm workspaceのみを想定しています。** +> +> ```bash +> pnpm install -wD typescript +> ``` + +```json +{ + "typescript.tsdk": "node_modules/typescript/lib", + "typescript.enablePromptUseWorkspaceTsdk": true, +} +```