Agent skill

build-tools

Build tool configuration for tsup, tsx, and bundlers. Use when setting up build pipelines.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/build-tools

SKILL.md

Build Tools Skill

This skill covers build tool configuration for TypeScript projects.

When to Use

Use this skill when:

  • Setting up build pipelines
  • Configuring library bundling
  • Running TypeScript directly
  • Choosing between build tools

Core Principle

RIGHT TOOL FOR THE JOB - Use tsup for libraries, tsx for scripts, Vite for apps.

Tool Selection Guide

Use Case Recommended Tool
Library/Package tsup
CLI Application tsup + tsx
Script Execution tsx
React SPA Vite
Full-Stack App Next.js

tsup - Library Bundler

Installation

bash
npm install -D tsup

Basic Configuration

typescript
// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  splitting: false,
  sourcemap: true,
  minify: false,
  treeshake: true,
});

Package.json for Library

json
{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch"
  }
}

Multiple Entry Points

typescript
// tsup.config.ts
export default defineConfig({
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils/index.ts',
    cli: 'src/cli.ts',
  },
  format: ['esm', 'cjs'],
  dts: true,
});

CLI with Shebang

typescript
// tsup.config.ts
export default defineConfig({
  entry: ['src/cli.ts'],
  format: ['esm'],
  banner: {
    js: '#!/usr/bin/env node',
  },
  clean: true,
});

tsx - TypeScript Execution

Installation

bash
npm install -D tsx

Usage

bash
# Run TypeScript file directly
npx tsx src/script.ts

# Watch mode
npx tsx watch src/server.ts

# With Node.js flags
npx tsx --inspect src/debug.ts

Package.json Scripts

json
{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "start": "tsx src/index.ts",
    "script": "tsx scripts/migrate.ts"
  }
}

tsconfig.json for tsx

json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

TypeScript Compiler (tsc)

Build Only (No Bundling)

json
{
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}
json
{
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch"
  }
}

Vite - Application Bundler

Installation

bash
npm create vite@latest

Configuration

typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    target: 'ES2022',
    sourcemap: true,
    outDir: 'dist',
  },
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

Library Mode

typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'node:path';

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      fileName: 'my-lib',
      formats: ['es', 'cjs'],
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
    },
  },
});

Build Scripts

Complete Build Pipeline

json
{
  "scripts": {
    "prebuild": "npm run clean",
    "build": "tsup",
    "postbuild": "npm run type-check",
    "clean": "rm -rf dist",
    "type-check": "tsc --noEmit"
  }
}

Watch Mode

json
{
  "scripts": {
    "dev": "tsup --watch",
    "dev:run": "tsx watch src/index.ts"
  }
}

Output Formats

ESM (ES Modules)

typescript
// Output: dist/index.js
export function hello() { }

CJS (CommonJS)

typescript
// Output: dist/index.cjs
module.exports.hello = function() { }

Dual Package

typescript
// tsup.config.ts
export default defineConfig({
  format: ['esm', 'cjs'],
  dts: true,
});

Declaration Files

Generate .d.ts

typescript
// tsup.config.ts
export default defineConfig({
  dts: true, // Generate declaration files
});

Separate Declaration Build

json
{
  "scripts": {
    "build": "tsup && tsc --emitDeclarationOnly"
  }
}

Source Maps

typescript
// tsup.config.ts
export default defineConfig({
  sourcemap: true, // Generate source maps
});

Tree Shaking

typescript
// tsup.config.ts
export default defineConfig({
  treeshake: true, // Remove unused code
});

Minification

typescript
// tsup.config.ts
export default defineConfig({
  minify: true, // Minify output (production)
});

External Dependencies

typescript
// tsup.config.ts
export default defineConfig({
  external: ['react', 'react-dom'], // Don't bundle these
});

Best Practices Summary

  1. Use tsup for libraries - Simple, fast, handles dual packages
  2. Use tsx for scripts - Direct execution without build
  3. Use Vite for apps - Fast dev server, optimized builds
  4. Generate type declarations - Always include .d.ts files
  5. Support both ESM and CJS - Dual package format
  6. Enable source maps - For debugging
  7. Tree shake in production - Remove unused code

Code Review Checklist

  • Correct build tool selected for use case
  • tsup.config.ts or vite.config.ts present
  • Declaration files generated (dts: true)
  • Both ESM and CJS formats for libraries
  • Source maps enabled
  • External dependencies configured
  • Clean script removes old builds

Didn't find tool you were looking for?

Be as detailed as possible for better results