type-tune

type-tune is a powerful command-line interface (CLI) tool built with Rust that simplifies the process of managing shared TypeScript types. This tool allows developers to efficiently locate TypeScript type aliases and interface declarations and assists in their safe relocation within projects, removing the tedious task of manually tracking imports.

Key Features

• Discover shared types effortlessly using deterministic candidate IDs to ensure accuracy.
• Review a generated plan to select new destinations for types before any modifications are made, enhancing project organization.
• Rewrite supported type imports, aliases, and simple barrels, while automatically maintaining compatibility exports at the original module path.
• Validate changes with TypeScript’s compiler, implementing a rollback mechanism for normal validation failures and offering dry-run previews for assurance.
• AI Integration: Optionally incorporate AI review notes to provide insights, helping to guide the move without relinquishing control over the rewrite process.

Unlike tools such as Knip, which focuses on identifying unused code, type-tune is designed specifically for relocating types that are actively in use—complementing existing workflows.

Workflow Steps

1. Start with a clean Git working tree.
2. Use the scan command to find candidate types that need relocation:

   npx type-tune scan --project tsconfig.json
   

3. Generate a reviewable plan detailing the proposed moves, outputting to both JSON and Markdown formats:

   npx type-tune plan --project tsconfig.json \ 
   --out .type-tune/plan.json \ 
   --markdown .type-tune/plan.md
   

4. Review the plan to confirm changes or edit manually as necessary:

   npx type-tune review --markdown .type-tune/plan.md
   

5. Preview the changes before applying them to ensure accuracy, using the apply command:

   npx type-tune apply --plan .type-tune/plan.json \ 
   --markdown .type-tune/plan.md --dry-run
   npx type-tune apply --plan .type-tune/plan.json \ 
   --markdown .type-tune/plan.md
   

Example Of Use

For instance, a type initially located within a feature module can be moved to its designated location:

// Before
// src/features/order/OrderPage.tsx
export type OrderSummary = {
  id: string;
  total: number;
};

// After review
// src/features/order/types/order.ts
export type OrderSummary = {
  id: string;
  total: number;
};

With type-tune, the original module retains a type-only compatibility export, and the relevant TypeScript references are updated, preserving existing imports without disrupting consumer code.

Project Scope & Safety

• TypeScript Focused: The tool inspects and rewrites .ts and .tsx files based on the selected tsconfig.json. It does not automatically handle Vue, Svelte, Astro, or external consumers.
• Validation Mechanism: Builds upon TypeScript compiler checks while providing a rollback feature for safe execution.
• Limited Moves: The focus remains on exported type aliases and interfaces only, excluding more complex types such as enums and classes.

For comprehensive details on additional commands and development guidelines, refer to the project's documentation.

Documentation Links:
Architecture | Requirements | AI Review | Release Guide

Conclusion

With type-tune, TypeScript developers gain a reliable tool for managing shared types, promoting code clarity and maintainability across the project.