From f0e84d77724436cceae64cfcae8f942ddb37f9f2 Mon Sep 17 00:00:00 2001 From: Adam DeHaven Date: Wed, 5 Jun 2024 11:37:11 -0400 Subject: [PATCH] feat: json config and docs --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++ configs/index.mjs | 55 ------------------------- configs/json.mjs | 65 +++++++++++++++++++++++++++++ package.json | 2 + 4 files changed, 170 insertions(+), 55 deletions(-) create mode 100644 configs/json.mjs diff --git a/README.md b/README.md index 2d662b4..0f6405a 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,10 @@ A [shared ESLint configuration](https://eslint.org/docs/latest/extend/shareable- - [Usage](#usage) - [Installation](#installation) + - [Available Configs](#available-configs) + - [Setup](#setup) + - [Overriding settings from the shared config](#overriding-settings-from-the-shared-config) + - [Apply a config to a subset of files](#apply-a-config-to-a-subset-of-files) - [Contributing \& Local Development](#contributing--local-development) - [Lint and fix](#lint-and-fix) - [Committing Changes](#committing-changes) @@ -27,6 +31,105 @@ pnpm add -D @kong/eslint-config-kong-ui pnpm add -wD @kong/eslint-config-kong-ui ``` +### Available Configs + +This package exports several ESLint configurations to use in your project. Read through the available configs below, and see the [Setup](#setup) section for instructions on how to add them to your project. + +#### Default config + +The default config provides linting for files matching this pattern `**/*.{js,mjs,cjs,jsx,ts,tsx,vue}` and includes rules configured via: + +- ESLint recommended rules +- TypeScript recommended rules +- `eslint-plugin-vue` +- `eslint-plugin-promise` +- `eslint-plugin-cypress` +- [ESLint Stylistic](https://eslint.style/) rules configured for our preferred formatting settings +- ...and more. See [`index.mjs`](./configs/index.mjs) to view the configuration. + +The default config can be imported as shown here: + +```javascript +import eslintKongUiConfig from '@kong/eslint-config-kong-ui' +// or +import eslintKongUiConfig from '@kong/eslint-config-kong-ui/default' +``` + +#### JSON config + +The JSON config provides linting for files matching this pattern `**/*.{json,jsonc}` and includes rules configured via: + +- `eslint-plugin-jsonc` + +The JSON config can be imported as shown here: + +```javascript +import eslintKongUiConfigJson from '@kong/eslint-config-kong-ui/json' +``` + +> [!Note] +> You will likely only want to apply the JSON config to a subset of file patterns in your project. See the section on [applying a config to a subset of files](#apply-a-config-to-a-subset-of-files) for detailed instructions. + +### Setup + +To use the shared config, import the package inside of an `eslint.config.mjs` file and add it into the exported array, like this: + +```javascript +// eslint.config.mjs +import eslintKongUiConfig from '@kong/eslint-config-kong-ui' + +export default [ + ...eslintKongUiConfig, +] +``` + +### Overriding settings from the shared config + +You can override settings from the shareable config by adding them directly into your `eslint.config.mjs` file after importing the shareable config. For example: + +```javascript +// eslint.config.mjs +import eslintKongUiConfig from '@kong/eslint-config-kong-ui' + +export default [ + ...eslintKongUiConfig, + // anything from here will override eslintKongUiConfig + { + rules: { + 'no-unused-vars': 'error', + } + } +] +``` + +### Apply a config to a subset of files + +You can [apply a config array to just a subset of files](https://eslint.org/docs/latest/use/configure/combine-configs#apply-a-config-object-to-a-subset-of-files) by using the `map()` method to add a `files` key to each config object. + +For example, you may only want to apply the [JSON config](#json-config) to `**/locales/**/*.json` files in your project (this is our practice at Kong): + +```javascript +// eslint.config.mjs +import eslintKongUiConfig from '@kong/eslint-config-kong-ui' +import eslintKongUiConfigJson from '@kong/eslint-config-kong-ui/json' + +export default [ + // Use the main config for all other files + ...eslintKongUiConfig, + // Only apply the shared JSON config to files that match the given pattern + ...eslintKongUiConfigJson.map(config => ({ + ...config, + files: ['**/locales/**/*.json'] + })), + // your modifications + { + rules: { + 'no-unused-vars': 'error', + } + } +] +``` + ## Contributing & Local Development To get started, install the package dependencies diff --git a/configs/index.mjs b/configs/index.mjs index 63730b1..16a4b05 100644 --- a/configs/index.mjs +++ b/configs/index.mjs @@ -3,8 +3,6 @@ import tseslint from 'typescript-eslint' import vueParser from 'vue-eslint-parser' import pluginVue from 'eslint-plugin-vue' import stylistic from '@stylistic/eslint-plugin' -import eslintPluginJsonc from 'eslint-plugin-jsonc' -import jsonParser from 'jsonc-eslint-parser' import globals from 'globals' // Compatibility utils @@ -25,9 +23,6 @@ export default [ ...compat.config({ extends: ['plugin:cypress/recommended'], }), - // JSON formatting for locale files - ...eslintPluginJsonc.configs['flat/base'], - ...eslintPluginJsonc.configs['flat/recommended-with-json'], // Global ignores { ignores: [ @@ -158,54 +153,4 @@ export default [ extends: ['plugin:cypress/recommended'], }), }, - { - files: [ - '**/src/locales/**/*.json', - ], - ignores: [ - // App directories - 'apps/signin/auth0-templates/**/*.json', - // Common ignores for JSON linting - '**/package.json', - '**/renovate.json', - '**/tsconfig.json', - '**/tsconfig.*.json', - ], - languageOptions: { - parser: jsonParser, - ecmaVersion: 'latest', - sourceType: 'module', - }, - rules: { - 'jsonc/indent': ['error', 2, {}], - 'jsonc/key-name-casing': ['error', - { - camelCase: false, - PascalCase: false, - SCREAMING_SNAKE_CASE: false, - 'kebab-case': false, - snake_case: true, - ignores: [], - }, - ], - 'jsonc/sort-keys': ['error', - { - pathPattern: '.*', - order: { - type: 'asc', - natural: true, - caseSensitive: true, - }, - minKeys: 2, - }, - ], - 'jsonc/key-spacing': ['error', - { - beforeColon: false, - afterColon: true, - mode: 'strict', - }, - ], - }, - }, ] diff --git a/configs/json.mjs b/configs/json.mjs new file mode 100644 index 0000000..2f62a62 --- /dev/null +++ b/configs/json.mjs @@ -0,0 +1,65 @@ +import eslintPluginJsonc from 'eslint-plugin-jsonc' +import jsonParser from 'jsonc-eslint-parser' + +export default [ + // JSON formatting for locale files + ...eslintPluginJsonc.configs['flat/base'], + ...eslintPluginJsonc.configs['flat/recommended-with-json'], + // Global ignores + { + ignores: [ + '**/node_modules/', + '**/dist/', + '**/public/', + '**/bin/', + ], + }, + { + files: [ + '**/*.{json,jsonc}', + ], + ignores: [ + // Common ignores for JSON linting + '**/package.json', + '**/renovate.json', + '**/tsconfig.json', + '**/tsconfig.*.json', + ], + languageOptions: { + parser: jsonParser, + ecmaVersion: 'latest', + sourceType: 'module', + }, + rules: { + 'jsonc/indent': ['error', 2, {}], + 'jsonc/key-name-casing': ['error', + { + camelCase: false, + PascalCase: false, + SCREAMING_SNAKE_CASE: false, + 'kebab-case': false, + snake_case: true, + ignores: [], + }, + ], + 'jsonc/sort-keys': ['error', + { + pathPattern: '.*', + order: { + type: 'asc', + natural: true, + caseSensitive: true, + }, + minKeys: 2, + }, + ], + 'jsonc/key-spacing': ['error', + { + beforeColon: false, + afterColon: true, + mode: 'strict', + }, + ], + }, + }, +] diff --git a/package.json b/package.json index 15bc712..4686acd 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,8 @@ ], "exports": { ".": "./configs/index.mjs", + "./default": "./configs/index.mjs", + "./json": "./configs/json.mjs", "./package.json": "./package.json", "./dist/*": "./dist/*" },