npm package: @foundrykit/eslint-config
Description: ESLint configuration for the FoundryKit ecosystem. Provides consistent code quality rules and formatting standards across all FoundryKit packages and applications.
Latest version: 1.0.5

# @foundrykit/eslint-config

ESLint configuration for the FoundryKit ecosystem. Provides consistent code
quality rules and formatting standards across all FoundryKit packages and
applications.

## Features

- **Consistent rules** - Standardized ESLint configuration across projects
- **TypeScript support** - Full TypeScript linting with type-aware rules
- **React support** - React-specific linting rules and best practices
- **Next.js support** - Next.js specific rules and configurations
- **Extensible** - Easy to extend and customize for specific needs

## Installation

```bash
pnpm add -D @foundrykit/eslint-config
```

## Available Configurations

### Base Configuration

The base configuration includes common rules for JavaScript/TypeScript projects:

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default foundrykitBase;
```

### Next.js Configuration

Configuration optimized for Next.js applications:

```javascript
// eslint.config.js
import foundrykitNext from '@foundrykit/eslint-config/next';

export default foundrykitNext;
```

### React Configuration

Configuration for React applications:

```javascript
// eslint.config.js
import foundrykitReact from '@foundrykit/eslint-config/react';

export default foundrykitReact;
```

## Usage

### Basic Setup

1. **Install the package:**

```bash
pnpm add -D @foundrykit/eslint-config
```

2. **Create ESLint configuration:**

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default foundrykitBase;
```

3. **Add scripts to package.json:**

```json
{
  "scripts": {
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix"
  }
}
```

### Next.js Project

For Next.js applications:

```javascript
// eslint.config.js
import foundrykitNext from '@foundrykit/eslint-config/next';

export default foundrykitNext;
```

### React Project

For React applications:

```javascript
// eslint.config.js
import foundrykitReact from '@foundrykit/eslint-config/react';

export default foundrykitReact;
```

### Custom Configuration

Extend the base configuration with custom rules:

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default [
  ...foundrykitBase,
  {
    rules: {
      // Custom rules
      'no-console': 'warn',
      'prefer-const': 'error',
    },
  },
];
```

## Configuration Details

### Base Configuration

The base configuration includes:

- **TypeScript rules** - Type-aware linting
- **Import rules** - Import/export validation
- **Code quality** - Common code quality rules
- **Formatting** - Consistent code formatting

### Next.js Configuration

Extends base configuration with:

- **Next.js specific rules** - Next.js best practices
- **React rules** - React-specific linting
- **JSX rules** - JSX syntax validation
- **Hooks rules** - React hooks linting

### React Configuration

Extends base configuration with:

- **React rules** - React best practices
- **JSX rules** - JSX syntax validation
- **Hooks rules** - React hooks linting
- **Accessibility rules** - Accessibility best practices

## Rules Overview

### TypeScript Rules

```javascript
// TypeScript specific rules
{
  '@typescript-eslint/no-unused-vars': 'error',
  '@typescript-eslint/no-explicit-any': 'warn',
  '@typescript-eslint/explicit-function-return-type': 'off',
  '@typescript-eslint/explicit-module-boundary-types': 'off'
}
```

### React Rules

```javascript
// React specific rules
{
  'react/jsx-uses-react': 'off',
  'react/react-in-jsx-scope': 'off',
  'react/prop-types': 'off',
  'react-hooks/rules-of-hooks': 'error',
  'react-hooks/exhaustive-deps': 'warn'
}
```

### Import Rules

```javascript
// Import/export rules
{
  'import/order': [
    'error',
    {
      groups: [
        'builtin',
        'external',
        'internal',
        'parent',
        'sibling',
        'index'
      ],
      'newlines-between': 'always'
    }
  ]
}
```

## Customization

### Override Rules

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default [
  ...foundrykitBase,
  {
    rules: {
      // Override specific rules
      'no-console': 'off',
      '@typescript-eslint/no-unused-vars': 'warn',
    },
  },
];
```

### Add Plugins

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default [
  ...foundrykitBase,
  {
    plugins: {
      'custom-plugin': require('eslint-plugin-custom'),
    },
    rules: {
      'custom-plugin/rule': 'error',
    },
  },
];
```

### Environment-Specific Rules

```javascript
// eslint.config.js
import foundrykitBase from '@foundrykit/eslint-config/base';

export default [
  ...foundrykitBase,
  {
    files: ['**/*.test.ts', '**/*.test.tsx'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
  {
    files: ['**/*.config.js', '**/*.config.ts'],
    rules: {
      'import/no-default-export': 'off',
    },
  },
];
```

## Integration

### VS Code

Add to your VS Code settings:

```json
{
  "eslint.workingDirectories": ["."],
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}
```

### Pre-commit Hooks

Using husky and lint-staged:

```json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix"]
  }
}
```

### CI/CD

Add to your GitHub Actions:

```yaml
- name: Lint
  run: pnpm lint
```

## Troubleshooting

### Common Issues

**TypeScript errors:**

```bash
# Ensure TypeScript is installed
pnpm add -D typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin
```

**Import errors:**

```bash
# Check import resolution
pnpm add -D eslint-plugin-import eslint-import-resolver-typescript
```

**React errors:**

```bash
# Ensure React ESLint plugin is installed
pnpm add -D eslint-plugin-react eslint-plugin-react-hooks
```

### Configuration Validation

```bash
# Validate ESLint configuration
npx eslint --print-config .eslintrc.js
```

## Best Practices

### Rule Selection

```javascript
// ✅ Good - Specific, actionable rules
{
  'no-console': 'warn',
  '@typescript-eslint/no-unused-vars': 'error'
}

// ❌ Avoid - Too strict or unclear rules
{
  'no-console': 'error',
  '@typescript-eslint/no-explicit-any': 'error'
}
```

### File Organization

```javascript
// ✅ Good - Organized configuration
export default [
  // Base configuration
  ...foundrykitBase,

  // TypeScript files
  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {
      // TypeScript specific rules
    },
  },

  // Test files
  {
    files: ['**/*.test.ts', '**/*.test.tsx'],
    rules: {
      // Test specific rules
    },
  },
];
```

## Contributing

When contributing to the ESLint configuration:

1. Follow ESLint best practices
2. Test configurations thoroughly
3. Document rule changes
4. Maintain backward compatibility
5. Update this README

## License

MIT