paucasanellas

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:

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

References