148 lines
3.9 KiB
Markdown
148 lines
3.9 KiB
Markdown
# Code Quality Setup - Team Documentation
|
|
|
|
## Overview
|
|
|
|
This project uses automated code quality tools to maintain consistent code style and catch errors early:
|
|
|
|
- **ESLint** - Identifies code quality issues and potential bugs
|
|
- **Prettier** - Automatically formats code to consistent style
|
|
- **Husky** - Runs quality checks before commits via git hooks
|
|
- **lint-staged** - Only checks files you're committing (fast!)
|
|
- **GitHub Actions** - Verifies code quality in CI
|
|
|
|
## For New Team Members
|
|
|
|
### First Time Setup
|
|
|
|
After cloning the repository, run:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
This automatically sets up Husky git hooks via the `prepare` script.
|
|
|
|
### Daily Workflow
|
|
|
|
When you make changes and commit:
|
|
|
|
1. Stage your files: `git add .`
|
|
2. Commit: `git commit -m "your message"`
|
|
3. **Pre-commit hook automatically runs** and checks your staged files
|
|
4. If checks pass, commit succeeds
|
|
5. If checks fail, fix the issues and try again
|
|
|
|
### Manual Quality Checks
|
|
|
|
Run these commands any time:
|
|
|
|
```bash
|
|
# Check for linting errors
|
|
npm run lint
|
|
|
|
# Auto-fix linting issues
|
|
npm run lint:fix
|
|
|
|
# Format all files
|
|
npm run format
|
|
|
|
# Check formatting (doesn't modify files)
|
|
npm run format:check
|
|
```
|
|
|
|
### IDE Integration
|
|
|
|
**Recommended**: Install ESLint and Prettier extensions in your editor:
|
|
|
|
- **VS Code**: Install "ESLint" and "Prettier - Code formatter" extensions
|
|
- **WebStorm/IntelliJ**: Enable ESLint and Prettier in Settings > Languages & Frameworks
|
|
|
|
Configure format on save in your editor for the best experience.
|
|
|
|
## Common Scenarios
|
|
|
|
### Pre-commit Hook Fails
|
|
|
|
**Linting errors**: Review the errors shown. Run `npm run lint:fix` to auto-fix many issues.
|
|
|
|
**Formatting issues**: Run `npm run format` to format all files, then try committing again.
|
|
|
|
**Type errors**: Fix TypeScript errors shown in the output. The hook prevents commits with type errors.
|
|
|
|
### Bypassing Hooks (Emergency Only)
|
|
|
|
In rare cases where you need to commit despite failing checks:
|
|
|
|
```bash
|
|
git commit --no-verify -m "your message"
|
|
```
|
|
|
|
**Warning**: Only use this for emergencies. The CI will still fail if code quality checks don't pass.
|
|
|
|
### Updating ESLint Rules
|
|
|
|
If you encounter a rule that doesn't make sense for your use case:
|
|
|
|
1. Discuss with the team first
|
|
2. Update `eslint.config.mjs` with the agreed change
|
|
3. Run `npm run lint` to verify the change works
|
|
4. Commit the configuration change
|
|
|
|
## Troubleshooting
|
|
|
|
### Hooks Not Running
|
|
|
|
If pre-commit hooks don't run when you commit:
|
|
|
|
```bash
|
|
# Reinstall Husky
|
|
rm -rf .husky
|
|
npm run prepare
|
|
```
|
|
|
|
Verify `.husky/pre-commit` exists and is executable.
|
|
|
|
### ESLint Configuration Errors
|
|
|
|
If ESLint fails to run with configuration errors:
|
|
|
|
```bash
|
|
# Check your Node version (should be 18+)
|
|
node --version
|
|
|
|
# Reinstall dependencies
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
```
|
|
|
|
### Conflicts Between Tools
|
|
|
|
If ESLint and Prettier report conflicting issues:
|
|
|
|
- Prettier should always win for formatting issues
|
|
- Check that `eslint-config-prettier` is installed
|
|
- Verify it's last in the config chain to disable conflicting ESLint rules
|
|
|
|
### CI Passing Locally But Failing in GitHub Actions
|
|
|
|
- Ensure you've committed all configuration files
|
|
- Verify Node.js version matches between local and CI
|
|
- Check that all devDependencies are in package.json
|
|
- Run `npm run lint` and `npm run format:check` locally before pushing
|
|
|
|
## Configuration Files
|
|
|
|
- `eslint.config.mjs` - ESLint rules and configuration
|
|
- `.prettierrc` - Prettier formatting rules
|
|
- `.prettierignore` - Files Prettier should skip
|
|
- `.husky/pre-commit` - Pre-commit hook that runs lint-staged
|
|
- `package.json` - Contains lint-staged configuration and scripts
|
|
- `.github/workflows/lint.yml` - CI workflow for automated checks
|
|
|
|
## Additional Resources
|
|
|
|
- [ESLint Documentation](https://eslint.org/docs/latest/)
|
|
- [Prettier Documentation](https://prettier.io/docs/en/)
|
|
- [Husky Documentation](https://typicode.github.io/husky/)
|
|
- [lint-staged Documentation](https://github.com/lint-staged/lint-staged)
|