Coding Practices

Code Organization

• Single responsibility: Each source file should have a clear, focused scope/purpose

• Split large files: Break files when they become large or handle too many concerns

• Type separation: Always separate types and interfaces into shared/types/*.ts

• Constants extraction: Move constants to a dedicated shared/consts/*.ts file

• Utils extraction: Move utils to a dedicated shared/utils/*.ts file

• Schemas extraction: Move zod schemas to a dedicated shared/schemas/*.ts file

Runtime Environment

• Prefer isomorphic code: Write runtime-agnostic code that works in Node, browser, and workers whenever possible

• Clear runtime indicators: When code is environment-specific, add a comment at the top of the file:

// @env node // @env browser

TypeScript

• Explicit return types: Declare return types explicitly when possible

• Avoid complex inline types: Extract complex types into dedicated type or interface declarations

Comments

• Avoid unnecessary comments: Code should be self-explanatory

• Explain "why" not "how": Comments should describe the reasoning or intent, not what the code does

Testing (Vitest)

• Test files: foo.ts → foo.test.ts (same directory)

• Use describe /it API (not test )

Tooling Choices

TypeScript Config

{ "compilerOptions": { "target": "ESNext", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "resolveJsonModule": true, "isolatedModules": true, "noEmit": true } }

ESLint Setup

// eslint.config.ts import { createConfigForNuxt } from '@nuxt/eslint-config'

export default createConfigForNuxt({ // options here })

When completing tasks, run pnpm run lint --fix to format the code and fix coding style.

For detailed configuration options: paucasanellas-eslint-config

pnpm Catalogs

Use named catalogs in pnpm-workspace.yaml for version management:

Catalog Purpose

prod

Production dependencies

inlined

Bundler-inlined dependencies

dev

Dev tools (linter, bundler, testing)

frontend

Frontend libraries

Avoid the default catalog. Catalog names can be adjusted per project needs.

References

Topic Description Reference

ESLint Config Framework support, formatters, rule overrides, VS Code settings antfu-eslint-config

Project Setup .gitignore, GitHub Actions, VS Code extensions setting-up

App Development Vue/Nuxt/NuxtUI conventions and patterns app-development