Backend TypeScript – Best Practices & Skills

This skill provides guidance for working on TypeScript backend projects that follow this pattern: structure under src/, ESM, Express, PostgreSQL/MongoDB, and tests with Mocha + tsx. Align with refactor.md, test.md, doc.md, and create-project.md in commands/ when refactoring, testing, documenting, or creating new projects.

When to Use

• Writing new controllers, models, or utilities in TypeScript
• Creating or updating tests (.test.ts, Mocha + tsx/cjs)
• Implementing features in a codebase that uses src/, env.pgConnection, env.pgModels
• Reviewing or refactoring TypeScript backend code
• Generating OpenAPI docs or new project scaffolds

Core Technologies

Runtime & Language

• Node.js: ESM ("type": "module"), run with tsx (or compiled dist/ with node)
• TypeScript: Strict mode, .ts only under src/ (and config/ if needed)
• Imports: Use .js extension in import paths for ESM resolution (e.g. from "./app.js"); tsx/Node resolve to .ts when needed. No .mjs.
• No dynamic imports in handlers: Do not use await import(...) inside controller/model method bodies for normal dependencies. Resolve imports at module scope (or in a dedicated adapter module) to keep types and behavior explicit.