@paratco/eslint-config 2.3.1 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paratco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,47 +1,212 @@
 # `@paratco/eslint-config`
 
-Paratco ESLint configs
+Paratco ESLint configs for JavaScript and TypeScript projects.
 
-- Typescript
+- TypeScript
 - React (optional)
+- Node.js
+- Import plugin (optional)
+- Stylistic or Prettier formatting
+
+## Installation
 
-### Installation
 
 NPM:
 ```bash
-npm install --save-dev @paratco/eslint-config eslint prettier typescript-eslint
+# prettier is optional, just use it if you want to use prettier formatting
+npm install --save-dev @paratco/eslint-config eslint prettier
 ```
 
 Yarn:
 ```bash
-yarn add -D @paratco/eslint-config eslint prettier typescript-eslint
+# prettier is optional, just use it if you want to use prettier formatting
+yarn add -D @paratco/eslint-config eslint prettier
 ```
 
-### Usage (Flat config):
+## Usage (ESLint Flat Config)
+
+Create an `eslint.config.{js,mjs,ts}` file in your project root:
 
-Node.JS:
 ```javascript
-import paratcoEslintConfig from "@paratco/eslint-config";
+import { createConfig } from "@paratco/eslint-config";
+
+export default createConfig({
+  // Required: Specify the platform
+  platform: "node", // or "react"
+
+  // Required: Choose your formatting style
+  style: "prettier", // or "stylistic"
+
+  // Optional: Enable import plugin rules
+  useImport: true,
+
+  // Optional: TypeScript configuration
+  typescript: {
+    tsconfigRootDir: import.meta.dirname,
+    project: "./tsconfig.json"
+  },
+
+  // Optional: Add custom overrides
+  overrides: [
+    // Your custom ESLint configurations
+  ],
 
-export default [
-  ...paratcoEslintConfig.node,
-];
+  // Optional: Specify patterns to ignore
+  ignores: ["dist/**", "node_modules/**"]
+});
 ```
 
-React:
+## Configuration Options
+
+The `createConfig` function accepts an options object with the following properties:
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `platform` | `"node" \| "react"` | Yes | - | Specifies the platform for the ESLint configuration |
+| `style` | `"stylistic" \| "prettier"` | Yes | - | Specifies the style formatter to use |
+| `useImport` | `boolean` | No | `false` | Enable import plugin rules |
+| `typescript` | `TypescriptOptions` | No | `undefined` | TypeScript configuration options |
+| `overrides` | `Linter.Config[]` | No | `undefined` | Additional ESLint configurations to override defaults |
+| `ignores` | `string[]` | No | `undefined` | Patterns to ignore |
+
+### TypeScript Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `tsconfigRootDir` | `string` | No | `undefined` | The root directory for TypeScript configuration |
+| `project` | `string \| string[]` | No | `undefined` | Path to tsconfig.json file(s) |
+
+## Examples
+
+### Node.js Configuration
+
 ```javascript
-import paratcoEslintConfig from "@paratco/eslint-config";
+import { createConfig } from "@paratco/eslint-config";
+
+export default createConfig({
+  platform: "node",
+  style: "prettier",
+  typescript: {
+    tsconfigRootDir: import.meta.dirname,
+    project: "./tsconfig.json"
+  }
+});
+```
+
+### React Configuration
+
+```javascript
+import { createConfig } from "@paratco/eslint-config";
+
+export default createConfig({
+  platform: "react",
+  style: "stylistic",
+  useImport: true,
+  typescript: {
+    tsconfigRootDir: import.meta.dirname,
+    project: "./tsconfig.json"
+  }
+});
+```
+
+### JavaScript-only Configuration
+
+```javascript
+import { createConfig } from "@paratco/eslint-config";
+
+export default createConfig({
+  platform: "node",
+  style: "prettier"
+});
+```
+
+## Using oxlint alongside ESLint
+
+[oxlint](https://oxc-project.github.io/) is a fast JavaScript/TypeScript linter written in Rust that can be used alongside ESLint to improve performance and catch additional issues. This package supports using both linters together.
+
+### Installation
 
-export default [
-  ...paratcoEslintConfig.react,
-];
+Install oxlint alongside ESLint:
+
+NPM:
+```bash
+npm install --save-dev --save-exact oxlint@1.7.0 eslint-plugin-oxlint@1.7.0
+```
+
+Yarn:
+```bash
+yarn add -D -E oxlint@1.7.0 eslint-plugin-oxlint@1.7.0
+```
+
+note: Ensure you have the latest and exact version of oxlint and eslint-plugin-oxlint installed.
+
+### Configuration
+
+1. Create an `.oxlintrc.json` file with @oxlint/migrate:
+
+```bash
+# version match with oxlint installed before
+npx @oxlint/migrate@1.7.0
+```
+This will generate or update your `.oxlintrc.json` file based on your ESLint configuration. The tool analyzes your ESLint config and converts compatible rules to their oxlint equivalents.
+
+2. Update your `package.json` scripts to run both linters (run oxlint first for performance):
+
+```json
+{
+  "scripts": {
+    "lint": "oxlint --max-warnings=0 && eslint --max-warnings=0",
+    "lint:fix": "oxlint --fix && eslint --fix"
+  }
+}
 ```
 
-Base (JS + TS rules):
+3. integrate oxlint with ESLint by adding the ESLint plugin to your configuration:
+
 ```javascript
-import paratcoEslintConfig from "@paratco/eslint-config";
+import { createConfig } from "@paratco/eslint-config";
+import oxlintPlugin from "eslint-plugin-oxlint";
+
+export default createConfig({
+  platform: "node", // or "react"
+  style: "prettier", // or "stylistic"
+
+  // Add oxlint plugin as the LAST item in your overrides
+  // This ensures ESLint rules that are handled by oxlint are turned off
+  overrides: [
+    // Your other overrides go here
+    
+    // eslint-plugin-oxlint must be the last config
+    ...oxlintPlugin.configs["flat/all"]
+  ]
+});
+```
 
-export default [
-  ...paratcoEslintConfig.base,
-];
+### Running Linters
+
+Run both linters with a single command:
+
+```bash
+npm run lint
+# or
+yarn lint
 ```
+
+Fix issues automatically when possible:
+
+```bash
+npm run lint:fix
+# or
+yarn lint:fix
+```
+
+### Benefits of Using Both Linters
+
+- **Performance**: oxlint is significantly faster than ESLint, especially on large codebases
+- **Complementary Rules**: Each linter has unique rules that can catch different issues
+- **Gradual Migration**: You can gradually migrate from ESLint to oxlint or use both permanently
+- **Modern JavaScript Support**: oxlint has excellent support for modern JavaScript and TypeScript features
+
+## License
+
+Licensed under [MIT License](./LICENSE)