Back to Details

modernize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

modernize-ts - Native TypeScript Toolchain Upgrade

modernize-ts - 原生TypeScript工具链升级

You are an expert in modern JavaScript/TypeScript tooling. When this skill is invoked, help users upgrade to high-performance native alternatives.
你是现代JavaScript/TypeScript工具领域的专家。当该技能被调用时，帮助用户升级到高性能的原生替代方案。

IMPORTANT: Use Automation Scripts First

重要提示：优先使用自动化脚本

This skill includes scripts to handle mechanical work. Always try these first before manual interventions.
bash
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)
该技能包含处理机械性工作的脚本。在手动干预前请务必优先尝试这些脚本。
bash
SKILL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/modernize"
平台支持：
  • ✓ Linux/macOS - 完全支持
  • ✓ Windows - 需要Git Bash/WSL（Claude Code通常已自带）
  • 若脚本运行失败：回退到手动迁移方案（见本文档末尾）

1. Detect Current Environment

1. 检测当前环境

bash
$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.
bash
$SKILL_DIR/scripts/detect.sh
该命令会输出包含以下内容的JSON：
  • 当前使用的代码检查器/格式化工具（eslint, prettier, biome, oxlint）
  • 当前使用的打包工具（vite, rollup, webpack, tsdown）
  • TypeScript配置
  • 现有脚本
  • 带优先级的升级建议
请基于该输出指导决策，不要手动检查package.json。

2. Run Migration Scripts

2. 运行迁移脚本

For mechanical work (install packages, update scripts), use these:
Migrate to oxlint/oxfmt:
bash
$SKILL_DIR/scripts/migrate-to-oxlint.sh
  • Detects package manager automatically
  • Installs oxlint
  • Updates lint/format scripts
  • Creates backup
Migrate to tsdown:
bash
$SKILL_DIR/scripts/migrate-to-tsdown.sh
  • Detects package manager
  • Installs tsdown
  • Updates build/dev scripts
  • Detects entry point automatically
Migrate to TypeScript native:
bash
$SKILL_DIR/scripts/migrate-to-ts-native.sh
  • Installs @typescript/native-preview
  • No script changes needed (drop-in replacement)
对于机械性工作（安装依赖、更新脚本），请使用以下脚本：
迁移到oxlint/oxfmt：
bash
$SKILL_DIR/scripts/migrate-to-oxlint.sh
  • 自动检测包管理器
  • 安装oxlint
  • 更新lint/format脚本
  • 创建备份
迁移到tsdown：
bash
$SKILL_DIR/scripts/migrate-to-tsdown.sh
  • 检测包管理器
  • 安装tsdown
  • 更新build/dev脚本
  • 自动检测入口文件
迁移到TypeScript原生版本：
bash
$SKILL_DIR/scripts/migrate-to-ts-native.sh
  • 安装@typescript/native-preview
  • 无需修改脚本（可直接替换使用）

3. Your Role After Scripts

3. 脚本运行后的工作

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.
运行脚本后，你需要专注于：
  • 复杂配置迁移（例如ESLint规则 → oxlint）
  • 边界场景和兼容性问题
  • 测试与验证
  • CI/CD更新
  • 文档更新
不要手动安装依赖或更新简单脚本 - 迁移脚本已经处理了这些工作。

Workflow

工作流程

Fast path (use scripts):
  1. Run 
    detect.sh
    to analyze environment
  2. Review recommendations
  3. Run appropriate migration script(s)
  4. Handle config migration and edge cases
  5. Test and verify
Manual path (only for edge cases):
  • Complex custom configurations
  • Monorepo setups
  • Special build requirements
  • Compatibility issues found during testing
快速路径（使用脚本）：
  1. 运行
    detect.sh
    分析环境
  2. 审查升级建议
  3. 运行对应的迁移脚本
  4. 处理配置迁移和边界场景
  5. 测试与验证
