zeno-config 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# zeno-config
+
+Preconfigured ESLint, Prettier, and TypeScript setup for modern JavaScript and React projects.
+
+## Features
+
+- 🚀 **ESLint 9+ flat config** - Modern configuration format
+- ⚛️ **React support** - Comprehensive React, React Hooks, and JSX accessibility rules
+- 📘 **TypeScript ready** - Full TypeScript support with type-aware linting
+- 💅 **Prettier integration** - Seamless formatting with ESLint
+- 🎯 **Node.js optimized** - Specific rules for Node.js projects
+- 🔌 **Modular configs** - Use only what you need
+
+## Requirements
+
+- Node.js >= 20
+- ESLint >= 9
+
+## Installation
+
+Install the package and its peer dependencies:
+
+```bash
+# Using pnpm (recommended)
+
+# Base dependencies
+pnpm add -D zeno-config eslint prettier @eslint/js @stylistic/eslint-plugin eslint-config-prettier eslint-plugin-import-x eslint-plugin-n eslint-plugin-prettier eslint-plugin-unicorn
+
+# For React projects, also install:
+pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-react-you-might-not-need-an-effect
+
+# For TypeScript projects, also install:
+pnpm add -D typescript typescript-eslint
+```
+
+## Usage
+
+### ESLint Configuration
+
+Create an `eslint.config.js` file in your project root:
+
+#### Basic Configuration
+
+```javascript
+import { defineZenoConfig } from 'zeno-config/eslint';
+
+export default defineZenoConfig({
+	ts: true, // Enable TypeScript support (default: false)
+	react: true, // Enable React support (default: false)
+});
+```
+
+#### Required: Empty `.eslintrc` File
+
+You must create an empty `.eslintrc` file in your project root for the `import-x/no-unused-modules` rule to work correctly with flat config:
+
+```bash
+touch .eslintrc
+```
+
+This is a workaround for a [known limitation](https://github.com/import-js/eslint-plugin-import/issues/3079) where certain internal ESLint APIs are excluded when using flat config. The file can be empty or contain only `ignorePatterns` if you need to ignore specific files.
+
+#### `engines` field in `package.json`
+
+Add an `engines` field to your `package.json` with your supported Node.js versions. Some rules for Node.js use this:
+
+ ```json
+ {
+ 	"engines": {
+ 		"node": ">=20"
+ 	}
+ }
+ ```
+
+#### Advanced Configuration
+
+```javascript
+import { defineZenoConfig } from 'zeno-config/eslint';
+
+export default defineZenoConfig(
+	{
+		react: true,
+		ts: true,
+
+		// If using .js extensions for React files, specify React directories
+		reactDirs: ['src/client', 'src/components'],
+
+		// Ignore Node.js rules in specific directories (defaults to reactDirs)
+		nodeIgnoreDirs: ['src/client'],
+
+		// Patterns to ignore for import/no-unresolved rule
+		ignoreExports: ['^@/'],
+
+		// Extensions to ignore for import/extensions rule
+		extensionsIgnorePattern: {
+			svg: 'always',
+		},
+
+		// Webpack config path for import resolution
+		webpackConfig: './webpack.config.js',
+	},
+	[
+		// Your custom config objects
+		{
+			rules: {
+				'no-console': 'warn',
+			},
+		},
+	]
+);
+```
+
+### Prettier Configuration
+
+Create a `prettier.config.js` file in your project root:
+
+```javascript
+import zenoConfig from 'zeno-config/prettier';
+
+export default zenoConfig;
+```
+
+Or extend it with your own options:
+
+```javascript
+import zenoConfig from 'zeno-config/prettier';
+
+export default {
+	...zenoConfig,
+	printWidth: 100, // Override specific options
+};
+```
+
+### TypeScript Configuration
+
+For Node.js projects, extend the provided TypeScript config in your `tsconfig.json`:
+
+```json
+{
+	"extends": "zeno-config/tsconfig"
+	// your tsconfig options
+}
+```
+
+For React projects:
+
+```json
+{
+	"extends": "zeno-config/tsconfig-react"
+	// your tsconfig options
+}
+```
+
+Example:
+
+```json
+{
+	"extends": "zeno-config/tsconfig-react",
+	"compilerOptions": {
+		"baseUrl": ".", // should match webpack alias settings
+		"paths": {
+			// should match webpack alias settings
+			"@/*": ["src/*"]
+		},
+
+		"allowJs": true,
+		"checkJs": false
+	},
+	"include": ["src/**/*"]
+}
+```
+
+### File Extensions Helpers
+
+Use in your build configs, webpack, etc:
+
+```javascript
+import {
+	allExtensions,
+	nodeExtensions,
+	reactExtensions,
+	typescriptExtensions,
+} from 'zeno-config/extensions';
+```
+
+Covers all of the module and commonjs extensions:
+
+- **JavaScript**: `.js`, `.mjs`, `.cjs`
+- **JSX**: `.jsx`, `.mjsx`, `.cjsx`
+- **TypeScript**: `.ts`, `.cts`, `.mts`
+- **TSX**: `.tsx`, `.mtsx`, `.ctsx`
+
+### `defineZenoConfig(options, additionalESLintConfig)`
+
+| Option                    | Type       | Default     | Description                                                                         |
+| ------------------------- | ---------- | ----------- | ----------------------------------------------------------------------------------- |
+| `react`                   | `boolean`  | `false`     | Enable React-specific rules                                                         |
+| `ts`                      | `boolean`  | `false`     | Enable TypeScript-specific rules                                                    |
+| `reactDirs`               | `string[]` | `[]`        | Directories containing React files (for projects using .js for both React and Node) |
+| `nodeIgnoreDirs`          | `string[]` | `[]`        | Directories to ignore for Node-specific rules (defaults to `reactDirs` if not set)  |
+| `ignoreExports`           | `string[]` | `[]`        | Export patterns to ignore for import/no-unresolved rule                             |
+| `extensionsIgnorePattern` | `object`   | `{}`        | Extension patterns to ignore for import/extensions rule                             |
+| `webpackConfig`           | `string`   | `undefined` | Path to webpack config for import resolver                                          |
+
+## Advanced Usage
+
+### Using Internal Configs Directly
+
+For advanced use cases, you can import and use the internal configs:
+
+```javascript
+import zenoInternals from 'zeno-config/eslint';
+
+const { configs, rules, extensions } = zenoInternals;
+
+export default [
+	...configs.getBase(),
+	...configs.getNode(),
+	...configs.getReact(),
+	...configs.getTypescript(),
+	// Your custom configs
+];
+```
+
+### Accessing Individual Rules
+
+```javascript
+import zenoInternals from 'zeno-config/eslint';
+
+const { rules } = zenoInternals;
+
+// Use individual rule sets
+const baseRules = rules.getBaseRules();
+const reactRules = rules.getReactPluginRules({ extensions: ['.jsx', '.tsx'] });
+```
+
+## Defaults
+
+### Ignored Directories
+
+The following directories are automatically ignored:
+
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+
+#### Prettier Settings
+
+See [src/prettier.js](src/prettier.js) for the default Prettier configuration.
+
+### TypeScript Settings
+
+See the TypeScript configuration files:
+
+- [src/tsconfig.base.json](src/tsconfig.base.json) - Base configuration for Node.js projects
+- [src/tsconfig.react.json](src/tsconfig.react.json) - Configuration for React projects (extends base)
+
+### Included Plugins
+
+- `@eslint/js` - Core JavaScript rules ([rules](src/eslint/rules/baseRules.js))
+- `@stylistic/eslint-plugin` - Code style rules ([rules](src/eslint/rules/stylisticPluginRules.js))
+- `eslint-plugin-import-x` - Import/export validation ([rules](src/eslint/rules/importPluginRules.js))
+- `eslint-plugin-unicorn` - Additional JavaScript best practices ([rules](src/eslint/rules/unicornPluginRules.js))
+- `eslint-plugin-n` - Node.js specific rules ([rules](src/eslint/rules/nodePluginRules.js))
+- `eslint-plugin-prettier` - Prettier integration
+- `eslint-plugin-react` (optional) - React specific rules ([rules](src/eslint/rules/reactPluginRules.js))
+- `eslint-plugin-react-hooks` (optional) - React Hooks rules ([rules](src/eslint/rules/reactHooksPluginRules.js))
+- `eslint-plugin-jsx-a11y` (optional) - Accessibility rules for JSX ([rules](src/eslint/rules/jsxA11yPluginRules.js))
+- `eslint-plugin-react-you-might-not-need-an-effect` (optional) - React Effect optimization ([rules](src/eslint/rules/reactYouMightNotNeedAnEffectPluginRules.js))
+- `typescript-eslint` (optional) - TypeScript rules ([rules](src/eslint/rules/typescriptPluginRules.js))

package/package.json

@@ -0,0 +1,89 @@
+{
+	"name": "zeno-config",
+	"version": "0.1.0",
+	"description": "Opinionated and preconfigured ESLint and Prettier setup",
+	"type": "module",
+	"packageManager": "pnpm@10.25.0",
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"inspect": "pnpm dlx eslint --inspect-config"
+	},
+	"exports": {
+		"./eslint": {
+			"types": "./src/eslint/index.d.ts",
+			"default": "./src/eslint/index.js"
+		},
+		"./prettier": {
+			"types": "./src/prettier.d.ts",
+			"default": "./src/prettier.js"
+		},
+		"./tsconfig": "./src/tsconfig.base.json",
+		"./tsconfig-react": "./src/tsconfig.react.json",
+		"./extensions": {
+			"types": "./src/extensions.d.ts",
+			"default": "./src/extensions.js"
+		}
+	},
+	"files": [
+		"src/**"
+	],
+	"peerDependencies": {
+		"@eslint/js": "^9.39.2",
+		"@stylistic/eslint-plugin": "^5.6.1",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-import-x": "^4.16.1",
+		"eslint-plugin-jsx-a11y": "^6.10.2",
+		"eslint-plugin-n": "^17.23.1",
+		"eslint-plugin-prettier": "^5.5.4",
+		"eslint-plugin-react": "^7.37.5",
+		"eslint-plugin-react-hooks": "^7.0.1",
+		"eslint-plugin-react-you-might-not-need-an-effect": "^0.7.0",
+		"eslint-plugin-unicorn": "^62.0.0",
+		"prettier": "^3.7.4",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.50.1"
+	},
+	"peerDependenciesMeta": {
+		"eslint-plugin-jsx-a11y": {
+			"optional": true
+		},
+		"eslint-plugin-react": {
+			"optional": true
+		},
+		"eslint-plugin-react-hooks": {
+			"optional": true
+		},
+		"eslint-plugin-react-you-might-not-need-an-effect": {
+			"optional": true
+		},
+		"typescript": {
+			"optional": true
+		},
+		"typescript-eslint": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@eslint/js": "9.39.2",
+		"@stylistic/eslint-plugin": "5.6.1",
+		"eslint": "9.39.2",
+		"eslint-config-prettier": "10.1.8",
+		"eslint-plugin-import-x": "4.16.1",
+		"eslint-plugin-jsx-a11y": "6.10.2",
+		"eslint-plugin-n": "17.23.1",
+		"eslint-plugin-prettier": "5.5.4",
+		"eslint-plugin-react": "7.37.5",
+		"eslint-plugin-react-hooks": "7.0.1",
+		"eslint-plugin-react-you-might-not-need-an-effect": "0.7.0",
+		"eslint-plugin-unicorn": "62.0.0",
+		"prettier": "3.7.4",
+		"typescript": "5.9.3",
+		"typescript-eslint": "8.50.1"
+	},
+	"dependencies": {
+		"globals": "16.5.0"
+	}
+}

