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):

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

快速路径（使用脚本）：

运行
```
detect.sh
```
分析环境
审查升级建议
运行对应的迁移脚本
处理配置迁移和边界场景
测试与验证

手动路径（仅适用于边界场景）：

复杂的自定义配置
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

Review build scripts

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:

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

顺序很重要：

先升级代码检查/格式化工具（风险最低）
然后升级构建工具
最后升级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

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:

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

用户反馈："ESLint运行一次要30秒"

解决方案：

安装oxlint：
```
npm install -D oxlint
```
将ESLint配置迁移为oxlint兼容规则
更新package.json中的脚本
初期保留ESLint配置作为回退方案
充分测试后移除ESLint

Scenario 2: Slow Vite Build

场景2：Vite构建慢

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

用户反馈："生产环境构建要5分钟"

解决方案：

安装tsdown：
```
npm install -D tsdown
```
创建最简tsdown配置
更新构建脚本
对比tsdown和Vite的构建输出
针对差异调整配置
验证通过后切换到tsdown

Scenario 3: Large Monorepo Type Checking

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

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

用户反馈："我们的Monorepo里tsc --noEmit运行起来没完没了"

解决方案：

安装@typescript/native-preview
先在部分包中测试
测量性能提升
全量推广到整个Monorepo
更新文档

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

只需极少配置
复杂场景可使用
```
tsdown.config.ts
```
配置
支持多入口文件
默认开启Tree-shaking

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

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

可直接替换Prettier使用
支持相同的样式配置选项
速度显著提升
和oxlint规则保持一致

@typescript/native-preview

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

实验性但稳定性良好
仅用于类型检查（不用于代码生成）
增量构建速度更快
监听模式效率极高

Migration Checklist

迁移检查清单

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

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.

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