Migrate any TypeScript Library to the Void Zero Toolchain using an AI agent

AI_Agent_migrate_to_void_Zero_Toolchain.md

🤖 AI Agent Instructions: Migrate TypeScript Library to Void Zero Toolchain

Agent Role: You are tasked with migrating any TypeScript library from its current build system to the high-performance Void Zero toolchain. Follow these instructions systematically.

🎯 Mission Overview

Transform any TypeScript library (regardless of current setup) to use:

• TSDown for both JavaScript bundling AND TypeScript declarations (primary approach)
• Oxlint for linting (optional, can keep existing)
• Vitest for testing (optional, can keep existing)
• Rolldown as advanced fallback for complex bundling needs (optional)
• Vite as legacy fallback build option (optional)

Expected Performance: 5-10x faster builds (guaranteed), 100x faster linting (if migrating to Oxlint), framework-compatible output.

Key Insight: For TypeScript libraries, TSDown can handle both bundling and declarations in one tool, eliminating the need for separate bundler configurations!

❓ Pre-Migration Analysis & Questions

Agent Instructions: First analyze the project structure to infer answers, then confirm with the user:

🔍 STEP 0: Auto-Analysis

Agent Task: Analyze the project before asking questions. Infer these automatically:

# Detect entry points
find . -name "index.ts" -o -name "index.js" | head -5
ls -la src/ lib/ 2>/dev/null || echo "No src/lib found"

# Detect source structure
[ -d "src" ] && echo "Source: src/" || [ -d "lib" ] && echo "Source: lib/" || echo "Source: root level"

# Detect current tools
grep -E "(webpack|rollup|esbuild|jest|eslint|babel)" package.json | head -10

# Detect framework
grep -E "(react|vue|svelte)" package.json | head -5

# Detect test files
find . -name "*.test.*" -o -name "*.spec.*" | head -3

# Check for multiple exports
grep -E "(exports|main|module)" package.json

