Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,101 @@
|
||||
# Package.json Configuration Reference
|
||||
|
||||
## Complete Scripts and Lint-Staged Configuration
|
||||
|
||||
Add these sections to your `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "your-project",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"lint": "eslint . --max-warnings 0",
|
||||
"lint:fix": "eslint . --fix",
|
||||
"format": "prettier --write .",
|
||||
"format:check": "prettier --check .",
|
||||
"prepare": "husky"
|
||||
},
|
||||
"lint-staged": {
|
||||
"*.{js,jsx,ts,tsx}": [
|
||||
"eslint --fix",
|
||||
"prettier --write"
|
||||
],
|
||||
"*.{json,md,yml,yaml,css,scss}": [
|
||||
"prettier --write"
|
||||
]
|
||||
},
|
||||
"devDependencies": {
|
||||
"eslint": "^9.0.0",
|
||||
"@eslint/js": "^9.0.0",
|
||||
"eslint-config-prettier": "^9.1.0",
|
||||
"eslint-plugin-react": "^7.35.0",
|
||||
"eslint-plugin-react-hooks": "^4.6.0",
|
||||
"eslint-plugin-jsx-a11y": "^6.9.0",
|
||||
"@typescript-eslint/parser": "^7.0.0",
|
||||
"@typescript-eslint/eslint-plugin": "^7.0.0",
|
||||
"typescript-eslint": "^7.0.0",
|
||||
"prettier": "^3.3.0",
|
||||
"husky": "^9.0.0",
|
||||
"lint-staged": "^15.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Script Descriptions
|
||||
|
||||
- **lint**: Runs ESLint on entire codebase with zero warning tolerance (fails CI on warnings)
|
||||
- **lint:fix**: Automatically fixes ESLint issues where possible
|
||||
- **format**: Formats all files in project with Prettier
|
||||
- **format:check**: Checks formatting without modifying files (good for CI)
|
||||
- **prepare**: npm lifecycle hook that runs after `npm install` to set up Husky
|
||||
|
||||
## Lint-Staged Configuration
|
||||
|
||||
The `lint-staged` object defines which commands run on which file types during pre-commit:
|
||||
|
||||
- JavaScript/TypeScript files: Run ESLint with auto-fix, then Prettier
|
||||
- Other files (JSON, Markdown, YAML, CSS): Run only Prettier
|
||||
|
||||
### Adding Type Checking
|
||||
|
||||
For stricter pre-commit checks, add TypeScript type checking:
|
||||
|
||||
```json
|
||||
{
|
||||
"lint-staged": {
|
||||
"*.{ts,tsx}": [
|
||||
"eslint --fix",
|
||||
"prettier --write",
|
||||
"bash -c 'tsc --noEmit'"
|
||||
],
|
||||
"*.{js,jsx}": [
|
||||
"eslint --fix",
|
||||
"prettier --write"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: Type checking all staged files can slow down commits. Consider using it selectively.
|
||||
|
||||
### Adding Tests
|
||||
|
||||
To run tests on staged files:
|
||||
|
||||
```json
|
||||
{
|
||||
"lint-staged": {
|
||||
"*.{ts,tsx,js,jsx}": [
|
||||
"eslint --fix",
|
||||
"prettier --write",
|
||||
"jest --bail --findRelatedTests"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `--findRelatedTests` flag runs only tests related to changed files.
|
||||
@@ -0,0 +1,147 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user