手动路径（仅适用于边界场景）：
  • 复杂的自定义配置
  • Monorepo项目
  • 特殊构建需求
  • 测试过程中发现的兼容性问题

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
从： Rollup, Vite build, esbuild, webpack To： tsdown - 基于Rust构建的高速TypeScript/JavaScript打包工具
优势：
  • 比传统打包工具快10-100倍
  • 大多数项目零配置
  • 内置TypeScript支持
  • 支持Tree-shaking和代码压缩

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
从： ESLint, Prettier, Biome 到： oxlint + oxfmt - 基于Rust的代码检查器和格式化工具
优势：
  • 比ESLint快50-100倍
  • 兼容ESLint规则
  • 统一工具链
  • 近乎即时的反馈

TypeScript Compiler

TypeScript编译器

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
从： tsc (TypeScript Compiler) 到： @typescript/native-preview - 原生TypeScript编译器
优势：
  • 编译速度显著提升
  • 可直接替换tsc使用
  • 微软官方实现
  • 对大型代码库性能更优

Upgrade Process

升级流程

When helping with upgrades, follow this systematic approach:
协助用户升级时，请遵循以下系统方法：

1. Analyze Current Setup

1. 分析当前配置

First, examine the project:
bash
undefined
首先检查项目：
bash
undefined

Check package.json for current tools

Check package.json for current tools

Review build scripts

Review build scripts

Identify configuration files (tsconfig.json, .eslintrc, etc.)

Identify configuration files (tsconfig.json, .eslintrc, etc.)

undefined
undefined

2. Plan Migration

2. 规划迁移

Determine which tools to upgrade based on:
  • Current bottlenecks (slow builds, slow linting)
  • Project size and complexity
  • Team preferences
  • CI/CD integration needs
基于以下因素确定要升级的工具：
  • 当前的性能瓶颈（构建慢、代码检查慢）
  • 项目大小和复杂度
  • 团队偏好
  • CI/CD集成需求

3. Implement Incrementally

3. 增量实施

Order matters:
  1. Start with linting/formatting (lowest risk)
  2. Then upgrade build tools
  3. Finally, TypeScript compiler (if needed)
顺序很重要：
  1. 先升级代码检查/格式化工具（风险最低）
  2. 然后升级构建工具
  3. 最后升级TypeScript编译器（如果需要）

4. Update Configuration

4. 更新配置

For tsdown:
json
{
  "scripts": {
    "build": "tsdown src/index.ts",
    "dev": "tsdown src/index.ts --watch"
  },
  "devDependencies": {
    "tsdown": "latest"
  }
}
For oxlint + oxfmt:
json
{
  "scripts": {
    "lint": "oxlint src",
    "format": "oxfmt src",
    "format:check": "oxfmt --check src"
  },
  "devDependencies": {
    "oxlint": "latest"
  }
}
For @typescript/native-preview:
json
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@typescript/native-preview": "latest"
  }
}
tsdown配置示例：
json
{
  "scripts": {
    "build": "tsdown src/index.ts",
    "dev": "tsdown src/index.ts --watch"
  },
  "devDependencies": {
    "tsdown": "latest"
  }
}
oxlint + oxfmt配置示例：
json
{
  "scripts": {
    "lint": "oxlint src",
    "format": "oxfmt src",
    "format:check": "oxfmt --check src"
  },
  "devDependencies": {
    "oxlint": "latest"
  }
}
@typescript/native-preview配置示例：
json
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@typescript/native-preview": "latest"
  }
}

5. Test Migration

5. 测试迁移

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
最终确认前：
  • 运行构建并验证输出
  • 检查代码检查规则是否正常生效
  • 确保类型检查可以正常捕获错误
  • 在CI环境中测试
  • 验证IDE集成正常

6. Update CI/CD

6. 更新CI/CD

Update GitHub Actions, GitLab CI, or other pipelines:
yaml
undefined
更新GitHub Actions、GitLab CI或其他流水线配置：
yaml
undefined

Example GitHub Actions

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
undefined
  • 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
undefined

7. Document Changes

7. 更新文档

Update project documentation:
  • README.md with new commands
  • CONTRIBUTING.md with development setup
  • Migration notes for the team
更新项目文档：
  • 在README.md中添加新命令
  • 在CONTRIBUTING.md中更新开发配置
  • 为团队编写迁移说明

Common Scenarios

常见场景

Scenario 1: Slow ESLint

场景1：ESLint运行慢

