inkreach-official-website/apps/website/.agents/skills/ts-library/references/build-tooling.md

Build Tooling

Tool Selection

Tool	Use case
tsdown	Most libraries - fast, simple, modern
unbuild	Complex builds, Nuxt modules, auto-externals
rollup/rolldown	Large projects needing fine control

tsdown (Recommended)

pnpm add -D tsdown

Basic Config

// tsdown.config.ts
import { defineConfig } from 'tsdown'

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

Multiple Entries

export default defineConfig({
  entry: ['src/index.ts', 'src/cli.ts', 'src/utils.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['vue', 'vite'],
})

Plugin Pattern (unplugin-*)

export default defineConfig({
  entry: ['src/*.ts'],          // Glob all entries
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,                // Auto-generate package.json exports
  attw: { profile: 'esm-only' }, // Type checking profile
})

Advanced Options

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: {
    resolve: ['@antfu/utils'],  // Inline specific deps in declarations
  },
  external: ['vue'],
  define: {
    __DEV__: 'false',
  },
  hooks: {
    'build:done': async () => {
      // Post-build tasks
    },
  },
})

unbuild

pnpm add -D unbuild

Basic Config

// build.config.ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index'],
  declaration: true,
  rollup: {
    emitCJS: true,
  },
})

With Externals

export default defineBuildConfig({
  entries: ['src/index', 'src/cli'],
  declaration: true,
  externals: ['vue', 'vite'],
  rollup: {
    emitCJS: true,
    inlineDependencies: true,
    dts: { respectExternal: true },
  },
})

Output Formats

ESM Only (modern)

export default defineConfig({
  format: ['esm'],
})

Dual CJS/ESM (recommended)

export default defineConfig({
  format: ['esm', 'cjs'],
})

With IIFE for CDN

export default defineConfig([
  { format: ['esm', 'cjs'], dts: true },
  { format: 'iife', globalName: 'MyLib', minify: true },
])

Define Flags

Common compile-time flags:

export default defineConfig({
  define: {
    __DEV__: `(process.env.NODE_ENV !== 'production')`,
    __TEST__: 'false',
    __BROWSER__: 'true',
    __VERSION__: JSON.stringify(pkg.version),
  },
})

Build Scripts

{
  "scripts": {
    "build": "tsdown",
    "dev": "tsdown --watch",
    "prepublishOnly": "pnpm build"
  }
}

Troubleshooting

CJS default export issues

Some bundlers need explicit default:

export default defineConfig({
  hooks: {
    'build:done': async () => {
      // Patch CJS files if needed
    },
  },
})

Missing types in output

Ensure dts: true and check isolatedDeclarations in tsconfig.

External not working

Check package is in peerDependencies and listed in external.