🤖 Smart Questions (Ask only what you can't infer)

Format: "I detected [INFERENCE], is this correct? If not, please clarify:"

1. Entry Point: "I found these potential entry points: [detected files]. Main entry appears to be [best guess] - correct?"

2. Source Directory: "Source code appears to be in [detected directory] - is this right?"

3. Current Tools: "I detected you're using [found tools] for building/testing/linting - accurate?"

4. Framework Type: "Based on dependencies, this appears to be a [React/Vue/vanilla/other] library - correct?"

5. Multiple Exports: "Package.json suggests [single/multiple] export structure - is this right?"

🎯 Clarification Questions (Only ask if analysis is unclear)

6. External Dependencies: "Should these dependencies stay external (not bundled)? [list from peerDependencies + common libs]"

7. Migration Scope: "Do you want to migrate just the build system, or also linting/testing to Void Zero tools?"

8. Output Formats: "I see you currently output [detected formats] - keep both ESM and CJS?"

9. Special Build Steps: "I noticed [custom scripts/configs] - any special build requirements I should preserve?"

10. Breaking Changes: "This migration may change your build scripts - are you okay with that?"

Agent Decision Matrix Based on Analysis + Answers:

• Always migrate: TSDown (build + types) - single tool for everything!
• Auto-configure: Entry points (Q1), source paths (Q2), externals (Q6), output formats (Q8)
• Conditionally migrate: Oxlint (based on Q7), Vitest (based on Q7)
• Advanced needs only: Rolldown (complex bundling), Vite (legacy fallback)
• Preserve existing: Custom build steps (Q9), existing tools (if user prefers in Q7)

📋 Step-by-Step Agent Instructions

STEP 1: Analyze Current Setup 🔍

Task: Examine the existing project structure and identify what needs to be replaced (this should build on your STEP 0 auto-analysis).

Actions:

1. Verify auto-analysis findings with the user using smart questions above

2. Document current setup based on analysis + user confirmation:

   • Entry point: [confirmed path]
   • Source directory: [confirmed directory]
   • Current bundler: [detected tool]
   • Current linter: [detected tool or none]
   • Current test framework: [detected tool or none]
   • Framework type: [React/Vue/vanilla/other]
   • External dependencies: [from peerDependencies + user input]

3. Plan replacement strategy:

   • webpack.config.js → Replace with Rolldown
   • rollup.config.js → Replace with Rolldown
   • esbuild.config.js → Replace with Rolldown
   • .eslintrc.* → Replace with Oxlint (if user agrees)
   • jest.config.* → Replace with Vitest (if user agrees)
   • babel.config.* → Remove (Rolldown handles transpilation)
   • Multiple tsconfig.*.json → Simplify to one
   • Build scripts in /scripts/ → Replace with simple npm scripts

Expected Output: Clear migration plan based on actual project structure rather than assumptions.

STEP 2: Install Void Zero Dependencies 📦

Task: Replace old dependencies with Void Zero ecosystem (install only what you need).

Actions:

1. Remove old dependencies (only uninstall what exists in the current project):

# Check package.json first, then remove only existing bundlers
npm uninstall -D webpack webpack-cli webpack-dev-server || true
npm uninstall -D rollup @rollup/plugin-* || true
npm uninstall -D esbuild || true
npm uninstall -D parcel || true

# Remove existing linters only if found
npm uninstall -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin || true
npm uninstall -D eslint-plugin-* || true

# Remove existing test runners only if found
npm uninstall -D jest @types/jest ts-jest || true
npm uninstall -D mocha @types/mocha || true

# Remove transpilation tools only if found
npm uninstall -D babel-core @babel/core @babel/preset-* || true
npm uninstall -D swc @swc/core || true

2. Install Void Zero tools (TSDown-first approach):

# Core essentials (always install - TSDown handles both JS and types!)
npm install -D tsdown@^0.14.1
npm install -D typescript@^5.8.3

# Choose linting approach:
npm install -D oxlint@^1.11.2  # OR keep existing ESLint setup

# Choose testing approach:
npm install -D vitest@^3.2.4   # OR keep existing test framework

# Advanced bundling (only if TSDown isn't sufficient):
npm install -D rolldown@^1.0.0-beta.32

# Legacy fallback build (install if complex build needs):
npm install -D vite@^6.0.0 vite-plugin-dts@^4.3.0

# Utilities (install if needed):
npm install -D rimraf@^6.0.1 @types/node@^24.0.10

STEP 3: Create Core Configuration Files 📝

Task: Create the essential configuration (TSDown-first approach for libraries).

Action 3A: Create tsdown.config.js (Primary build - handles both JS and types!)

// TSDown can handle both bundling and declarations for libraries
export default {
  entry: "src/index.ts", // Adjust based on your project structure
  outDir: "dist",
  format: ["esm", "cjs"], // Outputs both ES modules and CommonJS
  dts: true, // Generate TypeScript declarations
  sourcemap: true,
  external: [], // Add external dependencies here (will be updated in Step 8)
  clean: true,
};

Action 3B: Create rolldown.config.js (Only if you need advanced bundling features)

// Only create this if TSDown doesn't meet your complex bundling needs
export default {
  input: "src/index.ts", // Common alternatives: "lib/index.ts", "index.ts"
  output: [
    {
      file: "dist/esm/index.js",
      format: "esm",
      sourcemap: true,
    },
    {
      file: "dist/cjs/index.cjs",
      format: "cjs",
      sourcemap: true,
    },
  ],
  external: [], // Add external dependencies here
};

Action 3C: Create oxlint.json (only if migrating from ESLint)

{
  "rules": {}
}

Action 3D: Create vite.config.ts (only if you need legacy fallback build)

import { defineConfig } from "vite";
import dts from "vite-plugin-dts";

export default defineConfig({
  plugins: [
    dts({
      outDir: "dist/types",
      include: ["src/**/*"], // Adjust path if needed: ["lib/**/*"], etc.
      exclude: ["**/*.test.ts", "**/*.spec.ts"],
    }),
  ],
  build: {
    lib: {
      entry: "src/index.ts", // Adjust to match your entry point
      formats: ["es", "cjs"],
      fileName: (format) =>
        format === "es" ? "esm/index.js" : "cjs/index.cjs",
    },
    minify: false, // Libraries should not be minified
    target: "esnext",
    rollupOptions: {
      output: {
        compact: false, // Clean output for frameworks
      },
    },
  },
});

STEP 4: Update TypeScript Configuration 🔧

Task: Simplify TypeScript setup to one modern config.

Actions:

1. Remove old tsconfig files: tsconfig.*.json (except main one)
2. Replace tsconfig.json content with:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src/**/*", "vite.config.ts"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

STEP 5: Transform Package.json 📋

Task: Update package.json to use Void Zero toolchain.

Action 5A: Replace scripts section (TSDown-first approach):

{
  "scripts": {
    "clean": "rimraf dist", // OR "rm -rf dist" if rimraf not installed
    "build": "tsdown", // Single command builds both JS and types!
    "build:rolldown": "rolldown -c rolldown.config.js", // Only if using Rolldown
    "build:vite": "npm run clean && vite build", // Legacy fallback
    "lint": "oxlint", // OR keep your existing linter: "eslint src"
    "lint:fix": "oxlint --fix", // OR "eslint src --fix"
    "test": "vitest run", // OR keep existing: "jest", "mocha", etc.
    "test:watch": "vitest", // OR existing watch command
    "prepublishOnly": "npm run build"
  }
}

Action 5B: Update/add package configuration fields (TSDown output structure):

{
  "type": "module",
  "main": "./dist/index.cjs", // TSDown output structure
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "sideEffects": false,
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist"]
}

STEP 6: Handle Test Files 🧪

Task: Migrate tests to Vitest (optional - you can keep existing test setup).

Actions (only if migrating to Vitest):

1. Find test files: Look for *.test.*, *.spec.*, /test/, /__tests__/
2. Update imports (if migrating from Jest):
   • Change import { describe, it, expect } from 'jest'
   • To import { describe, it, expect } from 'vitest'
3. Remove old test configs: jest.config.*, .mocharc.* (if migrating)
4. Create vitest.config.ts only if you have complex testing needs:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node", // or "jsdom" for browser-like tests
  },
});

