syncing-tsconfig-paths

Synchronizes tsconfig.json paths from package.json imports field. Ensures TypeScript resolves subpath imports (#imports) correctly during development.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 22, 2025

When & Why to Use This Skill

This Claude skill automates the synchronization between package.json subpath imports and tsconfig.json path mappings. It solves the common development friction where TypeScript fails to resolve modern Node.js '#imports' by automatically translating build-directory references into source-directory paths, ensuring seamless IDE navigation and type checking without manual configuration overhead.

Use Cases

  • Modern Node.js Development: Automatically map subpath imports (#imports) defined in package.json to the corresponding source files in tsconfig.json to enable immediate IntelliSense and error checking.
  • Build-to-Source Redirection: Maintain 'Go to Definition' functionality in IDEs by transforming build-output paths (e.g., ./build/*.js) into source paths (e.g., ./src/*.ts) within the TypeScript configuration.
  • CI/CD Configuration Auditing: Use the --check flag in continuous integration pipelines to verify that configuration files are in sync, preventing broken builds or unresolved module errors in shared environments.
  • Refactoring and Scaling: Quickly update path mappings across large projects whenever the package.json imports field is modified, eliminating the risk of manual entry errors.
namesyncing-tsconfig-paths
descriptionSynchronizes tsconfig.json paths from package.json imports field. Ensures TypeScript resolves subpath imports (#imports) correctly during development.

Syncing TSConfig Paths

Keep tsconfig paths in sync with package.json subpath imports.

Steps

Syncing

pnpm exec tsx .claude/skills/syncing-tsconfig-paths/scripts/sync-tsconfig-paths.ts

Auditing

Run with --check flag to verify without modifying:

pnpm exec tsx .claude/skills/syncing-tsconfig-paths/scripts/sync-tsconfig-paths.ts --check

Reference

The script transforms package.json imports to tsconfig paths:

// package.json
{
  "imports": {
    "#pkg": "./build/_.js",
    "#foo": "./build/foo.js"
  }
}

Becomes:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "#pkg": ["./src/_.ts"],
      "#foo": ["./src/foo.ts"]
    }
  }
}

Key transformation: ./build/ → ./src/ (extension stays .js - TypeScript with nodenext resolves to .ts)

Notes

  • Run after modifying any package's imports field
  • Conditional imports (objects with browser/default) are skipped with a warning
  • This enables TypeScript to resolve # imports during development before build