feat: json config and docs

Kong · Jun 5, 2024 · f0e84d7 · f0e84d7
1 parent 3af8eab
commit f0e84d7
Show file tree

Hide file tree

Showing 4 changed files with 170 additions and 55 deletions.
diff --git 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
@@ -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
@@ -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
@@ -9,6 +9,8 @@
   ],
   "exports": {
     ".": "./configs/index.mjs",
+    "./default": "./configs/index.mjs",
+    "./json": "./configs/json.mjs",
     "./package.json": "./package.json",
     "./dist/*": "./dist/*"
   },