Note: You can keep your existing test setup (Jest, Mocha, etc.) and only migrate the build system.

STEP 7: Clean Up Legacy Files 🗑️

Task: Remove obsolete configuration and build files (only remove what exists).

Actions - Check and remove these files if they exist:

# Remove old bundler configs (check first)
[ -f webpack.config.js ] && rm webpack.config.js
[ -f rollup.config.js ] && rm rollup.config.js
[ -f esbuild.config.js ] && rm esbuild.config.js
[ -f parcel.config.js ] && rm parcel.config.js

# Remove old linter configs (only if migrating to Oxlint)
[ -f .eslintrc.js ] && rm .eslintrc.js
[ -f .eslintrc.json ] && rm .eslintrc.json
[ -f .eslintrc.yml ] && rm .eslintrc.yml

# Remove old test configs (only if migrating to Vitest)
[ -f jest.config.js ] && rm jest.config.js
[ -f jest.config.json ] && rm jest.config.json
[ -f .mocharc.json ] && rm .mocharc.json

# Remove transpilation configs (check first)
[ -f babel.config.js ] && rm babel.config.js
[ -f .babelrc ] && rm .babelrc
[ -f .swcrc ] && rm .swcrc

# Remove multiple tsconfig files (keep main tsconfig.json)
[ -f tsconfig.cjs.json ] && rm tsconfig.cjs.json
[ -f tsconfig.esm.json ] && rm tsconfig.esm.json
[ -f tsconfig.types.json ] && rm tsconfig.types.json

# Remove build scripts directory (only if it contains build scripts)
[ -d scripts ] && [ "$(ls -A scripts)" ] && echo "Check scripts/ directory manually"

# Remove old package files
rm -f *.tgz

STEP 8: Handle External Dependencies 🔗

Task: Configure external dependencies for the bundler.

Actions:

1. Read package.json dependencies and peerDependencies
2. Add them to rolldown.config.js external array:

external: ["react", "react-dom", "lodash"]; // Example

3. Rule: Never bundle dependencies that consumers should provide

STEP 9: Test Migration ✅

Task: Verify everything works correctly.

Actions:

# Test build (core requirement)
npm run build

# Test linting (if migrated to Oxlint)
npm run lint

# Test tests (with existing or new test framework)
npm test

# Create test package
npm pack

Expected Results:

• Build completes in <1 second (major improvement)
• Single tsdown command handles everything!
• Linting completes in <50ms (if using Oxlint)
• All tests pass (with existing or migrated test framework)
• Package creates successfully
• Output structure (TSDown approach):

dist/
├── index.js (ESM)
├── index.cjs (CommonJS)
├── index.d.ts (TypeScript declarations)
└── *.map files (sourcemaps)

STEP 10: Validate Framework Compatibility 🎯

Task: Ensure the package works across different frameworks.

Actions:

1. Check that dist/ contains both .d.ts AND .js/.cjs files
2. Verify package.json has proper exports field
3. Test import in a simple test file:

// Test ESM
import { yourFunction } from "./package-name";

// Test CJS
const { yourFunction } = require("./package-name");

// Test CJS const { yourFunction } = require("./package-name");

## 🚨 Common Edge Cases to Handle

### Multiple Entry Points

If the library has multiple exports, update configs:

