Code Quality - Chapinismos

Overview

The Chapinismos project uses ESLint for linting and Prettier for code formatting to maintain consistent, high-quality code across the codebase.

ESLint Configuration

Installed Packages

The project uses the following ESLint packages:

eslint (v10.0.2) - Core linting engine
@typescript-eslint/parser (v8.56.1) - TypeScript parsing
eslint-plugin-astro (v1.6.0) - Astro-specific rules
eslint-plugin-jsx-a11y (v6.10.2) - Accessibility rules

Configuration File

ESLint is configured using the modern flat config format in eslint.config.js:

Base Rules

{
  languageOptions: {
    ecmaVersion: "latest",
    sourceType: "module"
  },
  rules: {
    "no-console": "warn",        // Warn on console statements
    "no-unused-vars": "warn",    // Warn on unused variables
    "prefer-const": "error",     // Require const for non-reassigned variables
    "no-var": "error"            // Disallow var keyword
  }
}

Astro Integration

The recommended Astro ESLint configuration is applied:

...eslintPluginAstro.configs.recommended

This includes rules specific to Astro components and best practices.

Accessibility Rules

Accessibility linting helps ensure the site is usable by everyone:

rules: {
  "jsx-a11y/alt-text": "warn",
  "jsx-a11y/anchor-has-content": "warn",
  "jsx-a11y/anchor-is-valid": "warn",
  "jsx-a11y/aria-props": "warn",
  "jsx-a11y/aria-role": "warn",
  "jsx-a11y/aria-unsupported-elements": "warn",
  "jsx-a11y/heading-has-content": "warn",
  "jsx-a11y/html-has-lang": "warn",
  "jsx-a11y/iframe-has-title": "warn",
  "jsx-a11y/img-redundant-alt": "warn"
}

All accessibility violations generate warnings, not errors, allowing gradual improvements.

Ignored Files

The following directories and files are excluded from linting:

dist/** - Build output
.astro/** - Astro cache
.vercel/** - Vercel output
node_modules/** - Dependencies
*.config.js and *.config.mjs - Config files
**/*.min.js - Minified files

Running ESLint

Check for Issues

To lint the entire codebase:

npm run lint

This runs eslint . and displays all warnings and errors.

Auto-fix Issues

To automatically fix fixable issues:

npm run lint:fix

This runs eslint . --fix and corrects issues like:

Missing const declarations
Unused imports (when safe)
Formatting issues ESLint can fix

Not all ESLint issues can be auto-fixed. Review the output for remaining warnings and errors that require manual fixes.

Prettier Configuration

Installed Packages

The project uses the following Prettier packages:

prettier (v3.8.1) - Code formatter
prettier-plugin-astro (v0.14.1) - Astro formatting
prettier-plugin-tailwindcss (v0.7.2) - Tailwind class sorting

Configuration File

Prettier is configured in .prettierrc:

{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "useTabs": false,
  "trailingComma": "es5",
  "printWidth": 100,
  "arrowParens": "always",
  "plugins": [
    "prettier-plugin-astro",
    "prettier-plugin-tailwindcss"
  ],
  "overrides": [
    {
      "files": "*.astro",
      "options": {
        "parser": "astro"
      }
    }
  ]
}

Configuration Details

Semicolons: Required (semi: true)
Quotes: Double quotes (singleQuote: false)
Indentation: 2 spaces (tabWidth: 2, useTabs: false)
Trailing commas: ES5 compatible (objects, arrays)
Line width: 100 characters maximum
Arrow functions: Always use parentheses around parameters

Plugin Features

prettier-plugin-astro:

Formats .astro files correctly
Handles Astro component syntax
Preserves frontmatter formatting

prettier-plugin-tailwindcss:

Automatically sorts Tailwind CSS classes
Uses official Tailwind class order
Works in HTML, JSX, and Astro files

Running Prettier

Format All Files

To format the entire codebase:

npm run format

This runs prettier --write . and formats all supported files.

Check Formatting

To check if files are formatted without making changes:

npm run format:check

This runs prettier --check . and exits with an error if any files need formatting.

Use npm run format:check in CI/CD pipelines to ensure consistent formatting before deployment.

Editor Integration

Visual Studio Code

Recommended extensions:

ESLint (dbaeumer.vscode-eslint)
Prettier (esbenp.prettier-vscode)
Astro (astro-build.astro-vscode)

VS Code Settings

