hana-developer-cli-tool-example typescript-configuration.instructions.md

TypeScript Configuration Guidelines

Use this guide when creating or modifying TypeScript configuration files (tsconfig.json) in the project.

Scope and Purpose

This guide applies to TypeScript configuration in:

• Root tsconfig.json - Type generation from JavaScript sources
• mcp-server/tsconfig.json - TypeScript source compilation
• Subdirectory-specific TypeScript configs
• Build-specific TypeScript configs (e.g., tsconfig.build.json)

Critical Principles

1. Dual Config Strategy: Root config for type generation, subproject configs for compilation
2. ESM Compatibility: Use Node16/NodeNext module resolution for ESM projects
3. Strict Mode: Enable strict type checking for maximum safety
4. Declaration Files: Generate .d.ts files for external consumption
5. Source Maps: Enable source maps for debugging compiled code
6. Incremental Builds: Use incremental compilation for faster rebuilds
7. Path Mappings: Configure path aliases for clean imports
8. Type-Only Imports: Use "importsNotUsedAsValues": "error" to enforce type-only imports

Root Configuration Pattern (Type Generation from JS)

Pattern: Generate Types from JavaScript Sources

This project uses JavaScript with JSDoc comments for the main CLI. TypeScript is configured to extract type definitions:

{
  "compilerOptions": {
    // Enable type checking and declaration generation from JS
    "allowJs": true,                    // Process .js files
    "checkJs": true,                    // Type-check .js files
    "declaration": true,                // Generate .d.ts files
    "emitDeclarationOnly": true,        // ONLY generate declarations
    
    // Module system
    "module": "ESNext",                 // Use latest ECMAScript modules
    "moduleResolution": "node",         // Node.js style resolution
    "target": "ES2022",                 // Modern JavaScript features
    
    // Output configuration
    "outDir": "./types",                // Type declarations go here
    "rootDir": ".",                     // Source root
    
    // Type checking strictness
    "strict": false,                    // Lenient for JS sources
    "noImplicitAny": false,             // Allow implicit any in JS
    "strictNullChecks": false,          // No null checks for JS
    
    // Other options
    "esModuleInterop": true,            // CommonJS/ESM interop
    "skipLibCheck": true,               // Skip library type checks
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true           // Import JSON files
  },
  
  "include": [
    "bin/**/*.js",
    "routes/**/*.js",
    "utils/**/*.js",
    "index.js"
  ],
  
  "exclude": [
    "node_modules",
    "tests",
    "coverage",
    "types",
    "**/*.test.js",
    "**/*.Test.js"
  ]
}