@zayne-labs/eslint-config 0.0.0 → 0.0.2

package/README.md

@@ -1,50 +1,572 @@
-# Create Ts Library
+# @zayne-labs/eslint-config
 
-This is an opinionated starter template for creating a library with TypeScript.
+- Reasonable defaults, best practices, only one line of config
+- Designed to work with TypeScript, JSX, Vue, JSON, YAML, Toml, Markdown, etc. Out-of-box.
+- Opinionated, but [very customizable](#customization)
+- [ESLint Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), compose easily!
+- Optional [React](#react), [Svelte](#svelte), [TailwindCSS](#tailwindcss), [Astro](#astro), [Solid](#solid) support
+- Respects `.gitignore` by default
+- Requires ESLint v9.5.0+
 
 
 ## Usage
 
-To use this template, simply click the green `Use this template` button at the top right of this repo, or just fork and clone it if you prefer.
-
-## Tooling available
-- Eslint plugins for linting (customizable)
-- Prettier for formatting
-- [TSUP](https://github.com/egoist/tsup) for bundling
-- [@zayne-labs/tsconfig](https://github.com/zayne-labs/tsconfig) for relevant tsconfig presets
-- [Changesets](https://github.com/changesets/changesets) (Both cli and github action which must be installed on the repo) for versioning, publishing, release notes and changelogs
-- [publint](https://github.com/bluwy/publint) and [@arethetypeswrong/cli](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md) for validating package.json and checking for proper package types resolutions respectively.
-- [size-limit](https://github.com/ai/size-limit) for bundle size analysis and management
-- [lint-staged](https://github.com/lint-staged/lint-staged) for lint and types checks on staged files and [husky](https://github.com/typicode/husky) for running lint-staged before any commit and before push if you prefer
-- [pkg.pr.new](https://pkg-pr-new) for continuous testing of packages on every commit before publishing to npm.
-- Various github workflows for:
-  - Linting on ci
-  - Automatic publishing via changesets
-  - Formatting on ci via [autofix.ci](https://autofix.ci/)
-  - Labeling issues
-  - Issue assignment
-  - Continuous release testing via pkg.pr.new github action, etc.
-
-## Setup
-
-- Click the `Use this template` button.
-- Create a new repository with it.
-- Install the necessary github applications and bots on your repo namely:
-  - [aufofix app](https://github.com/marketplace/autofix-ci) for running automatic code fixes
-  - [changesets bot](https://github.com/apps/changeset-bot) for checking if there are any changesets contained in PRs
-  - [pkg.pr.new app](https://github.com/apps/pkg-pr-new) for continuous testing of packages
-- Create npm token [here](https://docs.npmjs.com/creating-and-viewing-access-tokens) (Skip if you already have it handy).
-- Add it as a [secret to your repository](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization#adding-secrets-for-a-repository) (or at the organization level if you have one), using the name `"NPM_TOKEN"`.
-- Install the dependencies using `pnpm install`.
-	- Edit the package.json file, and replace any of these: `[*]`, with the appropriate names relevant to your lib (Did this cuz comments aren't allowed in json files).
-- Lint your changes by running some of the `lint:*` scripts in the package.json.
-- Commit and push your changes.
-
-## To publish a new version
- - Create a changeset via `pnpm changeset` command
- - Follow the prompts
- - Push to github
- - Wait for the changeset action to finish and if it's successful, you should see a pr created by the changeset bot
- - Merging it will lead to the version bump, release and publishing of the package
+### Manual Install
 
+If you prefer to set up manually:
 
+```bash
+pnpm add -D eslint @zayne-labs/eslint-config
+```
+
+And create `eslint.config.js` in your project root:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne()
+```
+
+<details>
+<summary>
+Combined with legacy config:
+</summary>
+
+If you still use some configs from the legacy eslintrc format, you can use the [`@eslint/eslintrc`](https://www.npmjs.com/package/@eslint/eslintrc) package to convert them to the flat config.
+
+```js
+// eslint.config.mjs
+import zayne from '@zayne-labs/eslint-config'
+import { FlatCompat } from '@eslint/eslintrc'
+
+const compat = new FlatCompat()
+
+export default zayne(
+  {
+    ignores: [],
+  },
+
+  // Legacy config
+  [
+	...compat.config({
+    extends: [
+      'eslint:recommended',
+      // Other extends...
+    ],
+  }),
+
+  // Other flat configs...
+  ]
+
+)
+```
+
+> Note that `.eslintignore` no longer works in Flat config, see [customization](#customization) for more details.
+
+</details>
+
+### Add script for package.json
+
+For example:
+
+```json
+{
+  "scripts": {
+    "lint:eslint": "eslint .",
+    "lint:eslint-fix": "eslint . --fix"
+  }
+}
+```
+
+## IDE Support (auto fix on save)
+
+<details>
+<summary>🟦 VS Code support</summary>
+
+<br>
+
+Install [VS Code ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+
+Add the following settings to your `.vscode/settings.json`:
+
+```jsonc
+{
+  // Auto fix
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "never"
+  },
+
+  // Enable eslint for all supported languages
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "vue",
+    "html",
+    "markdown",
+    "json",
+    "jsonc",
+    "yaml",
+    "toml",
+    "xml",
+    "gql",
+    "graphql",
+    "astro",
+    "svelte",
+    "css",
+    "less",
+    "scss",
+    "pcss",
+    "postcss"
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary>🟩 Neovim Support</summary>
+
+<br>
+
+Update your configuration to use the following:
+
+```lua
+local lspconfig = require('lspconfig')
+-- Enable eslint for all supported languages
+lspconfig.eslint.setup(
+  {
+    filetypes = {
+      "javascript",
+      "javascriptreact",
+      "javascript.jsx",
+      "typescript",
+      "typescriptreact",
+      "typescript.tsx",
+      "vue",
+      "html",
+      "markdown",
+      "json",
+      "jsonc",
+      "yaml",
+      "toml",
+      "xml",
+      "gql",
+      "graphql",
+      "astro",
+      "svelte",
+      "css",
+      "less",
+      "scss",
+      "pcss",
+      "postcss"
+    },
+  }
+)
+```
+
+### Neovim format on save
+
+There's few ways you can achieve format on save in neovim:
+
+- `nvim-lspconfig` has a `EslintFixAll` command predefined, you can create a autocmd to call this command after saving file.
+
+```lua
+lspconfig.eslint.setup({
+  --- ...
+  on_attach = function(client, bufnr)
+    vim.api.nvim_create_autocmd("BufWritePre", {
+      buffer = bufnr,
+      command = "EslintFixAll",
+    })
+  end,
+})
+```
+
+- Use [conform.nvim](https://github.com/stevearc/conform.nvim).
+- Use [none-ls](https://github.com/nvimtools/none-ls.nvim)
+- Use [nvim-lint](https://github.com/mfussenegger/nvim-lint)
+
+</details>
+
+## Customization
+
+Normally you only need to import the `zayne` preset:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne()
+```
+
+And that's it! Or you can configure each integration individually, for example:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  // Enable stylistic formatting rules
+  stylistic: true,
+
+  // TypeScript is autodetected, you can also explicitly enable it:
+  typescript: true,
+
+  // Disable jsonc and yaml support
+  jsonc: false,
+  yaml: false,
+
+  // `.eslintignore` is no longer supported in Flat config, use `ignores` instead
+  ignores: [
+    'build/**',
+    // ...globs
+  ]
+})
+```
+
+The `zayne` factory function also accepts an array of arbitrary custom config overrides as the second argument:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne(
+  {
+    // Configures for zayne labs' config
+  },
+
+  // The second arguments is an array of ESLint Configs
+ [ {
+    files: ['**/*.ts'],
+    rules: {},
+  },
+  {
+    rules: {},
+  }],
+)
+```
+
+Going more advanced, you can also import fine-grained configs and compose them as you wish:
+
+<details>
+<summary>Advanced Example</summary>
+
+We wouldn't recommend using this style in general unless you know exactly what they are doing, as there are shared options between configs and might need extra care to make them consistent.
+
+```js
+// eslint.config.js
+import {
+  combine,
+  comments,
+  ignores,
+  imports,
+  javascript,
+  jsdoc,
+  jsonc,
+  markdown,
+  node,
+  sortPackageJson,
+  sortTsconfig,
+  stylistic,
+  toml,
+  typescript,
+  unicorn,
+  vue,
+  yaml,
+} from '@zayne-labs/eslint-config'
+
+export default combine(
+  ignores(),
+  javascript(/* Options */),
+  comments(),
+  node(),
+  jsdoc(),
+  imports(),
+  unicorn(),
+  typescript(/* Options */),
+  stylistic(),
+  vue(),
+  jsonc(),
+  yaml(),
+  toml(),
+  markdown(),
+)
+```
+
+</details>
+
+Check out the [configs](https://github.com/zayne-labs/eslint-config/blob/main/src/configs) and [factory](https://github.com/zayne-labs/eslint-config/blob/main/src/factory.ts) for more details.
+
+> Thanks to [zayne/eslint-config](https://github.com/zayne/eslint-config) for the inspiration and reference.
+
+### Plugins Renaming
+
+Since flat config requires us to explicitly provide the plugin names (instead of the mandatory convention from npm package name), we renamed some plugins to make the overall scope more consistent and easier to write.
+
+| New Prefix | Original Prefix        | Source Plugin                                                                              |
+| ---------- | ---------------------- | ------------------------------------------------------------------------------------------ |
+| `import/*` | `import-x/*`           | [eslint-plugin-import-x](https://github.com/un-es/eslint-plugin-import-x)                  |
+| `node/*`   | `n/*`                  | [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)                     |
+| `yaml/*`   | `yml/*`                | [eslint-plugin-yml](https://github.com/ota-meshi/eslint-plugin-yml)                        |
+| `ts-eslint/*`     | `@typescript-eslint/*` | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint) |
+| `stylistic/*`  | `@stylistic/*`         | [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic)           |
+
+When you want to override rules, or disable them inline, you need to update to the new prefix:
+
+```diff
+-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
++// eslint-disable-next-line ts/consistent-type-definitions
+type foo = { bar: 2 }
+```
+
+
+<details>
+<summary>Change back to original prefix</summary>
+
+If you really want to use the original prefix, you can revert the plugin renaming by:
+
+```ts
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne()
+  .renamePlugins({
+    "ts-eslint": '@typescript-eslint',
+    // ...
+  })
+```
+
+</details>
+
+### Rules Overrides
+
+Certain rules would only be enabled in specific files, for example, `ts/*` rules would only be enabled in `.ts` files and `vue/*` rules would only be enabled in `.vue` files. If you want to override the rules, you need to specify the file extension:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne(
+  {
+    vue: true,
+    typescript: true
+  },
+  {
+    // Remember to specify the file glob here, otherwise it might cause the vue plugin to handle non-vue files
+    files: ['**/*.vue'],
+    rules: {
+      'vue/operator-linebreak': ['error', 'before'],
+    },
+  },
+  {
+    // Without `files`, they are general rules for all files
+    rules: {
+      'stylistic/semi': ['error', 'never'],
+    },
+  }
+)
+```
+
+We also provided the `overrides` options in each integration to make it easier:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  vue: {
+    overrides: {
+      'vue/operator-linebreak': ['error', 'before'],
+    },
+  },
+  typescript: {
+    overrides: {
+      'ts/consistent-type-definitions': ['error', 'interface'],
+    },
+  },
+  yaml: {
+    overrides: {
+      // ...
+    },
+  },
+})
+```
+
+### Config Composer
+
+The factory function `zayne()` returns a [`FlatConfigComposer` object from `eslint-flat-config-utils`](https://github.com/zayne/eslint-flat-config-utils#composer) where you can chain the methods to compose the config even more flexibly.
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne()
+  .prepend(
+    // some configs before the main config
+  )
+  // overrides any named configs
+  .override(
+    'zayne/imports',
+    {
+      rules: {
+        'import/order': ['error', { 'newlines-between': 'always' }],
+      }
+    }
+  )
+  // rename plugin prefixes
+  .renamePlugins({
+    'old-prefix': 'new-prefix',
+    // ...
+  })
+// ...
+```
+
+
+#### React
+
+To enable React support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  react: true,
+})
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D @eslint-react/eslint-plugin eslint-plugin-react-hooks eslint-plugin-react-refresh
+```
+
+#### Svelte
+
+To enable svelte support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  svelte: true,
+})
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-svelte
+```
+
+#### Astro
+
+To enable astro support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  astro: true,
+})
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-astro
+```
+
+#### Solid
+
+To enable Solid support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  solid: true,
+})
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-solid
+```
+
+#### tailwindcss
+
+To enable Tailwindcss support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  tailwindcss: true,
+})
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-tailwindcss
+```
+
+
+### Type Aware Rules
+
+You can optionally enable the [type aware rules](https://typescript-eslint.io/linting/typed-linting/) by passing the options object to the `typescript` config:
+
+```js
+// eslint.config.js
+import zayne from '@zayne-labs/eslint-config'
+
+export default zayne({
+  typescript: {
+    tsconfigPath: 'tsconfig.json',
+  },
+})
+```
+
+
+## View what rules are enabled
+
+Eslint config inspecctor is visual tool to help you view what rules are enabled in your project and apply them to what files, [@eslint/config-inspector](https://github.com/eslint/config-inspector).
+It was built by the legendary Anthony Fu.
+
+Go to your project root that contains `eslint.config.js` and run:
+
+```bash
+npx @eslint/config-inspector
+```
+
+## Versioning Policy
+
+This project follows [Semantic Versioning](https://semver.org/) for releases. However, since this is just a config and involves opinions and many moving parts, we don't treat rules changes as breaking changes.
+
+### Changes Considered as Breaking Changes
+
+- Node.js version requirement changes
+- Huge refactors that might break the config
+- Plugins made major changes that might break the config
+- Changes that might affect most of the codebases
+
+### Changes Considered as Non-breaking Changes
+
+- Enable/disable rules and plugins (that might become stricter)
+- Rules options changes
+- Version bumps of dependencies
+
+## FAQ
+
+### I prefer XXX...
+
+Sure, you can configure and override rules locally in your project to fit your needs. If that still does not work for you, you can always fork this repo and maintain your own.