Add to .vscode/settings.json:

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

This configuration:

Formats files on save with Prettier
Auto-fixes ESLint issues on save
Uses Prettier for Astro files

Other Editors

For other editors, install:

ESLint plugin/extension
Prettier plugin/extension
Astro language support

Configure format-on-save and auto-fix according to your editor’s documentation.

Pre-commit Hooks

While the project doesn’t currently use pre-commit hooks, you can add them to enforce code quality:

Using Husky and lint-staged

Install Dependencies

npm install --save-dev husky lint-staged

Initialize Husky

npx husky init

Configure lint-staged

Add to package.json:

{
  "lint-staged": {
    "*.{js,mjs,astro,ts}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,css}": [
      "prettier --write"
    ]
  }
}

Create Pre-commit Hook

Create .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

Make Hook Executable

chmod +x .husky/pre-commit

Now ESLint and Prettier run automatically on staged files before each commit.

CI/CD Integration

GitHub Actions Example

Add a code quality check workflow (.github/workflows/lint.yml):

name: Code Quality

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Check formatting
        run: npm run format:check
      
      - name: Run linter
        run: npm run lint

This workflow:

Runs on pull requests and pushes to main
Checks formatting with Prettier
Lints code with ESLint
Fails the build if issues are found

Best Practices

Before Committing

Run linting: npm run lint:fix
Run formatting: npm run format
Fix any remaining warnings or errors
Test your changes: npm run dev

Code Review Checklist

No ESLint errors or warnings
Code is formatted with Prettier
Accessibility rules are followed
No console.log statements in production code
Unused variables and imports removed

Writing Clean Code

Use const by default, let only when reassignment is needed
Avoid var keyword (ESLint will error)
Add alt text to all images
Ensure interactive elements are keyboard accessible
Keep functions small and focused
Write descriptive variable and function names

Troubleshooting

ESLint Errors

“Parsing error”:

Ensure file extensions are correct (.astro, .js, .ts)
Check for syntax errors in the file
Verify TypeScript parser is installed

“Failed to load plugin”:

rm -rf node_modules package-lock.json
npm install

Prettier Issues

Files not formatting:

Check file extension is supported
Verify Prettier plugins are installed
Look for syntax errors preventing parsing

Conflicting with ESLint:

This project doesn’t use eslint-config-prettier as Prettier handles formatting
ESLint focuses on code quality, not formatting

Editor Issues

Format on save not working:

Verify Prettier extension is installed and enabled
Check workspace settings override user settings
Restart editor after configuration changes

ESLint not showing errors:

Ensure ESLint extension is installed
Check ESLint output panel for errors
Verify eslint.config.js is valid

Next Steps

Set up pre-commit hooks for automatic checks
Configure your editor for format-on-save
Review Local Setup for development workflow
Explore Building and Deployment for production checks

Get Started

Content Management

Architecture

Features

Customization

Development

Contributing

​Overview

​ESLint Configuration

​Installed Packages

​Configuration File

​Base Rules

​Astro Integration

​Accessibility Rules

​Ignored Files

​Running ESLint

​Check for Issues

​Auto-fix Issues

​Prettier Configuration

​Installed Packages

​Configuration File

​Configuration Details

​Plugin Features

​Running Prettier

​Format All Files

​Check Formatting

​Editor Integration

​Visual Studio Code

​VS Code Settings

​Other Editors

​Pre-commit Hooks

​Using Husky and lint-staged

​CI/CD Integration

​GitHub Actions Example

​Best Practices

​Before Committing

​Code Review Checklist

​Writing Clean Code

​Troubleshooting

​ESLint Errors

​Prettier Issues

​Editor Issues

​Next Steps

Build docs developers (and LLMs) love

Overview

ESLint Configuration

Installed Packages

Configuration File

Base Rules

Astro Integration

Accessibility Rules

Ignored Files

Running ESLint

Check for Issues

Auto-fix Issues

Prettier Configuration

Installed Packages

Configuration File

Configuration Details

Plugin Features

Running Prettier

Format All Files

Check Formatting

Editor Integration

Visual Studio Code

VS Code Settings

Other Editors

Pre-commit Hooks

Using Husky and lint-staged

CI/CD Integration

GitHub Actions Example

Best Practices

Before Committing

Code Review Checklist

Writing Clean Code

Troubleshooting

ESLint Errors

Prettier Issues

Editor Issues

Next Steps