typescript-development

TypeScript Development Rules

Description

Best practices and conventions for TypeScript development in this workspace, including module imports, testing framework usage, and file naming conventions.

Module Import Rules

Use Explicit File Extensions

When using ESNext modules ("module": "ESNext" in tsconfig.json), always use explicit file extensions in import statements.

Rule: Import with .js Extension

// ✅ Correct - Use .js extension (refers to compiled output)
import { myFunction } from "./my-module.js";

// ❌ Incorrect - Missing extension causes linter errors
import { myFunction } from "./my-module";

Why This Rule Exists

• ESNext modules follow ES6 import standards requiring explicit extensions
• TypeScript compiles .ts → .js, so imports reference the final output
• Runtime and Vitest resolve correctly, but TypeScript language server needs explicit extensions
• Future-proof - aligns with modern ES module standards

When to Apply

• All local module imports (relative paths starting with ./ or ../)
• Not needed for node_modules imports (e.g., import { describe } from "vitest")
• Not needed when using CommonJS modules ("module": "CommonJS")

Testing Framework Rules

Use Vitest for Unit Testing

Rule: Vitest is the Standard Testing Framework

// ✅ Correct - Import from vitest
import { describe, it, expect } from "vitest";

// ❌ Incorrect - Don't use jest, mocha, or other frameworks
import { describe, it, expect } from "jest";

Vitest Configuration

• Use vitest --run
• Leverage Vitest's TypeScript support out of the box
• No additional configuration needed for basic usage

File Naming Conventions

Test Files: Use .spec.ts Extension

Rule: Tests are Specifications

✅ Correct naming:
- calculator.spec.ts
- string-calculator.spec.ts
- user-service.spec.ts

❌ Incorrect naming:
- calculator.test.ts
- string-calculator.test.ts
- user-service.test.ts