ts-import-move

Stop breaking your TypeScript projects when refactoring! This powerful CLI tool safely moves TypeScript files/folders while automatically updating all import references, preventing the #1 cause of refactoring pain.

Why Your Project Needs This

When refactoring TypeScript projects, using the standard Unix mv command will silently break all import statements across your project, leading to:

• ❌ Hours of frustrating debugging
• ❌ Compilation errors everywhere
• ❌ Wasted development time fixing imports manually
• ❌ Broken CI/CD pipelines

Without ts-import-move, the only way to safely move TypeScript files is through VS Code's GUI interface—leaving command-line workflows and CI/CD pipelines vulnerable to broken imports.

This tool bridges that critical gap, providing a drop-in replacement for mv that's TypeScript-aware:

• ✅ Seamlessly preserves all import references
• ✅ Works with the same familiar command-line syntax
• ✅ Integrates perfectly with automation and CI/CD
• ✅ Saves hours of tedious manual fixes

Features

• TypeScript-Aware - Uses ts-morph to handle file moves while ensuring all imports are updated
• Multiple Files - Move multiple files at once with glob pattern support
• Interactive Mode - Prompt before overwriting files with -i flag
• Dry Run - Preview changes without modifying files with -n flag
• Cross-Platform - Works on any OS where Node.js runs

Installation

# Install globally
npm install -g ts-import-move

# Or with pnpm
pnpm add -g ts-import-move

Usage

ts-import-move [options] <sources...> <destination>

Examples

Move a single file:

# Instead of breaking your project with:
# mv src/utils/helpers.ts src/shared/helpers.ts

# Use this and keep everything working:
ts-import-move src/utils/helpers.ts src/shared/helpers.ts

Move multiple files to a directory:

ts-import-move src/components/Button.tsx src/components/Input.tsx src/ui/

Move with wildcard patterns:

ts-import-move "src/components/*.tsx" src/ui/

Preview changes without moving files:

ts-import-move -n src/old/ src/new/

Options

• -r, --recursive - Recursively move directories
• -i, --interactive - Prompt before overwriting files
• -f, --force - Force overwrite without prompt
• -n, --dry-run - Show what would be moved without making changes
• -v, --verbose - Display detailed operation logs
• --extensions <ext> - Specify file extensions to consider (default: .ts,.tsx)
• --tsconfig <path> - Path to tsconfig.json (default: auto-detect)

For AI Agents

This tool is especially valuable for AI agents working with TypeScript codebases:

Best Practice for AI Agents

AI agents should adopt the following pattern when refactoring TypeScript projects:

# Instead of:
mv src/components/Button.tsx src/ui/

# Use:
ts-import-move src/components/Button.tsx src/ui/

This small change prevents import breakage while maintaining the familiar move command syntax, saving debugging time and reducing token usage that would otherwise be spent fixing broken imports.

Agent Integration Examples

Reorganizing components in a React project:

ts-import-move -f "src/components/*.tsx" src/ui/components/

Moving multiple utility files:

ts-import-move -f --verbose src/utils/format.ts src/utils/validation.ts src/shared/

Moving an entire directory with recursive flag:

ts-import-move -f -r src/services/ src/api/services/

Moving files based on a pattern match:

ts-import-move -f "src/components/forms/**/*.tsx" src/features/forms/

Dry run to preview changes without applying them:

ts-import-move -n "src/hooks/*.ts" src/common/hooks/

The tool will automatically:

1. Move the specified files/directories to the new location
2. Update all import statements across the project to reflect the new paths
3. Preserve any comments and formatting in the updated files

Development

# Clone the repository
git clone https://github.com/your-username/ts-import-move.git
cd ts-import-move

# Install dependencies
pnpm install

# Run in development mode
pnpm dev -- src/file.ts src/newlocation/

# Run tests
pnpm test

How It Works

1. CLI arguments are parsed using commander
2. Source files are resolved using fast-glob (including wildcard patterns)
3. A TypeScript project is initialized using ts-morph with the nearest tsconfig.json
4. Files are moved to their destinations
5. Import paths are automatically updated using the TypeScript AST
6. All modified files are saved, preserving original formatting

License

MIT

Verify everything works after refactoring

npm run build npm test

Cursor AI Integration

ts-import-move includes special rules for the Cursor AI editor to ensure that AI agents always use the tool correctly when refactoring TypeScript code.

Installing Cursor Rules

After installing the package globally, you can install the Cursor rules with either of these commands:

# As a subcommand of ts-import-move
ts-import-move install-rules

# Or using the dedicated command
install-cursor-rules

This adds two rule files to your Cursor rules directory:

• ts-import-move-simple.rules.mdc - Basic rule for direct substitution of mv with ts-import-move
• ts-import-move-advanced.rules.mdc - Advanced rule with detailed mapping of all mv options

What These Rules Do

Cursor rules teach AI assistants how to properly use tools in your TypeScript projects:

1. Simple Rule: Ensures the AI always uses ts-import-move instead of mv when moving TypeScript files, providing basic examples for common operations.

2. Advanced Rule: Provides comprehensive mapping between all Unix mv command options and their ts-import-move equivalents, with examples for complex refactoring operations.

Enabling the Rules in Cursor

There are two ways to enable these rules in Cursor:

Option 1: Add to your project's .cursorrules file

Add one or both rules to your .cursorrules file in your project root:

{
  "rules": [
    "ts-import-move-simple.rules.mdc"
  ]
}

This will automatically apply the rule when Cursor AI reads files in your project.

Option 2: Load via Command Palette

1. Open Cursor AI editor
2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) to open the Command Palette
3. Type "Cursor: Load Rule" and select it
4. Choose either ts-import-move-simple.rules.mdc or ts-import-move-advanced.rules.mdc

Validating the Rules Are Working

Once the rules are installed and enabled, you can verify they're working by:

1. Opening a TypeScript project in Cursor
2. Asking the AI to move a TypeScript file (e.g., "move src/utils/helpers.ts to src/common/helpers.ts")
3. Confirming the AI uses ts-import-move in its response instead of the standard mv command

Troubleshooting Rules Installation

If the rules aren't working as expected:

• Ensure the install-cursor-rules command completed successfully
• Check that your .cursor/rules/ directory contains the rule files
• Verify the rule is correctly referenced in your .cursorrules file
• Try restarting the Cursor application