---
name: build
description: >
  TypeScript to ESM compilation via tsdown with opinionated defaults. Sourcemaps,
  clean dist/, unbundled output, .d.mts types by default, publint publish gate.
  Flags: --no-dts, --bundle, --minify. Default entry src/**/*.ts. Use when
  building a package for publish or generating declarations.
metadata:
  type: core
  library: '@bomb.sh/tools'
  library_version: '0.6.0'
  requires:
    - lifecycle
  sources:
    - 'bombshell-dev/tools:src/commands/build.ts'
---

# Build

Builds TypeScript to ESM using tsdown with opinionated defaults.

## Setup

```sh
pnpm run build
```

## How It Works

`pnpm run build` runs `bsh build` which calls tsdown with:
- **Format:** ESM only
- **Sourcemaps:** enabled
- **Clean:** removes dist/ before building
- **Unbundled** by default (each source file produces one output file)
- **Types:** `.d.mts` declarations generated by default (via tsgo)
- **Entry:** defaults to `src/**/*.ts`
- **Config:** explicitly disabled (`config: false`) — tsdown.config.ts is ignored

## Publish gate

After a successful build, `bsh build` runs **publint** (strict mode) against
the emitted `dist/` and fails the build on errors — broken `exports` targets,
missing declaration files, and invalid `package.json` fields are caught here,
not at publish time. Warnings and suggestions are advisory.

A failed gate after `--no-dts` almost always means `package.json` declares
types that weren't emitted — either rebuild with types (the default) or fix
the `exports` map.

## Flags

Pass flags after `--` in pnpm:

| Flag | Effect |
|------|--------|
| `--no-dts` | Skip `.d.mts` declaration generation (on by default) |
| `--bundle` | Bundle into single output (disables unbundled mode) |
| `--minify` | Minify output |
| positional args | Custom entry points (replaces default `src/**/*.ts`) |

```sh
pnpm run build -- --no-dts
pnpm run build -- --bundle
pnpm run build -- --minify
pnpm run build -- src/index.ts
```

If no entry files match, the build fails with `No entry files matched: …` —
pass explicit entries or check that `src/` exists.

## Common Mistakes

### MEDIUM: Passing unnecessary flags

ESM, sourcemaps, and clean are already defaults. Don't pass them explicitly.

```sh
# Wrong
pnpm run build -- --format esm --sourcemap --clean
```

```sh
# Correct
pnpm run build
```

### HIGH: Running tsdown directly

Always go through the `bsh` wrapper to get correct defaults.

```sh
# Wrong
pnpm exec tsdown src/**/*.ts --format esm
npx tsdown src/**/*.ts
```

```sh
# Correct
pnpm run build
```

### HIGH: CommonJS output configuration

Bombshell is ESM-only. Never configure CJS output.

```sh
# Wrong
pnpm run build -- --format cjs
```

```sh
# Correct — ESM is the only format, no flag needed
pnpm run build
```

## See Also

- `dev/SKILL.md` — Both handle TS compilation in different modes