package/src/eslint/index.d.ts

@@ -0,0 +1,124 @@
+import { type Linter } from 'eslint';
+
+interface BaseConfigOptions {
+	/** Export patterns to ignore for import rules */
+	ignoreExports?: string[];
+	/** Extension patterns to ignore for import rules */
+	extensionsIgnorePattern?: Record<string, string>;
+	/** Path to webpack config for import resolver */
+	webpackConfig?: string;
+}
+
+interface NodeConfigOptions {
+	/** Additional directories to ignore for Node-specific rules */
+	ignoreDirs?: string[];
+}
+
+interface ReactConfigOptions {
+	/** Directories containing React files (for projects using .js for both React and Node) */
+	reactDirs?: string[];
+	/** Extension patterns to ignore for import rules */
+	extensionsIgnorePattern?: Record<string, string>;
+}
+
+interface DefineZenoConfigOptions {
+	/** Enable React-specific rules */
+	react?: boolean;
+	/** Enable TypeScript-specific rules */
+	ts?: boolean;
+	/** Directories containing React files (for projects using .js for both React and Node) */
+	reactDirs?: string[];
+	/** Directories to ignore for Node-specific rules */
+	nodeIgnoreDirs?: string[];
+	/** Export patterns to ignore for import rules */
+	ignoreExports?: string[];
+	/** Extension patterns to ignore for import rules */
+	extensionsIgnorePattern?: Record<string, string>;
+	/** Path to webpack config for import resolver */
+	webpackConfig?: string;
+}
+
+interface Extensions {
+	allExtensions: string[];
+	allExtensionsString: string;
+	nodeExtensions: string[];
+	nodeExtensionsString: string;
+	reactJsExtensions: string[];
+	reactJsExtensionsString: string;
+	reactJsExtensionsExtended: string[];
+	reactJsExtensionsExtendedString: string;
+	reactExtensions: string[];
+	reactExtensionsString: string;
+	reactExtensionsExtended: string[];
+	reactExtensionsExtendedString: string;
+	typescriptExtensions: string[];
+	typescriptExtensionsString: string;
+}
+
+interface Configs {
+	getBase: (options?: BaseConfigOptions) => Linter.Config[];
+	getReact: (options?: ReactConfigOptions) => Linter.Config[];
+	getNode: (options?: NodeConfigOptions) => Linter.Config[];
+	getTypescript: () => Linter.Config[];
+}
+
+interface Rules {
+	getBaseRules: () => Linter.RulesRecord;
+	getImportPluginRules: (options?: {
+		ignoreExports?: string[];
+		extensionsIgnorePattern?: Record<string, string>;
+	}) => Linter.RulesRecord;
+	getStylisticPluginRules: () => Linter.RulesRecord;
+	getUnicornPluginRules: () => Linter.RulesRecord;
+	getReactPluginRules: (options?: {
+		extensions?: string[];
+	}) => Linter.RulesRecord;
+	getReactHooksPluginRules: () => Linter.RulesRecord;
+	getReactYouMightNotNeedAnEffectPluginRules: () => Linter.RulesRecord;
+	getJsxA11yPluginRules: () => Linter.RulesRecord;
+}
+
+interface Internals {
+	configs: Configs;
+	extensions: Extensions;
+	rules: Rules;
+}
+
+declare const internals: Internals;
+
+/**
+ * Defines a Zeno ESLint configuration.
+ *
+ * @param arg1 - Options object or additional config array. If an array, treated as additional config.
+ * @param arg2 - Additional ESLint config objects to merge (only used if arg1 is options object).
+ * @returns ESLint flat config array.
+ *
+ * @example
+ * // With options object
+ * defineZenoConfig({ react: true, ts: true })
+ *
+ * @example
+ * // With additional config
+ * defineZenoConfig({ react: true }, [customConfig])
+ *
+ * @example
+ * // With config array only
+ * defineZenoConfig([customConfig])
+ */
+declare function defineZenoConfig(
+	arg1?: DefineZenoConfigOptions | Linter.Config[],
+	arg2?: Linter.Config[]
+): Linter.Config[];
+
+export {
+	type BaseConfigOptions,
+	type Configs,
+	type DefineZenoConfigOptions,
+	type Extensions,
+	type Internals,
+	type NodeConfigOptions,
+	type ReactConfigOptions,
+	type Rules,
+	defineZenoConfig,
+};
+export default internals;