flyer-crawler.projectium.com/docs/adr/0021-code-formatting-and-linting-unification.md

ADR-021: Code Formatting and Linting Unification

Date: 2025-12-12

Status: Accepted

Implemented: 2026-01-09

Context

The project contains both frontend (React) and backend (Node.js) code. While linters may be in use, there isn't a single, enforced standard for code style and quality across the entire repository. This leads to inconsistent code and time wasted in code reviews on stylistic debates.

Decision

We will mandate the use of Prettier for automated code formatting and a unified ESLint configuration for code quality rules across both frontend and backend. This will be enforced automatically using a pre-commit hook managed by Husky and lint-staged.

Consequences

Positive: Improves developer experience and team velocity by automating code consistency. Reduces time spent on stylistic code review comments. Enhances code readability and maintainability.

Negative: Requires an initial setup and configuration of Prettier, ESLint, and Husky. May require a one-time reformatting of the entire codebase.

Implementation Status

What's Implemented

• ✅ Prettier Configuration - .prettierrc with consistent settings
• ✅ Prettier Ignore - .prettierignore to exclude generated files
• ✅ ESLint Configuration - eslint.config.js with TypeScript and React support
• ✅ ESLint + Prettier Integration - eslint-config-prettier to avoid conflicts
• ✅ Husky Pre-commit Hooks - Automatic enforcement on commit
• ✅ lint-staged - Run linters only on staged files for performance

Implementation Details

Prettier Configuration

The project uses a consistent Prettier configuration in .prettierrc:

{
  "semi": true,
  "trailingComma": "all",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "endOfLine": "auto"
}

ESLint Configuration

ESLint is configured with:

• TypeScript support via typescript-eslint
• React hooks rules via eslint-plugin-react-hooks
• React Refresh support for HMR
• Prettier compatibility via eslint-config-prettier

// eslint.config.js (ESLint v9 flat config)
import globals from 'globals';
import tseslint from 'typescript-eslint';
import pluginReact from 'eslint-plugin-react';
import pluginReactHooks from 'eslint-plugin-react-hooks';
import pluginReactRefresh from 'eslint-plugin-react-refresh';
import eslintConfigPrettier from 'eslint-config-prettier';

export default tseslint.config(
  // ... configurations
  eslintConfigPrettier, // Must be last to override formatting rules
);

Pre-commit Hook

The pre-commit hook runs lint-staged automatically:

# .husky/pre-commit
npx lint-staged

lint-staged Configuration

lint-staged runs appropriate tools based on file type:

{
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{json,md,css,html,yml,yaml}": ["prettier --write"]
}

NPM Scripts

Script	Description
npm run format	Format all files with Prettier
npm run lint	Run ESLint on all TypeScript/JavaScript files
npm run validate	Run Prettier check + TypeScript check + ESLint

Key Files

File	Purpose
.prettierrc	Prettier configuration
.prettierignore	Files to exclude from formatting
eslint.config.js	ESLint flat configuration (v9)
.husky/pre-commit	Pre-commit hook script
.lintstagedrc.json	lint-staged configuration

Developer Workflow

Automatic Formatting on Commit

When you commit changes:

1. Husky intercepts the commit
2. lint-staged identifies staged files
3. ESLint fixes auto-fixable issues
4. Prettier formats the code
5. Changes are automatically staged
6. Commit proceeds if no errors

Manual Formatting

# Format entire codebase
npm run format

# Check formatting without changes
npx prettier --check .

# Run ESLint
npm run lint

# Run all validation checks
npm run validate

IDE Integration

For the best experience, configure your IDE:

VS Code - Install extensions:

• Prettier - Code formatter
• ESLint

Add to .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

Troubleshooting

"eslint --fix failed"

ESLint may fail on unfixable errors. Review the output and manually fix the issues.

"prettier --write failed"

Check for syntax errors in the file that prevent parsing.

Bypassing Hooks (Emergency)

In rare cases, you may need to bypass hooks:

git commit --no-verify -m "emergency fix"

Use sparingly - the CI pipeline will still catch formatting issues.