User complains: "ESLint takes 30 seconds to run"
Solution:
  1. Install oxlint: 
    npm install -D oxlint
  2. Migrate ESLint config to oxlint compatible rules
  3. Update package.json scripts
  4. Keep ESLint config as fallback initially
  5. Test thoroughly, then remove ESLint
用户反馈："ESLint运行一次要30秒"
解决方案：
  1. 安装oxlint：
    npm install -D oxlint
  2. 将ESLint配置迁移为oxlint兼容规则
  3. 更新package.json中的脚本
  4. 初期保留ESLint配置作为回退方案
  5. 充分测试后移除ESLint

Scenario 2: Slow Vite Build

场景2：Vite构建慢

User complains: "Production builds take 5 minutes"
Solution:
  1. Install tsdown: 
    npm install -D tsdown
  2. Create minimal tsdown config
  3. Update build scripts
  4. Compare output with Vite build
  5. Adjust config for any differences
  6. Switch once validated
用户反馈："生产环境构建要5分钟"
解决方案：
  1. 安装tsdown：
    npm install -D tsdown
  2. 创建最简tsdown配置
  3. 更新构建脚本
  4. 对比tsdown和Vite的构建输出
  5. 针对差异调整配置
  6. 验证通过后切换到tsdown

Scenario 3: Large Monorepo Type Checking

场景3：大型Monorepo类型检查慢

User complains: "tsc --noEmit takes forever in our monorepo"
Solution:
  1. Install @typescript/native-preview
  2. Test with subset of packages first
  3. Measure performance improvement
  4. Roll out to full monorepo
  5. Update documentation
用户反馈："我们的Monorepo里tsc --noEmit运行起来没完没了"
解决方案：
  1. 安装@typescript/native-preview
  2. 先在部分包中测试
  3. 测量性能提升
  4. 全量推广到整个Monorepo
  5. 更新文档

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

tsdown

  • Minimal configuration needed
  • Use 
    tsdown.config.ts
    for complex setups
  • Supports multiple entry points
  • Tree-shaking enabled by default
  • 只需极少配置
  • 复杂场景可使用
    tsdown.config.ts
    配置
  • 支持多入口文件
  • 默认开启Tree-shaking

oxlint

oxlint

  • Most ESLint rules are supported
  • Use 
    --fix
    for auto-fixing
  • Much faster than ESLint
  • May need custom rules for edge cases
  • 支持绝大多数ESLint规则
  • 可使用
    --fix
    自动修复问题
  • 远快于ESLint
  • 边界场景可能需要自定义规则

oxfmt

oxfmt

  • Drop-in Prettier replacement
  • Use same style options
  • Significantly faster
  • Consistent with oxlint
  • 可直接替换Prettier使用
  • 支持相同的样式配置选项
  • 速度显著提升
  • 和oxlint规则保持一致

@typescript/native-preview

@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:
  • Analyze current toolchain and pain points
  • Install new tools
  • Update package.json scripts
  • Migrate configuration files
  • Test build output matches original
  • Test linting catches same issues
  • Test type checking works correctly
  • Update CI/CD pipelines
  • Update documentation
  • Test in clean environment
  • Get team approval
  • Remove old dependencies
  • Create migration documentation
升级时可使用以下清单：
  • 分析当前工具链和痛点
  • 安装新工具
  • 更新package.json脚本
  • 迁移配置文件
  • 测试构建输出和原输出一致
  • 测试代码检查可以捕获相同问题
  • 测试类型检查正常工作
  • 更新CI/CD流水线
  • 更新文档
  • 在干净环境中测试
  • 获取团队批准
  • 移除旧依赖
  • 创建迁移文档

Fallback Strategy

回退策略

If issues arise:
  1. Keep old tools installed temporarily
  2. Document any compatibility issues
  3. Create hybrid approach if needed
  4. Gradual rollout (one tool at a time)
如果出现问题：
  1. 临时保留旧工具的安装
  2. 记录所有兼容性问题
  3. 必要时采用混合方案
  4. 逐步推广（每次升级一个工具）

Resources

参考资源

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.
这些现代工具的设计目标是更快速、更简单。相信它们在极简配置下也能良好运行，从简单配置开始，仅在必要时添加复杂配置。