npm package: @jgoldiee/standardization-configs
Description: Shared ESLint, Prettier, and TypeScript configurations
Latest version: 1.0.0

# @composecure/config

Shared ESLint, Prettier, and TypeScript configurations for CompoSecure platform applications.

## Overview

Centralized ESLint, Prettier, and TypeScript configurations for all platform projects. Install once, extend the configs, and get automatic code formatting, import sorting, Tailwind class ordering, and strict type checking. Updates to linting rules or formatting standards are applied across all projects by simply updating this package.

**What this enables:**

- Auto-fix on save (formatting, import sorting, Tailwind classes)
- Real-time linting errors in your editor
- Consistent code style across the entire platform
- Strict TypeScript with modern React patterns
- Accessibility and Tailwind best practices enforced automatically

## Installation

```bash
npm install -D @composecure/config prettier-plugin-tailwindcss
```

**Note:** `prettier-plugin-tailwindcss` is required as a peer dependency due to how Prettier resolves plugins.

## Usage

```javascript
// eslint.config.js
import config from '@composecure/config/eslint';
export default config;
```

```javascript
// .prettierrc.js
export { default } from '@composecure/config/prettier';
```

```json
// tsconfig.json
{
  "extends": "@composecure/config/typescript",
  "compilerOptions": {
    "outDir": "./dist",
    "baseUrl": "."
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

---

## Rules & Settings

| Config         | Category       | Rule/Setting                 | Level/Value | Description                            |
| -------------- | -------------- | ---------------------------- | ----------- | -------------------------------------- |
| **ESLint**     | TypeScript     | `no-explicit-any`            | warn        | Discourages `any`, allows when needed  |
|                |                | `no-unused-vars`             | error       | Unused variables (except `_` prefixed) |
|                |                | `consistent-type-imports`    | error       | Enforces `import type` for types       |
|                | React          | `jsx-key`                    | error       | Requires keys on list items            |
|                |                | `jsx-no-target-blank`        | error       | Prevents unsecured `target="_blank"`   |
|                |                | `prop-types`                 | off         | Disabled (TypeScript handles this)     |
|                | React Hooks    | `rules-of-hooks`             | error       | Hooks only at top level                |
|                |                | `exhaustive-deps`            | error       | Catches missing hook dependencies      |
|                | Accessibility  | Critical ARIA                | error       | Invalid ARIA, missing lang             |
|                |                | Best practices               | warn        | Missing alt text, click handlers       |
|                | Tailwind       | `classnames-order`           | warn        | Auto-fixes class order                 |
|                |                | `no-contradicting-classname` | error       | Conflicting classes (e.g., `p-2 p-4`)  |
|                |                | `no-custom-classname`        | warn        | Non-existent Tailwind classes          |
|                | Import Sorting | `imports`                    | error       | Auto-sorts into groups                 |
|                |                | `exports`                    | error       | Auto-sorts exports                     |
| **Prettier**   | Style          | `semi`                       | `true`      | Always semicolons                      |
|                |                | `singleQuote`                | `true`      | Single quotes                          |
|                |                | `printWidth`                 | `120`       | Wrap at 120 characters                 |
|                |                | `tabWidth`                   | `2`         | 2 spaces indentation                   |
|                |                | `trailingComma`              | `all`       | Trailing commas everywhere             |
|                |                | `arrowParens`                | `always`    | Wrap arrow params                      |
|                |                | `endOfLine`                  | `lf`        | Unix line endings                      |
|                | Plugin         | Tailwind                     | enabled     | Auto-sorts Tailwind classes            |
| **TypeScript** | Type Safety    | `strict`                     | `true`      | All strict checks                      |
|                |                | `noUncheckedIndexedAccess`   | `true`      | Index access returns `T \| undefined`  |
|                |                | `noImplicitOverride`         | `true`      | Requires `override` keyword            |
|                |                | `noFallthroughCasesInSwitch` | `true`      | Prevents switch fallthrough            |
|                | Modules        | `target`                     | `ES2022`    | Modern JavaScript                      |
|                |                | `module`                     | `ESNext`    | Latest import/export                   |
|                |                | `moduleResolution`           | `bundler`   | Vite/Webpack optimized                 |
|                | React          | `jsx`                        | `react-jsx` | Modern JSX (no React import)           |
|                | Performance    | `incremental`                | `true`      | Faster rebuilds                        |
|                |                | `skipLibCheck`               | `true`      | Skip node_modules checking             |

---

## Auto-Fix on Save

> **Important:** Auto-fix on save requires VS Code with ESLint and Prettier extensions installed and configured. See the [complete VS Code setup guide](../../docs/recommended-vscode-config.md) for installation and settings.

| Config       | Feature                 | What Gets Fixed                                                          |
| ------------ | ----------------------- | ------------------------------------------------------------------------ |
| **ESLint**   | Tailwind class ordering | Reorders classes to Tailwind's official order                            |
|              | Import sorting          | Groups and sorts imports (node → external → internal → relative → types) |
|              | Spacing                 | Fixes indentation and whitespace issues                                  |
|              | Unused imports          | Removes safe-to-remove unused imports                                    |
| **Prettier** | Indentation             | Enforces 2-space indentation                                             |
|              | Quotes                  | Converts to single quotes                                                |
|              | Semicolons              | Adds semicolons                                                          |
|              | Line wrapping           | Wraps at 120 characters                                                  |
|              | Trailing commas         | Adds trailing commas                                                     |
|              | Tailwind classes        | Sorts Tailwind classes to official order                                 |

**Manual fixes required:** Missing React keys, hook dependencies, accessibility violations, unused variables

---

## Examples

### Tailwind Class Sorting (Prettier)

```jsx
// Before
<div className="text-white bg-blue-500 hover:bg-blue-600 p-4 rounded flex items-center" />

// After (auto-sorted on save)
<div className="flex items-center rounded bg-blue-500 p-4 text-white hover:bg-blue-600" />
```

### Import Sorting (ESLint)

```typescript
// Before
import { Button } from './Button';
import type { User } from '../types';
import { useState } from 'react';
import { api } from '@composecure/api';
import fs from 'fs';

// After (auto-sorted on save)
import fs from 'fs';

import { useState } from 'react';

import { api } from '@composecure/api';

import type { User } from '../types';
import { Button } from './Button';
```

### TypeScript Strict Checks

```typescript
// Strict null checks
let name: string = null; // ❌ Error
let name: string | null = null; // ✅ OK

// Unchecked index access
const arr = [1, 2, 3];
const item = arr[10]; // Type: number | undefined
item.toFixed(2); // ❌ Error - might be undefined

// Missing override
class Child extends Base {
  method() {} // ❌ Error - missing 'override'
  override method() {} // ✅ OK
}
```

---

## Path Aliases Setup

TypeScript config enables `@/` imports. Bundler configuration required:

**Vite:**

```typescript
// vite.config.ts
import path from 'path';

export default defineConfig({
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
});
```

Requires: `npm install -D @types/node`

**Next.js:** Automatic - no config needed

**Webpack:** Add to `resolve.alias`

**Disable:** Set `"paths": {}` in your tsconfig