tsconfig.node.json

// ============================================================================
// QUICK REFERENCE: TYPESCRIPT NODE CONFIGURATION
// ============================================================================
// | CONCEPT                       | DESCRIPTION                                                                 |
// |-------------------------------|-----------------------------------------------------------------------------|
// | target                        | Specifies the JavaScript language version for the emitted output.           |
// | lib                           | Defines which built-in type definitions to include (e.g., ES2023, DOM).     |
// | module                        | Sets the module system for the project (ESNext for modern ESM).             |
// | skipLibCheck                  | Skips type checking of .d.ts files to improve compilation speed.           |
// | moduleResolution              | Determines how TypeScript resolves module imports (e.g., bundler, node).     |
// | noEmit                        | Tells TypeScript not to output files (letting a bundler like Vite do it).    |
// | strict                        | Enables a wide range of strong type-checking behavior.                      |
// | include                       | Specifies the files or directories the compiler should process.             |
// ============================================================================

// ============================================================================
// FILE DOCUMENTATION: tsconfig.node.json
// ============================================================================
// FILE NAME: tsconfig.node.json
//
// WHAT THIS FILE DOES:
// This is a specialized TypeScript configuration file designed specifically 
// for the Node.js environment. It focuses on the build-tooling side of the 
// project rather than the code that runs in the user's browser.
//
// WHAT THE SYSTEM USES IT FOR:
// It primarily configures how 'vite.config.ts' is parsed and type-checked.
// Since Vite runs on Node.js, it can use more modern JS features than the 
// client-side code might support.
//
// EXECUTION FLOW:
// 1. The IDE/Compiler detects this file.
// 2. It applies these specific rules only to the files listed in "include".
// 3. It ensures development tools have full type-safety without mixing 
//    Node-specific globals (like 'process') with Browser globals (like 'window').
//
// MAIN SECTIONS:
// - compilerOptions: Technical rules for how TS interprets the code.
// - include: Scope definition (which files this config governs).
// ============================================================================

{
  // ============================================================
  // SECTION: COMPILER OPTIONS
  // ============================================================
  "compilerOptions": {
    
    // We target ES2022 because Node.js environments (where Vite runs) 
    // are typically more updated than general-purpose browsers.
    "target": "ES2022",

    // We only include ES2023 libraries. Since this is for Node.js, 
    // we explicitly exclude "DOM" to prevent using browser-only 
    // APIs in our build configuration scripts.
    "lib": ["ES2023"],

    // Use ESNext to support the latest ECMAScript module syntax 
    // (import/export), which is standard for Vite projects.
    "module": "ESNext",

    // Skips checking the types of external node_modules. 
    // This significantly speeds up the development environment.
    "skipLibCheck": true,

    // "bundler" resolution is optimized for tools like Vite that 
    // understand modern module loading strategies.
    "moduleResolution": "bundler",

    // Allows importing .ts files directly in the config—useful 
    // for keeping the build pipeline strictly typed.
    "allowImportingTsExtensions": true,

    // Ensures that each file can be transpiled safely without 
    // needing to check other files (required by many modern bundlers).
    "isolatedModules": true,

    // Forces TypeScript to treat all files as modules, preventing 
    // global scope pollution in the config scripts.
    "moduleDetection": "force",

    // This file is only for type-checking. Vite handles the 
    // actual conversion from TS to JS, so we don't "emit" files here.
    "noEmit": true,

    // Load Node.js types for Vite's config file.
    // vite.config.ts runs in Node, so it can use path, __dirname, process, etc.
    "types": ["node"],

    // Enables "Strict Mode" to catch potential bugs and enforce 
    // the high engineering standards you're aiming for, Carlos.
    "strict": true
  },

  // ============================================================
  // SECTION: INCLUSION RULES
  // ============================================================
  
  // We strictly limit this config to the Vite configuration file.
  // This prevents Node-specific types from leaking into your 
  // frontend application logic.
  "include": ["vite.config.ts"]
}