Standards to Tooling

Maps project-specific coding conventions to linting/formatting tool configuration. For the Stars project: JS/TS/Vue codebase with ESLint 10 + Prettier, migrating to full TypeScript.

Mindset

A convention that cannot be auto-enforced will drift. Before implementing any standard, always ask: Can a tool catch this? If yes, configure it. If no, document it as a code review checklist item.

Prefer tools that provide fix-on-save or --fix support — adoption is higher when enforcement is automatic rather than manual.

When to Use

• Onboarding a new project and need to set up linting/formatting from scratch
• Adding a new code convention that should be machine-enforced
• Reviewing a PR where a convention was violated and a tool should catch it
• Migrating a codebase (e.g., JS → TS) and need to update or add tooling
• Standardising tooling across multiple projects or monorepo workspaces

Workflow

1. Discovery — Extract actionable standards

Source the project's conventions from:

For each convention, classify it:

2. Mapping — Convention → Rule

Use this reference for the Stars project's tech stack:

JavaScript / TypeScript (ESLint)

Vue SFCs (eslint-plugin-vue)

Formatting (Prettier)

TypeScript (tsconfig.json)

3. Implementation — Generate config

When creating or updating config files, follow these principles:

ESLint flat config (eslint.config.js):

• Use ESM (export default), not .eslintrc
• Organise by file glob: separate JS/TS blocks from Vue SFC blocks
• Use the files array to scope rules correctly
• Vue SFCs need vue-eslint-parser as outer parser with TS parser inside

Prettier config (.prettierrc):

• Keep it minimal — formatting rules belong here, logic rules belong in ESLint
• Use prettier-plugin-sort-imports for import order when ESLint import plugin is not used
• Pair with format and format:check npm scripts

TypeScript config (tsconfig.json):

• Separate tsconfig.json (IDE/typecheck) from Vite config
• Set "noEmit": true when using Vite for bundling
• Enable strict: true as a baseline, relax specific checks only with documented justification

4. Verification — Tooling checklist

After implementing, verify with:

# Lint all source files
npx eslint 'web/src/**/*.{ts,js,vue}'

# Check formatting (without writing)
npx prettier --check 'web/src/**/*.{ts,vue,css}'

# TypeScript type check
npx vue-tsc --noEmit

# Fix all auto-fixable issues
npx eslint --fix 'web/src/**/*.{ts,js,vue}'
npx prettier --write 'web/src/**/*.{ts,vue,css}'

5. CI Integration

Ensure lint/format/typecheck runs in CI:

name: Lint & Typecheck
steps:
  - run: npm run format:check   # Prettier
  - run: npm run lint           # ESLint
  - run: npm run typecheck      # vue-tsc

Add to package.json scripts:

{
  "lint": "eslint 'web/src/**/*.{ts,js,vue}'",
  "lint:fix": "eslint --fix 'web/src/**/*.{ts,js,vue}'",
  "format": "prettier --write 'web/src/**/*.{ts,vue,css}'",
  "format:check": "prettier --check 'web/src/**/*.{ts,vue,css}'",
  "typecheck": "vue-tsc --noEmit -p web/tsconfig.json"
}

Consider adding pre-commit hooks (lefthook, husky + lint-staged) to catch issues before they reach CI.

Language Quick Reference

When the project's language differs from Stars (JS/TS/Vue), use these mappings:

Never

• Never add a tool that the project doesn't already use without asking — introducing a new linter/formatter is a team decision
• Never change prettier formatting options without verifying the change across the full codebase (formatting wars are expensive)
• Never override a tool's default without a documented code convention that justifies it
• Never configure ESLint rules that conflict with Prettier rules (use eslint-config-prettier to disable style rules ESLint handles)
• Never add a rule that produces noise — warnings that are always ignored reduce trust in the tool
• Never skip documenting why a rule exists — future maintainers need to know if the convention still applies

References

• Vue 3 Style Guide
• ESLint Flat Config docs
• typescript-eslint rules
• Prettier options
• Biome (alternative to ESLint + Prettier for JS/TS)
• Related skills: vault-capture (persist tooling decisions as semantic memories)