modernize-ts - Native TypeScript Toolchain Upgrade

You are an expert in modern JavaScript/TypeScript tooling. When this skill is invoked, help users upgrade to high-performance native alternatives.

IMPORTANT: Use Automation Scripts First

This skill includes scripts to handle mechanical work. Always try these first before manual interventions.

SKILL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/modernize"

Platform Support:

✓ Linux/macOS - Full support
✓ Windows - Requires Git Bash/WSL (usually available with Claude Code)
If scripts fail: Fall back to manual migration (see bottom of this document)

1. Detect Current Environment

$SKILL_DIR/scripts/detect.sh

This outputs JSON with:

Current linters/formatters (eslint, prettier, biome, oxlint)
Current bundlers (vite, rollup, webpack, tsdown)
TypeScript setup
Existing scripts
Upgrade recommendations with priorities

Use this output to guide decisions. Don't manually check package.json.

2. Run Migration Scripts

For mechanical work (install packages, update scripts), use these:

Migrate to oxlint/oxfmt:

$SKILL_DIR/scripts/migrate-to-oxlint.sh

Detects package manager automatically
Installs oxlint
Updates lint/format scripts
Creates backup

Migrate to tsdown:

$SKILL_DIR/scripts/migrate-to-tsdown.sh

Detects package manager
Installs tsdown
Updates build/dev scripts
Detects entry point automatically

Migrate to TypeScript native:

$SKILL_DIR/scripts/migrate-to-ts-native.sh

Installs @typescript/native-preview
No script changes needed (drop-in replacement)

3. Your Role After Scripts

After running scripts, focus on:

Complex configuration migration (e.g., ESLint rules → oxlint)
Edge cases and compatibility issues
Testing and verification
CI/CD updates
Documentation

Don't manually install packages or update simple scripts - the migration scripts handle that.

Workflow

Fast path (use scripts):

Run detect.sh to analyze environment
Review recommendations
Run appropriate migration script(s)
Handle config migration and edge cases
Test and verify

Manual path (only for edge cases):

Complex custom configurations
Monorepo setups
Special build requirements
Compatibility issues found during testing

Migration Paths

Build Tools

From: Rollup, Vite build, esbuild, webpack To: tsdown - Fast TypeScript/JavaScript bundler built with Rust

Benefits:

10-100x faster than traditional bundlers
Zero config for most projects
Built-in TypeScript support
Tree-shaking and minification

Linting & Formatting

From: ESLint, Prettier, Biome To: oxlint + oxfmt - Rust-based linter and formatter

Benefits:

50-100x faster than ESLint
Compatible with ESLint rules
Unified toolchain
Near-instant feedback

TypeScript Compiler

From: tsc (TypeScript Compiler) To: @typescript/native-preview - Native TypeScript compiler

Benefits:

Significantly faster compilation
Drop-in replacement for tsc
Official Microsoft implementation
Better performance for large codebases

Upgrade Process

When helping with upgrades, follow this systematic approach:

1. Analyze Current Setup

First, examine the project:

# Check package.json for current tools
# Review build scripts
# Identify configuration files (tsconfig.json, .eslintrc, etc.)

2. Plan Migration

Determine which tools to upgrade based on:

Current bottlenecks (slow builds, slow linting)
Project size and complexity
Team preferences
CI/CD integration needs

3. Implement Incrementally

Order matters:

Start with linting/formatting (lowest risk)
Then upgrade build tools
Finally, TypeScript compiler (if needed)

4. Update Configuration

For tsdown:

{
  "scripts": {
    "build": "tsdown src/index.ts",
    "dev": "tsdown src/index.ts --watch"
  },
  "devDependencies": {
    "tsdown": "latest"
  }
}

For oxlint + oxfmt:

{
  "scripts": {
    "lint": "oxlint src",
    "format": "oxfmt src",
    "format:check": "oxfmt --check src"
  },
  "devDependencies": {
    "oxlint": "latest"
  }
}

For @typescript/native-preview:

{
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@typescript/native-preview": "latest"
  }
}

5. Test Migration

Before finalizing:

Run the build and verify output
Check that linting rules still work
Ensure type checking catches errors
Test in CI environment
Verify IDE integration

6. Update CI/CD

Update GitHub Actions, GitLab CI, or other pipelines:

# Example GitHub Actions
- name: Install dependencies
  run: npm install

- name: Lint
  run: npm run lint

- name: Format check
  run: npm run format:check

- name: Build
  run: npm run build

- name: Type check
  run: npm run typecheck

7. Document Changes

Update project documentation:

README.md with new commands
CONTRIBUTING.md with development setup
Migration notes for the team

Common Scenarios

Scenario 1: Slow ESLint

User complains: "ESLint takes 30 seconds to run"

Solution:

Install oxlint: npm install -D oxlint
Migrate ESLint config to oxlint compatible rules
Update package.json scripts
Keep ESLint config as fallback initially
Test thoroughly, then remove ESLint

Scenario 2: Slow Vite Build

User complains: "Production builds take 5 minutes"

Solution:

Install tsdown: npm install -D tsdown
Create minimal tsdown config
Update build scripts
Compare output with Vite build
Adjust config for any differences
Switch once validated

Scenario 3: Large Monorepo Type Checking

User complains: "tsc --noEmit takes forever in our monorepo"

Solution:

Install @typescript/native-preview
Test with subset of packages first
Measure performance improvement
Roll out to full monorepo
Update documentation

Important Notes

Preserve Existing Configs Initially: Keep old configs commented out during migration
Test Incrementally: Don't upgrade everything at once
Measure Performance: Benchmark before/after to show improvements
Check Compatibility: Ensure editor plugins and tools work with new toolchain
Team Communication: Explain changes and new workflows to the team

Tool-Specific Tips

tsdown

Minimal configuration needed
Use tsdown.config.ts for complex setups
Supports multiple entry points
Tree-shaking enabled by default

oxlint

Most ESLint rules are supported
Use --fix for auto-fixing
Much faster than ESLint
May need custom rules for edge cases

oxfmt

Drop-in Prettier replacement
Use same style options
Significantly faster
Consistent with oxlint

@typescript/native-preview

Experimental but stable
Use for type checking only (not emit)
Faster incremental builds
Watch mode is very efficient

Migration Checklist

Use this checklist when upgrading:

Fallback Strategy

If issues arise:

Keep old tools installed temporarily
Document any compatibility issues
Create hybrid approach if needed
Gradual rollout (one tool at a time)

Resources

tsdown: https://github.com/egoist/tsdown
Oxc (oxlint/oxfmt): https://oxc.rs/
@typescript/native-preview: https://github.com/microsoft/TypeScript/tree/main/packages/native-preview

Philosophy

These modern tools are designed to be faster and simpler. Trust them to work well with minimal configuration. Start simple, add complexity only when needed.