```javascript
// rolldown.config.js
export default [
  { input: 'src/index.ts', output: [...] },
  { input: 'src/utils.ts', output: [...] }
]

React/Vue Libraries

Add JSX/Vue support:

// rolldown.config.js
export default {
  // ... other config
  plugins: [
    // Add react() or vue() plugin if needed
  ],
};

Complex Directory Structure

If src files are not in /src/, adjust all config file paths accordingly.

Monorepo Setup

Apply this migration to each package individually, not at the root level.

🎯 Success Criteria

The migration is complete when:

• ✅ Build time reduced by 5-10x (core requirement)
• ✅ TSDown successfully handles both bundling AND declarations (primary goal)
• ✅ Package exports both ESM and CJS
• ✅ Single npm run build command works
• ✅ No old bundler tools remain
• ✅ All tests pass (regardless of test framework)
• ✅ Package size optimized
• ✅ Framework compatibility verified

Optional completions (depending on what you migrated):

• ✅ Linting time reduced by 100x (if migrated to Oxlint)
• ✅ Test performance improved (if migrated to Vitest)
• ✅ Rolldown available for advanced bundling needs (if installed)

🎯 Using Auto-Analysis + User Confirmation

Agent Reference: Use the auto-detected information + user confirmations to customize the migration:

Path Configuration (Based on Auto-Detection + Q1-2)

// tsdown.config.js - use confirmed paths (primary approach)
export default {
  entry: "[detected/confirmed entry point]", // e.g., "src/index.ts"
  outDir: "dist",
  format: ["esm", "cjs"],
  dts: true,
  // For multiple exports (detected in analysis), specify multiple entries
  // entry: ["src/index.ts", "src/utils.ts"]
};

// rolldown.config.js - only if TSDown isn't sufficient
export default {
  input: "[detected/confirmed entry point]", // e.g., "src/index.ts"
  // For multiple exports (detected in analysis), create array of configs
  // input: ["src/index.ts", "src/utils.ts"]
};

Framework Support (Based on Auto-Detection + Q4)

// If React/Vue library detected, add to tsdown.config.js:
export default {
  entry: "src/index.ts",
  outDir: "dist",
  format: ["esm", "cjs"],
  dts: true,
  esbuildOptions: {
    jsx: "automatic", // For React
    // or configure for Vue/Svelte
  },
};

// OR for complex cases, use rolldown.config.js:
import react from "@rolldown/plugin-react";
import vue from "@rolldown/plugin-vue";

export default {
  plugins: [react()], // Add appropriate plugin based on detection
  // ...
};

External Dependencies (Based on Auto-Detection + Q6)

// tsdown.config.js - use detected peerDependencies + user confirmation
export default {
  entry: "src/index.ts",
  outDir: "dist",
  format: ["esm", "cjs"],
  dts: true,
  external: ["react", "react-dom", "vue"], // From peerDeps + user input
};

Conditional Script Generation (Based on Q7)

// package.json scripts - TSDown-first approach
{
  "scripts": {
    "build": "tsdown", // Primary: single command for everything!
    "build:rolldown": "rolldown -c", // Only if using Rolldown for complex needs
    "lint": "oxlint", // If user chose to migrate linting
    "test": "vitest run" // If user chose to migrate testing
    // Otherwise keep existing: "eslint src", "jest", etc.
  }
}

🔄 Final Output Structure

Every migrated library should have (TSDown-first approach):

├── src/                    # Source code (unchanged location may vary)
├── dist/                   # Generated by TSDown
│   ├── index.js           # ES modules
│   ├── index.cjs          # CommonJS
│   ├── index.d.ts         # TypeScript declarations
│   └── *.map              # Sourcemaps
├── package.json           # Updated configuration
├── tsconfig.json          # Simplified TypeScript config
├── tsdown.config.js       # Primary build config (TSDown)
├── rolldown.config.js     # Advanced build config (optional)
├── vite.config.ts         # Legacy fallback build config (optional)
├── oxlint.json           # Linting config (optional)
└── README.md             # Updated documentation

---

Agent Note: This migration should work for ANY TypeScript library regardless of its current setup. The key principle is:

1. Always install: TSDown + TypeScript (TSDown handles both bundling AND declarations!)
2. Optionally install: Oxlint (linting), Vitest (testing), Rolldown (complex bundling), Vite (legacy fallback)
3. Adapt paths: Check actual entry points (src/, lib/, index.ts, etc.)
4. Preserve choices: Keep existing test/lint setups if preferred
5. Remove safely: Only delete files that actually exist

Focus on the TSDown-first transformation for libraries - it's simpler and handles both JS bundling and TypeScript declarations in one tool!