npm package: @kolar-ai/eslint-config
Description: Shared ESLint configuration for Kolar projects
Latest version: 1.0.8

# @kolar-ai/eslint-config

Shared ESLint configuration for Kolar projects with TypeScript, NestJS, and Next.js support.

## Installation

```bash
npm install --save-dev @kolar-ai/eslint-config
```

### Peer Dependencies

Make sure you have the required peer dependencies installed:

```bash
npm install --save-dev \
  eslint@^8.0.0 \
  @typescript-eslint/eslint-plugin@^6.0.0 \
  @typescript-eslint/parser@^6.0.0 \
  eslint-plugin-import@^2.29.0
```

For frontend projects, also install:

```bash
npm install --save-dev \
  eslint-plugin-react@^7.33.0 \
  eslint-plugin-react-hooks@^4.6.0 \
  eslint-plugin-jsx-a11y@^6.8.0
```

## Usage

### Basic Setup

```javascript
// eslint.config.js
const { configs } = require("@kolar-ai/eslint-config");

module.exports = [configs.base];
```

### Backend (NestJS) Setup

```javascript
// backend/eslint.config.js
const { configs } = require("@kolar-ai/eslint-config");

module.exports = [
  {
    ...configs.backend,
    files: ["**/*.ts"],
    ignores: ["dist/**", "node_modules/**"],
  },
];
```

### Frontend (Next.js) Setup

```javascript
// frontend/eslint.config.mjs
import kolarConfig from "@kolar-ai/eslint-config";
const { configs } = kolarConfig;

export default [
  {
    ...configs.frontend,
    files: ["**/*.ts", "**/*.tsx"],
    ignores: [".next/**", "out/**", "node_modules/**"],
  },
];
```

### Custom Configuration

You can mix and match rules or use the helper function:

```javascript
const { createConfig, baseRules } = require("@kolar-ai/eslint-config");

// Using the helper function
module.exports = [
  createConfig({
    type: "backend",
    withPrettier: true,
    withTesting: false,
    customRules: {
      "no-console": "off", // Override for development
    },
  }),
];

// Or manual configuration
module.exports = [
  {
    ...configs.backend,
    rules: {
      ...configs.backend.rules,
      // Your custom overrides
      "@typescript-eslint/no-explicit-any": "off",
    },
  },
];
```

### Testing Files

For test files, you might want more relaxed rules:

```javascript
const { configs, testingRules } = require("@kolar-ai/eslint-config");

module.exports = [
  {
    ...configs.backend,
    files: ["**/*.ts"],
    ignores: ["**/*.spec.ts", "**/*.test.ts"],
  },
  {
    ...configs.backend,
    files: ["**/*.spec.ts", "**/*.test.ts"],
    rules: {
      ...configs.backend.rules,
      ...testingRules,
    },
  },
];
```

### With Prettier

If you're using Prettier, make sure to add `eslint-config-prettier`:

```bash
npm install --save-dev eslint-config-prettier
```

Then use it after our config:

```javascript
const { configs } = require("@kolar-ai/eslint-config");
const prettier = require("eslint-config-prettier");

module.exports = [
  configs.backend,
  prettier, // Must come last to override formatting rules
];
```

Or use the built-in Prettier compatibility:

```javascript
const { createConfig } = require("@kolar-ai/eslint-config");

module.exports = [
  createConfig({
    type: "backend",
    withPrettier: true, // This disables conflicting rules
  }),
];
```

## What's Included

### Base Rules

- TypeScript best practices
- Import ordering and organization
- Code quality and consistency
- Async/Promise handling
- Complexity limits

### Backend Config (NestJS)

- All base rules
- Class naming conventions for NestJS
- Decorator positioning
- No default exports (NestJS pattern)
- Dependency injection patterns

### Frontend Config (Next.js/React)

- All base rules
- React best practices
- React Hooks rules
- JSX accessibility (a11y)
- Next.js patterns (default exports for pages)

### Testing Rules

- Relaxed rules for test files
- Allow any types in tests
- No console warnings
- No line limits

## Configuration Options

### createConfig Options

```typescript
{
  type?: 'base' | 'backend' | 'frontend';
  withPrettier?: boolean;    // Disable formatting rules
  withTesting?: boolean;      // Apply relaxed testing rules
  customRules?: object;       // Your rule overrides
  customSettings?: object;    // Your settings overrides
}
```

## Rule Categories

### TypeScript Rules

- Naming conventions (interfaces with 'I' prefix, PascalCase for types)
- Type safety (no-explicit-any as warning)
- Async/await best practices
- Consistent type imports

### Import Rules

- Alphabetical ordering within groups
- Grouped by type (builtin → external → internal → parent → sibling)
- Newlines between import groups
- No duplicate imports
- Cycle detection

### Code Quality

- Complexity limits (max 15)
- Function size limits (max 100 lines)
- Max depth (4 levels)
- Prefer modern syntax (const, template literals, destructuring)
- Consistent equality checks

### Framework Specific

**NestJS:**

- Class suffixes (Controller, Service, Repository, etc.)
- Decorator positioning
- No extraneous classes allowed

**React/Next.js:**

- Hooks rules enforcement
- JSX best practices
- Accessibility requirements
- Component naming (PascalCase)

## Migrating from Old Config

If you're migrating from `.eslintrc.json`:

1. Install this package
2. Create `eslint.config.js` (or `.mjs` for frontend)
3. Remove old `.eslintrc.json`
4. Update scripts in `package.json` if needed

## Troubleshooting

### "Cannot find module" errors

Make sure all peer dependencies are installed.

### Rules not applying

Check that your `files` glob patterns are correct and that the config is exported correctly.

### Conflicts with Prettier

Either use `eslint-config-prettier` or enable `withPrettier: true` in createConfig.

## Version History

- **1.0.0** - Initial release with base, backend, and frontend configs
- **1.0.1** - Added testing rules
- **1.0.2** - Added Prettier compatibility rules

## License

MIT