TSConfig Module Paths Protocol

Module path management for all agents (Cursor, Vitto, Claude Code, Cowork)

TSConfig Module Paths Protocol

Applies to: Cursor, Vitto (backend-vitto-api), Claude Code, Claude Cowork, and any agent that generates or modifies modules.

Single source of truth: config/tsconfig-paths/modules/*.paths.json
tsconfig.base.json is derived via yarn paths:merge — never edit it for @module/* paths.

Mandatory Rules

  1. NEVER add or edit @module/* or @modules/* path entries directly in tsconfig.base.json.

  2. ALWAYS add new module paths to:

    • config/tsconfig-paths/modules/generated.paths.json (AI-generated modules)
    • Or the appropriate category file: sports.paths.json, restaurant.paths.json, etc.

  3. ALWAYS run yarn paths:merge after adding or changing paths in any *.paths.json file.

Workflow for New Modules

1. Add path to config/tsconfig-paths/modules/generated.paths.json:
   {
     "paths": {
       "@module/my-module": ["modules/my-module/src/index"],
       "@module/my-module/*": ["modules/my-module/src/*"]
     }
   }

2. Run: yarn paths:merge

3. Verify: yarn paths:validate

Commands

Command Purpose
yarn paths:merge Merge config files → tsconfig.base.json
yarn paths:merge:dry Preview merge without writing
yarn paths:validate Validate all path files
yarn paths:extract Extract from tsconfig → category files (recovery only)
yarn paths:sync Remove stale paths for deleted modules
yarn paths:check Verify tsconfig is in sync (CI/pre-commit)

Reference