@santi020k/eslint-config-basic 0.1.0

package/README.md

@@ -0,0 +1,275 @@
+# @santi020k/eslint-config-basic
+
+[![CI](https://github.com/santi020k/eslint-config/actions/workflows/build.yml/badge.svg)](https://github.com/santi020k/eslint-config/actions/workflows/build.yml)
+[![npm version](https://img.shields.io/npm/v/@santi020k/eslint-config-basic.svg)](https://www.npmjs.com/package/@santi020k/eslint-config-basic)
+[![npm downloads](https://img.shields.io/npm/dm/@santi020k/eslint-config-basic.svg)](https://www.npmjs.com/package/@santi020k/eslint-config-basic)
+[![Docs](https://img.shields.io/badge/docs-TypeDoc-blue.svg)](https://santi020k.github.io/eslint-config-basic/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Welcome to **@santi020k/eslint-config-basic**, a comprehensive and opinionated ESLint configuration package for JavaScript, TypeScript, React, and other frameworks. Born from a desire to eliminate bad practices and ensure high-quality code, this configuration automates code quality checks and reduces cognitive load during code reviews by enforcing a consistent coding style across your projects.
+
+## Why Use This Configuration?
+
+- **Consistency:** Enforces a uniform coding style, reducing code discrepancies and easing collaboration.
+- **Quality:** Promotes best practices and helps avoid common pitfalls in JavaScript, TypeScript, Frameworks, Libraries, Tools and more.
+- **Automation:** Catches issues early in the development process, minimizing manual code review effort.
+- **Customization:** While it comes with strong opinions, you can tailor it to suit your project's specific needs.
+
+## Installation
+
+Before installing, make sure you have ESLint (version 9.0.0 or later) installed:
+
+```bash
+npm install eslint --save-dev
+```
+
+Then, install the configuration package. **Important:** I recommend using a fixed version (do not use `^` or `~`), as any new functionality or change may introduce new linter errors that require manual updates.
+
+```bash
+npm install @santi020k/eslint-config-basic --save-dev
+```
+
+## Usage
+
+Create an `eslint.config.js` file (or update your existing one) and extend **@santi020k/eslint-config-basic** based on your project type.
+
+### Basic Usage
+
+For a basic JavaScript/Node.js project:
+
+```js
+import { eslintConfig } from '@santi020k/eslint-config-basic'
+
+export default [
+  ...eslintConfig()
+  // Your custom config
+]
+```
+
+### Advanced Usage
+
+For projects that require specific configurations (e.g., TypeScript, React, Next.js, ...Etc), use the appropriate options:
+
+```js
+import { ConfigOption, eslintConfig } from '@santi020k/eslint-config-basic'
+
+// TypeScript project
+export default [
+  ...eslintConfig({ config: [ConfigOption.Ts] })
+  // Your custom config
+]
+
+// React project
+export default [
+  ...eslintConfig({ config: [ConfigOption.React] })
+  // Your custom config
+]
+
+// TypeScript and React project
+export default [
+  ...eslintConfig({ config: [ConfigOption.React, ConfigOption.Ts] })
+  // Your custom config
+]
+
+// Next.js project
+export default [
+  ...eslintConfig({ config: [ConfigOption.Next] })
+  // Your custom config
+]
+
+// Expo project
+export default [
+  ...eslintConfig({ config: [ConfigOption.Expo] })
+  // Your custom config
+]
+
+// Astro project (supports Astro with React)
+export default [
+  ...eslintConfig({ config: [ConfigOption.Astro] })
+  // Your custom config
+]
+
+// NestJS project
+export default [
+  ...eslintConfig({ config: [ConfigOption.Nest] })
+  // Your custom config
+]
+```
+
+### Optional Usage
+
+There are additional optional parameters to add support for other front-end/back-end technologies. This enables you to extend support as needed:
+
+```js
+import { ConfigOption, eslintConfig, OptionalOption } from '@santi020k/eslint-config-basic'
+
+export default [
+  ...eslintConfig({
+    config: [ConfigOption.Next, ConfigOption.Ts],
+    optionals: [
+      // Spell checker
+      OptionalOption.Cspell,
+      // TailwindCss
+      OptionalOption.Tailwind,
+      // Vitest and testing-library
+      OptionalOption.Vitest,
+      // I18next
+      OptionalOption.I18next,
+      // Mdx
+      OptionalOption.Mdx,
+      // Markdown
+      OptionalOption.Markdown,
+      // Stencil
+      OptionalOption.Stencil
+    ]
+  })
+  // Your custom config
+]
+```
+
+### Settings Usage (Experimental)
+
+This experimental option allows ESLint to honor your `.gitignore` file:
+
+```js
+import { eslintConfig, SettingOption } from '@santi020k/eslint-config-basic'
+
+export default [
+  ...eslintConfig({
+    // ESLint will ignore files specified in .gitignore
+    settings: [SettingOption.Gitignore]
+  })
+  // Your custom config
+]
+```
+
+## Monorepo Structure
+
+This project is a monorepo managed with **Turbo** and **npm Workspaces**.
+
+- `packages/basic`: Main package entry point.
+- `packages/core`: Core logic and shared types.
+- `packages/typescript`: TypeScript specific rules.
+- `packages/react`: React and Hooks rules.
+- `packages/next`: Next.js rules.
+- `packages/astro`: Astro rules.
+- `packages/expo`: Expo/React Native rules.
+- `packages/optionals`: Optional configurations (Tailwind, Vitest, etc.).
+- `packages/tests`: Integration tests.
+- `packages/playground`: Testing playground for local development.
+
+## Development
+
+If you want to contribute or modify the configurations:
+
+### Prerequisites
+- Node.js (version specified in `.nvmrc`)
+- npm
+
+### Setup
+```bash
+npm install
+```
+
+### Useful Commands
+```bash
+npm run build      # Build all packages using Turbo
+npm run lint       # Lint all packages
+npm run test       # Run integration tests
+npm run dev        # Development mode with watch
+npm run inspector  # Open ESLint config inspector
+npm run docs       # Generate API documentation
+```
+
+### ESLint Config Inspector
+
+You can visually inspect the generated ESLint configuration using the built-in inspector:
+
+```bash
+npm run inspector
+```
+
+This opens an interactive UI where you can see all active rules, plugins, and config layers. It's useful for debugging which rules are applied and understanding the final merged configuration.
+
+### API Documentation
+
+### API Documentation
+
+Auto-generated API docs are available online:
+[**https://santi020k.github.io/eslint-config-basic/**](https://santi020k.github.io/eslint-config-basic/)
+
+You can also generate them locally:
+
+```bash
+npm run docs
+```
+
+This outputs markdown documentation to the `docs/` directory.
+
+## Opinionated but Flexible
+
+This ESLint configuration is based on my personal preferences and practices, and it may evolve over time. **Important:** I recommend using a fixed version to avoid unexpected changes that might introduce new linter errors. To ensure stability, do not use `^` or `~` when specifying the version. If a rule feels too strict, consider changing it from an error to a warning to allow more flexibility during development.
+
+## Scripts
+
+Add the following useful scripts to your `package.json`:
+
+```json
+"scripts": {
+  "lint": "eslint . --report-unused-disable-directives",
+  "lint:fix": "npm run lint -- --fix"
+}
+```
+
+## How to Implement in an Existing Project
+
+1.  **Install the Dependencies:** Ensure that both ESLint and this configuration package are installed.
+2.  **Update Your ESLint Configuration:** Extend **@santi020k/eslint-config-basic** in your ESLint configuration file as shown above.
+3.  **Run ESLint:** Lint your project files and automatically fix issues if possible:
+
+    ```bash
+    npm run lint
+    npm run lint:fix
+    ```
+
+4.  **Adjust as Necessary:** Review and modify the linting rules based on your project's needs. Some rules might be too strict or not applicable; feel free to disable or adjust them.
+
+## Future Features
+
+- [x] Testing
+- [x] Refactored rules structure (Monorepo transition)
+- [x] Astro and Expo support
+- [x] Enhanced documentation
+- [ ] Additional framework support (contributions welcome!):
+  - [ ] Vue
+  - [ ] Angular
+  - [x] NestJS
+
+## Contributing
+
+Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details on setting up the project, adding new configurations, and submitting pull requests.
+
+## Acknowledgements
+
+Special thanks to the developers and maintainers of the following libraries, which form the backbone of this ESLint configuration:
+
+- eslint-config-standard
+- eslint-plugin-import
+- eslint-plugin-jsx-a11y
+- eslint-plugin-n
+- eslint-plugin-promise
+- eslint-plugin-react
+- eslint-plugin-react-hooks
+- eslint-plugin-simple-import-sort
+- eslint-plugin-sonarjs
+- eslint-plugin-unused-imports
+- @stylistic/eslint-plugin
+- @typescript-eslint
+- @cspell/eslint-plugin
+- eslint-plugin-tailwindcss
+- eslint-plugin-vitest
+- ...and many others
+
+Their ongoing contributions help maintain the high standards of code quality we all strive for.
+
+Thank you for using **@santi020k/eslint-config-basic**. Together, let's write cleaner, more maintainable code!

package/config/.husky/commit-msg

@@ -0,0 +1,9 @@
+#!/bin/sh
+if ! head -1 "$1" | grep -qE "^(feat|fix|chore|docs|test|style|refactor|perf|build|ci|revert)(\(.+?\))?: .{1,}$"; then
+    echo "Aborting commit. Your commit message is invalid." >&2
+    exit 1
+fi
+if ! head -1 "$1" | grep -qE "^.{1,200}$"; then
+    echo "Aborting commit. Your commit message is too long." >&2
+    exit 1
+fi

package/config/.husky/pre-commit

@@ -0,0 +1 @@
+npm run pre-commit

package/config/.husky/pre-push

@@ -0,0 +1 @@
+npm run pre-push

package/config/.husky/prepare-commit-msg

@@ -0,0 +1 @@
+exec < /dev/tty && npx cz --hook || true

package/cspell.config.yaml

@@ -0,0 +1,2 @@
+words:
+  - santi

package/eslint.config.js

@@ -0,0 +1,21 @@
+// @ts-check
+import { ConfigOption, eslintConfig, OptionalOption } from '@santi020k/eslint-config-basic'
+
+export default [
+  ...eslintConfig({
+    config: [ConfigOption.Ts],
+    optionals: [OptionalOption.Mdx, OptionalOption.Markdown, OptionalOption.Vitest]
+  }),
+  {
+    name: 'local-config',
+    ignores: [
+      'dist/*',
+      'packages/*/dist/*',
+      '**/tsup.config.ts',
+      'docs/*',
+      'docs-md/*',
+      'typedoc.config.mjs',
+      'typedoc.markdown.mjs'
+    ]
+  }
+]

package/llms.txt

@@ -0,0 +1,72 @@
+# @santi020k/eslint-config-basic
+
+> A comprehensive ESLint configuration package for JavaScript, TypeScript, React, Next.js, Astro, and Expo projects.
+
+## AI Assistant Context
+**Role**: You are a senior software engineer maintaining this high-quality ESLint config package.
+**Goal**: Ensure code quality, type safety, and seamless developer experience (DX).
+**Style**: Strict but practical. Prefer correctness over brevity.
+
+## Quick Start
+
+```js
+import { ConfigOption, eslintConfig, OptionalOption } from '@santi020k/eslint-config-basic'
+
+export default [
+  ...eslintConfig({
+    config: [ConfigOption.React, ConfigOption.Ts],
+    optionals: [OptionalOption.Tailwind, OptionalOption.Vitest]
+  })
+]
+```
+
+## Architecture
+
+This is a monorepo-style ESLint config package using ESLint 9 Flat Config format.
+
+### Directory Structure
+
+packages/
+├── basic/            # Main entry point (@santi020k/eslint-config-basic)
+│   ├── src/index.ts  # Exports eslintConfig()
+│   └── dist/         # Build artifacts
+├── core/             # Core logic and shared types
+├── typescript/       # TypeScript config
+├── react/            # React config
+├── next/             # Next.js config
+├── astro/            # Astro config
+├── expo/             # Expo config
+├── optionals/        # Optional feature configs
+├── playground/       # Internal testing playground
+└── tests/            # Integration tests
+
+### Key Enums
+
+- **ConfigOption**: `Ts`, `React`, `Next`, `Expo`, `Astro`
+- **OptionalOption**: `Cspell`, `Tailwind`, `Vitest`, `I18next`, `Mdx`, `Markdown`, `Stencil`
+- **SettingOption**: `Gitignore`
+
+## Commands
+
+```bash
+npm run build       # Build with tsup
+npm run lint        # Run ESLint
+npm run lint:fix    # Fix linting issues
+npm run dev         # Watch mode development
+npm run inspector   # Open ESLint config inspector
+```
+
+## Adding New Configurations
+
+1. Create a new package under `packages/` (e.g. `packages/vue`).
+2. Implement the config in `src/index.ts` of that package.
+3. Export it from the package's entry point.
+4. Add to `ConfigOption` enum in `packages/core/src/types.ts`.
+5. Wire up in `packages/basic/src/index.ts`.
+
+## Tech Stack
+
+- **Build**: tsup, TypeScript
+- **ESLint**: v9+ Flat Config format
+- **Package Manager**: npm/pnpm
+- **Node**: ^18.18.0 || ^20.9.0 || >=21.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@santi020k/eslint-config-basic",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://santi020k.github.io/eslint-config-basic/",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "npm@10.8.3",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "turbo run dev",
+    "build": "turbo run build",
+    "lint": "turbo run lint",
+    "lint:fix": "turbo run lint:fix",
+    "test": "vitest run packages/tests",
+    "clean": "turbo run clean && rm -rf node_modules",
+    "prepare": "husky config/.husky",
+    "pre-commit": "lint-staged",
+    "pre-push": "npm run test && npm run lint && npm run build",
+    "docs": "typedoc",
+    "docs:md": "typedoc --options typedoc.markdown.mjs",
+    "docs:clean": "rm -rf docs docs-md"
+  },
+  "devDependencies": {
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^9.39.2",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-n": "^17.23.2",
+    "eslint-plugin-promise": "^7.2.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "turbo": "^2.5.3",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.10.0",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,md}": [
+      "eslint --fix"
+    ]
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "overrides": {
+    "eslint": "$eslint",
+    "eslint-config-standard": "$eslint-config-standard",
+    "eslint-plugin-promise": "$eslint-plugin-promise",
+    "eslint-plugin-n": "$eslint-plugin-n",
+    "lodash": "^4.17.23",
+    "minimist": "^1.2.6",
+    "tmp": "^0.2.3"
+  }
+}

package/packages/astro/README.md

@@ -0,0 +1,13 @@
+# @santi020k/eslint-config-astro
+
+Astro specific ESLint rules and configurations.
+
+## Description
+
+This package provides:
+- `eslint-plugin-astro` recommended rules.
+- Configuration for linting `.astro` files.
+
+## Usage
+
+This package is used automatically when `ConfigOption.Astro` is selected in the main configuration.

package/packages/astro/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@santi020k/eslint-config-astro",
+  "version": "0.0.0",
+  "description": "Astro ESLint configuration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "dependencies": {
+    "@santi020k/eslint-config-core": "*",
+    "eslint-plugin-astro": "^1.3.1"
+  },
+  "devDependencies": {
+    "@typescript-eslint/utils": "^8.54.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "santi020k",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/santi020k/eslint-config.git",
+    "directory": "packages/astro"
+  }
+}

package/packages/astro/src/ambient.d.ts

@@ -0,0 +1,10 @@
+declare module 'eslint-plugin-astro' {
+  import type { TSESLint } from '@typescript-eslint/utils'
+  const plugin: {
+    configs: {
+      recommended: TSESLint.FlatConfig.ConfigArray
+      'flat/recommended': TSESLint.FlatConfig.ConfigArray
+    }
+  }
+  export default plugin
+}

package/packages/astro/src/index.ts

@@ -0,0 +1,18 @@
+import pluginAstro from 'eslint-plugin-astro'
+
+import type { TSESLint } from '@typescript-eslint/utils'
+
+import { rules } from './rules.js'
+
+/**
+ * Astro ESLint configuration
+ * Includes Astro plugin recommended rules and custom overrides
+ */
+export const astroConfig: TSESLint.FlatConfig.ConfigArray = [
+  ...(pluginAstro.configs.recommended as TSESLint.FlatConfig.ConfigArray),
+  {
+    name: 'eslint-config-astro/custom',
+    files: ['**/*.astro'],
+    rules
+  }
+]

package/packages/astro/src/rules.ts

@@ -0,0 +1,29 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+import { groups } from '@santi020k/eslint-config-core'
+
+export const rules: TSESLint.Linter.RulesRecord = {
+  'simple-import-sort/imports': [
+    'warn',
+    {
+      groups: [
+        // Packages `react` related packages come first.
+        ['^react'],
+        ['^(astro)(/.*|$)?'],
+        ...groups
+      ]
+    }
+  ],
+  // Disable no-unresolved rule for .astro files
+  'react/jsx-filename-extension': [1, { extensions: ['.astro'] }], // Accept jsx in astro files
+  'react/destructuring-assignment': 'off', // Vscode doesn't support automatically destructuring
+  'react/require-default-props': 'off', // Allow non-defined react props as undefined
+  'react/jsx-props-no-spreading': 'off', // _app.tsx uses spread operator
+  'react/react-in-jsx-scope': 'off',
+  'react/no-unknown-property': 'off',
+  // Disable conflicted rules
+  '@stylistic/jsx-indent': 'off',
+  '@stylistic/jsx-one-expression-per-line': 'off',
+  '@stylistic/jsx-tag-spacing': 'off',
+  'react/jsx-key': 'off'
+}

package/packages/astro/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/astro/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022'
+})

package/packages/basic/README.md

@@ -0,0 +1,33 @@
+# @santi020k/eslint-config-basic
+
+A comprehensive, composable ESLint configuration for modern JavaScript and TypeScript projects.
+
+## Features
+
+- **Composable**: Pick and choose what you need (React, Next.js, Astro, Expo, etc.).
+- **Flat Config**: Built natively for ESLint 9+ Flat Config system.
+- **Opinionated yet Flexible**: Sane defaults with easy override capabilities.
+
+## Installation
+
+```bash
+npm install -D @santi020k/eslint-config-basic eslint
+```
+
+## Usage
+
+Create `eslint.config.mjs` (or `.js`):
+
+```js
+import { ConfigOption, eslintConfig, OptionalOption } from '@santi020k/eslint-config-basic'
+
+export default eslintConfig({
+  config: [
+    ConfigOption.Ts,
+    ConfigOption.React
+  ],
+  optionals: [
+    OptionalOption.Tailwind
+  ]
+})
+```