@luxass/eslint-config 4.0.0-beta.8 → 4.0.0

package/README.md

@@ -1,31 +1,79 @@
 # @luxass/eslint-config
 
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+
 > [!IMPORTANT]
-> The configuration is not currently finished.  
-> I could change at any moment.
+> The configuration is not currently finished, it could change at any moment.
 
 ## ✨ Features
 
-- Designed to work with JavaScript, Typescript, React, Svelte, Astro, Vue out of the box.
-- Support for JSON, YAML, Markdown
-- Sorted imports for `package.json` and `tsconfig.json`
+- Based on [Antfu's ESLint Config](https://github.com/antfu/eslint-config)
+- Auto fix for formatting (aimed to be used standalone **without** Prettier)
+- Designed to work with TypeScript, JSX, Vue & Astro out-of-box
+- Lints also for json, yaml, toml, markdown
+- Sorted imports, dangling commas
+- Reasonable defaults, best practices, only one-line of config
+- Opinionated, but [very customizable](#customization)
 - [ESLint Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), compose easily!
-- Using [ESLint Stylistic](https://eslint.style/guide/why)
+- Using [ESLint Stylistic](https://github.com/eslint-stylistic/eslint-stylistic)
+- Respects `.gitignore` by default
+- Optional [formatters](#formatters) support for CSS, HTML, etc.
 
 ## 📦 Install
 
 ```bash
-pnpm add -D eslint @luxass/eslint-config
+pnpm install -D eslint @luxass/eslint-config
 ```
 
 ## 🚀 Usage
+
+With [`"type": "module"`](https://nodejs.org/api/packages.html#type) in `package.json` (recommended):
+
 ```js
 // eslint.config.js
-import { luxass } from "@luxass/eslint-config";
+import luxass from "@luxass/eslint-config";
 
 export default luxass();
 ```
 
+With CJS:
+
+```js
+// eslint.config.js
+const luxass = require("@luxass/eslint-config").default;
+
+module.exports = luxass();
+```
+
+Combined with legacy config:
+
+```js
+// eslint.config.js
+const luxass = require("@luxass/eslint-config").default;
+const { FlatCompat } = require("@eslint/eslintrc");
+
+const compat = new FlatCompat();
+
+module.exports = luxass(
+  {
+    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.
+
 ## Setup for Visual Studio Code
 
 Install [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and add the following to your `.vscode/settings.json`:
@@ -42,7 +90,7 @@ Install [ESLint extension](https://marketplace.visualstudio.com/items?itemName=d
 
   // auto fix on save
   "editor.codeActionsOnSave": {
-    "source.fixAll": "explicit",
+    "source.fixAll.eslint": "explicit",
     "source.organizeImports": "never"
   },
 
@@ -84,7 +132,7 @@ Normally you would only need to import the `luxass` preset:
 
 ```js
 // eslint.config.js
-import { luxass } from "@luxass/eslint-config";
+import luxass from "@luxass/eslint-config";
 
 export default luxass();
 ```
@@ -93,16 +141,20 @@ you can also configure each `config` individually:
 
 ```js
 // eslint.config.js
-import { luxass } from "@luxass/eslint-config";
+import luxass from "@luxass/eslint-config";
 
 export default luxass({
+  stylistic: true,
   typescript: true,
   vue: true,
   react: false,
   astro: true,
-  svelte: false,
   unocss: true,
-  stylistic: true
+
+  // `.eslintignore` is no longer supported in Flat config, use `ignores` instead.
+  ignores: [
+    "./fixtures"
+  ]
 });
 ```
 
@@ -110,70 +162,321 @@ The `luxass` function accepts an arbitrary number of `flat configs` overrides:
 
 ```js
 // eslint.config.js
-import { luxass } from "@luxass/eslint-config";
+import luxass from "@luxass/eslint-config";
 
-export default luxass({}, {
+export default luxass({
+  // configuration points for my config
+}, {
   rules: {}
 }, {
   rules: {}
 });
 ```
 
-### Fine Grained Configurations
+<details>
+<summary>Advanced Example</summary>
 
-If you want it more advanced, you can also just import the `config` you need.
+We don't recommend using this style in general usages, as there are shared options between configs and might need extra care to make them consistent.
 
 ```js
 // eslint.config.js
 import {
-  astro,
   comments,
   ignores,
   imports,
   javascript,
-  javascriptStylistic,
   jsdoc,
   jsonc,
   markdown,
   node,
-  react,
-  sort,
-  svelte,
-  tailwindcss,
+  sortPackageJson,
+  sortTsconfig,
+  stylistic,
   typescript,
-  typescriptStylistic,
   unicorn,
-  unocss,
   vue,
-  yml
+  yaml,
 } from "@luxass/eslint-config/configs";
 
-export default [
-  ...astro,
-  ...comments,
-  ...ignores,
-  ...imports,
-  ...javascript,
-  ...javascriptStylistic,
-  ...jsdoc,
-  ...jsonc,
-  ...markdown,
-  ...node,
-  ...react,
-  ...sort,
-  ...svelte,
-  ...tailwindcss,
-  ...typescript,
-  ...typescriptStylistic,
-  ...unicorn,
-  ...unocss,
-  ...vue,
-  ...yml
-];
+import { combine } from "@luxass/eslint-config";
+
+export default combine(
+  ignores(),
+  javascript(/* Options */),
+  comments(),
+  node(),
+  jsdoc(),
+  imports(),
+  unicorn(),
+  typescript(/* Options */),
+  stylistic(),
+  vue(),
+  jsonc(),
+  yaml(),
+  markdown(),
+);
 ```
 
+</details>
+
+Check out the [configs](https://github.com/luxass/eslint-config/blob/main/src/configs) and [factory](https://github.com/luxass/eslint-config/blob/main/src/factory.ts) for more details.
+
 > Thanks to [sxzz/eslint-config](https://github.com/sxzz/eslint-config) and [antfu/eslint-config](https://github.com/antfu/eslint-config) for the inspiration and references.
 
+### Plugins Renaming
+
+Since flat config requires us to explicitly provide the plugin names (instead of mandatory convention from npm package name), we renamed some plugins to make overall scope more consistent and easier to write.
+
+| New Prefix | Original Prefix        | Source Plugin                                                                              |
+| ---------- | ---------------------- | ------------------------------------------------------------------------------------------ |
+| `import/*` | `i/*`                  | [eslint-plugin-i](https://github.com/un-es/eslint-plugin-i)                                |
+| `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/*`     | `@typescript-eslint/*` | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint) |
+| `style/*`  | `@stylistic/*`         | [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic)           |
+| `test/*`   | `vitest/*`             | [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest)                    |
+
+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 }
+```
+
+### 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 luxass from "@luxass/eslint-config";
+
+export default luxass(
+  { 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: {
+      "style/semi": ["error", "never"],
+    },
+  }
+);
+```
+
+We also provided a `overrides` options to make it easier:
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  overrides: {
+    vue: {
+      "vue/operator-linebreak": ["error", "before"],
+    },
+    typescript: {
+      "ts/consistent-type-definitions": ["error", "interface"],
+    },
+    yaml: {},
+    // ...
+  }
+});
+```
+
+### Optional Configs
+
+We provide some optional configs for specific use cases, that we don't include their dependencies by default.
+
+#### Formatters
+
+> [!WARNING]
+> Experimental feature, changes might not follow semver.
+
+Use external formatters to format files that ESLint cannot handle yet (`.css`, `.html`, etc). Powered by [`eslint-plugin-format`](https://github.com/antfu/eslint-plugin-format).
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  formatters: {
+    /**
+     * Format CSS, LESS, SCSS files, also the `<style>` blocks in Vue
+     * By default uses Prettier
+     */
+    css: true,
+    /**
+     * Format HTML files
+     * By default uses Prettier
+     */
+    html: true,
+    /**
+     * Format TOML files
+     * Currently only supports dprint
+     */
+    toml: "dprint",
+    /**
+     * Format Markdown files
+     * Supports Prettier and dprint
+     * By default uses Prettier
+     */
+    markdown: "prettier"
+  }
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-format
+```
+
+#### React
+
+To enable React support, need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  react: true,
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-react-refresh
+```
+
+#### Next.JS
+
+To enable Next.JS support, need to explicitly turn it on:
+
+Next.JS also enables React support.
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  nextjs: true,
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-react-refresh @next/eslint-plugin-next
+```
+
+#### UnoCSS
+
+To enable UnoCSS support, need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  unocss: true,
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D @unocss/eslint-plugin
+```
+
+#### TailwindCSS
+
+To enable TailwindCSS support, need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import luxass from "@luxass/eslint-config";
+
+export default luxass({
+  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
+```
+
+### Optional Rules
+
+This config also provides some optional plugins/rules for extended usages.
+
+#### `perfectionist` (sorting)
+
+This plugin [`eslint-plugin-perfectionist`](https://github.com/azat-io/eslint-plugin-perfectionist) allows you to sorted object keys, imports, etc, with auto-fix.
+
+The plugin is installed but no rules are enabled by default.
+
+It's recommended to opt-in on each file individually using [configuration comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1).
+
+```js
+/* eslint perfectionist/sort-objects: "error" */
+const objectWantedToSort = {
+  a: 2,
+  b: 1,
+  c: 3,
+};
+/* eslint perfectionist/sort-objects: "off" */
+```
+
+### 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 luxass from "@luxass/eslint-config";
+
+export default luxass({
+  typescript: {
+    tsconfigPath: "tsconfig.json",
+  },
+});
+```
+
+## 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
+
 ## 📄 License
 
 Published under [MIT License](./LICENSE).
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@luxass/eslint-config?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@luxass/eslint-config
+[npm-downloads-src]: https://img.shields.io/npm/dm/@luxass/eslint-config?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@luxass/eslint-config

package/dist/{chunk-TQ476NL2.mjs → chunk-4YBQZLPS.mjs}

@@ -35,8 +35,8 @@ async function ensure(packages) {
   const { default: prompts } = await import("prompts");
   const { result } = await prompts([
     {
-      message: `${nonExistingPackages.length === 1 ? "Package is" : "Packages are"} required for this config: ${nonExistingPackages.join(", ")}. Do you want to install them?`,
       name: "result",
+      message: `${nonExistingPackages.length === 1 ? "Package is" : "Packages are"} required for this config: ${nonExistingPackages.join(", ")}. Do you want to install them?`,
       type: "confirm"
     }
   ]);
@@ -47,11 +47,22 @@ async function ensure(packages) {
   }
   ;
 }
+function resolveSubOptions(options, key) {
+  return typeof options[key] === "boolean" ? {} : options[key] || {};
+}
+function getOverrides(options, key) {
+  const sub = resolveSubOptions(options, key);
+  return {
+    ..."overrides" in sub ? sub.overrides : {}
+  };
+}
 
 export {
   combine,
   renameRules,
   toArray,
   interop,
-  ensure
+  ensure,
+  resolveSubOptions,
+  getOverrides
 };

package/dist/{chunk-NDNDG7BH.mjs → chunk-5NK24IKQ.mjs}

@@ -1,14 +1,11 @@
-import {
-  default3 as default2
-} from "./chunk-C5VMTRKT.mjs";
-
 // src/configs/node.ts
+import pluginNode from "eslint-plugin-n";
 function node() {
   return [
     {
       name: "luxass:node",
       plugins: {
-        node: default2
+        node: pluginNode
       },
       rules: {
         "node/handle-callback-err": ["error", "^(err|error)$"],

package/dist/{chunk-2SW2E3TH.mjs → chunk-5SDSWPKR.mjs}

@@ -1,9 +1,10 @@
 import {
-  default as default2,
-  pluginImport
-} from "./chunk-C5VMTRKT.mjs";
+  GLOB_SRC_EXT
+} from "./chunk-ATRL3UZP.mjs";
 
 // src/configs/imports.ts
+import pluginImport from "eslint-plugin-i";
+import pluginAntfu from "eslint-plugin-antfu";
 async function imports(options = {}) {
   const {
     stylistic = true
@@ -12,11 +13,12 @@ async function imports(options = {}) {
     {
       name: "luxass:imports",
       plugins: {
-        antfu: default2,
+        antfu: pluginAntfu,
         import: pluginImport
       },
       rules: {
         "antfu/import-dedupe": "error",
+        "antfu/no-import-dist": "error",
         "antfu/no-import-node-modules-by-path": "error",
         "import/first": "error",
         "import/no-duplicates": "error",
@@ -29,6 +31,14 @@ async function imports(options = {}) {
           "import/newline-after-import": ["error", { considerComments: true, count: 1 }]
         } : {}
       }
+    },
+    {
+      name: "luxass:imports:bin",
+      files: ["**/bin/**/*", `**/bin.${GLOB_SRC_EXT}`],
+      rules: {
+        "antfu/no-import-dist": "off",
+        "antfu/no-import-node-modules-by-path": "off"
+      }
     }
   ];
 }

package/dist/chunk-6T7MXPCT.mjs

@@ -0,0 +1,17 @@
+// src/configs/perfectionist.ts
+import pluginPerfectionist from "eslint-plugin-perfectionist";
+async function perfectionist() {
+  return [
+    {
+      name: "luxass:perfectionist",
+      plugins: {
+        perfectionist: pluginPerfectionist
+      },
+      rules: {}
+    }
+  ];
+}
+
+export {
+  perfectionist
+};

package/dist/{chunk-ADP4MYOS.mjs → chunk-ANUYBAYV.mjs}

@@ -1,6 +1,6 @@
 import {
   GLOB_EXCLUDE
-} from "./chunk-R4NSLRAE.mjs";
+} from "./chunk-ATRL3UZP.mjs";
 
 // src/configs/ignores.ts
 function ignores() {

package/dist/{chunk-R4NSLRAE.mjs → chunk-ATRL3UZP.mjs}

@@ -1,20 +1,23 @@
 // src/globs.ts
 var GLOB_SRC_EXT = "?([cm])[jt]s?(x)";
-var GLOB_SRC = "**/*.?([cm])[jt]s?(x)";
+var GLOB_SRC = `**/*.${GLOB_SRC_EXT}`;
 var GLOB_JS = "**/*.?([cm])js";
+var GLOB_JSX = "**/*.?([cm])jsx";
 var GLOB_TS = "**/*.?([cm])ts";
-var GLOB_JSX_EXT = "[jt]sx";
-var GLOB_JSX = `**/*.${GLOB_JSX_EXT}`;
+var GLOB_TSX = "**/*.?([cm])tsx";
 var GLOB_STYLE = "**/*.{c,le,sc}ss";
 var GLOB_CSS = "**/*.css";
+var GLOB_POSTCSS = "**/*.{p,post}css";
 var GLOB_LESS = "**/*.less";
 var GLOB_SCSS = "**/*.scss";
 var GLOB_JSON = "**/*.json";
 var GLOB_JSON5 = "**/*.json5";
 var GLOB_JSONC = "**/*.jsonc";
 var GLOB_MARKDOWN = "**/*.md";
+var GLOB_MARKDOWN_IN_MARKDOWN = "**/*.md/*.md";
 var GLOB_VUE = "**/*.vue";
 var GLOB_YAML = "**/*.y?(a)ml";
+var GLOB_TOML = "**/*.toml";
 var GLOB_HTML = "**/*.htm?(l)";
 var GLOB_ASTRO = "**/*.astro";
 var GLOB_MARKDOWN_CODE = `${GLOB_MARKDOWN}/${GLOB_SRC}`;
@@ -26,9 +29,9 @@ var GLOB_TESTS = [
   `**/*.benchmark.${GLOB_SRC_EXT}`
 ];
 var GLOB_NEXTJS_OG = [
-  `**/app/**/opengraph-image.${GLOB_JSX_EXT}`,
-  `**/app/**/twitter-image.${GLOB_JSX_EXT}`,
-  `**/app/**/route.${GLOB_JSX_EXT}`
+  `**/app/**/opengraph-image.[jt]s?(x)`,
+  `**/app/**/twitter-image.[jt]s?(x)`,
+  `**/app/**/route.[jt]s?(x)`
 ];
 var GLOB_NEXTJS_ROUTES = [
   `**/app/**/page.${GLOB_SRC_EXT}`,
@@ -79,19 +82,22 @@ export {
   GLOB_SRC_EXT,
   GLOB_SRC,
   GLOB_JS,
-  GLOB_TS,
-  GLOB_JSX_EXT,
   GLOB_JSX,
+  GLOB_TS,
+  GLOB_TSX,
   GLOB_STYLE,
   GLOB_CSS,
+  GLOB_POSTCSS,
   GLOB_LESS,
   GLOB_SCSS,
   GLOB_JSON,
   GLOB_JSON5,
   GLOB_JSONC,
   GLOB_MARKDOWN,
+  GLOB_MARKDOWN_IN_MARKDOWN,
   GLOB_VUE,
   GLOB_YAML,
+  GLOB_TOML,
   GLOB_HTML,
   GLOB_ASTRO,
   GLOB_MARKDOWN_CODE,