npm Package Development (Bun-First)

Build and publish npm packages using Bun as the primary runtime and toolchain, producing output that works everywhere npm packages are consumed.

When to Use This Skill

Use when:

Creating a new npm library package from scratch
Setting up build/test/lint tooling for an existing package
Fixing CJS/ESM interop, exports map, or TypeScript declaration issues
Publishing a package to npm
Reviewing or improving package configuration

Do NOT use when:

Building an npx-executable CLI tool (use the
```
npx-cli
```
skill)
Building an application (not a published package)
Working in a monorepo (this skill targets single-package repos)

Toolchain

Concern	Tool	Why
Runtime / package manager	Bun	Fast install, run, transpile
Bundler	Bunup	Bun-native, dual output, .d.ts generation
Type declarations	Bunup (via tsc)	Integrated with build
TypeScript	`module: "nodenext"` , `strict: true` + extras	Maximum correctness for published code
Formatting + basic linting	Biome v2	10-25x faster than ESLint, single tool
Type-aware linting	ESLint + typescript-eslint	40+ type-aware rules Biome can't do
Testing	Vitest	Test isolation, mature mocking, coverage
Versioning	Changesets	File-based, explicit, monorepo-ready
Publishing	`npm publish --provenance`	Trusted Publishing / OIDC

Scaffolding a New Package

Run the scaffold script to generate a complete project:

bash

bun run <skill-path>/scripts/scaffold.ts ./my-package \
  --name my-package \
  --description "What this package does" \
  --author "Your Name" \
  --license MIT

Options:

```
--dual
```
— Generate dual CJS/ESM output (default: ESM-only)
```
--no-eslint
```
— Skip ESLint, use Biome only

Then install dependencies:

bash

cd my-package
bun install
bun add -d bunup typescript vitest @vitest/coverage-v8 @biomejs/biome @changesets/cli
bun add -d eslint typescript-eslint  # unless --no-eslint

Project Structure

my-package/
├── src/
│   ├── index.ts            # Package entry point — all public API exports here
│   └── index.test.ts       # Tests co-located with source
├── dist/                   # Built output (gitignored, included in published tarball)
├── .changeset/
│   └── config.json
├── package.json
├── tsconfig.json
├── bunup.config.ts
├── biome.json
├── eslint.config.ts        # Type-aware rules only
├── vitest.config.ts
├── .gitignore
├── README.md
└── LICENSE

Critical Configuration Details

Read these reference docs before modifying any configuration. They contain the reasoning behind each decision and the sharp edges that cause subtle breakage:

reference/esm-cjs-guide.md —
```
exports
```
map configuration, dual package hazard,
```
module-sync
```
, common mistakes
reference/strict-typescript.md — tsconfig rationale, Biome rules, ESLint type-aware rules, Vitest config
reference/publishing-workflow.md — Changesets,
```
files
```
field, Trusted Publishing, CI pipeline

Key Rules (Non-Negotiable)

These are the rules that, when violated, cause the most common and painful bugs in published packages. Follow these without exception.

Package Configuration

Always use
"type": "module"
in package.json. ESM-only is the correct default.
```
require(esm)
```
works in all supported Node.js versions.
Always use
exports
field, not
main
.
```
main
```
is legacy.
```
exports
```
gives precise control over what consumers can access.
types
must be the first condition in every exports block. TypeScript silently fails to resolve types if it isn't.
Always export
"./package.json": "./package.json"
. Many tools need access to the package.json and
```
exports
```
encapsulates completely.
Use
files: ["dist"]
in package.json. Whitelist approach prevents shipping secrets. Never use
```
.npmignore
```
.
Run
npm pack --dry-run
before every publish. Verify the tarball contains exactly what you intend.

TypeScript

Use
module: "nodenext"
for published packages. Not
```
"bundler"
```
. Code satisfying nodenext works everywhere; the reverse is not true.
strict: true
is non-negotiable. Without it, your .d.ts files can contain types that error for consumers using strict mode.
Enable
noUncheckedIndexedAccess
. Catches real runtime bugs from unguarded array/object access.
Ship
declarationMap: true
. Enables "Go to Definition" to reach original source for consumers.
Do not use path aliases (
paths
) in published packages. tsc does not rewrite them in emitted code. Consumers can't resolve them.

Code Quality

any
is banned. Use
```
unknown
```
and narrow. Suppress with
```
// biome-ignore suspicious/noExplicitAny: <reason>
```
only when genuinely unavoidable, and always include the reason.
Prefer named exports over default exports. Default exports behave differently across CJS/ESM boundaries.
Always use
import type
for type-only imports. Enforced by both
```
verbatimModuleSyntax
```
and Biome's
```
useImportType
```
rule.

Build

Build with Bunup using
```
format: ['esm']
```
(or
```
['esm', 'cjs']
```
for dual). Bunup handles .d.ts generation, external detection, and correct file extensions.
Set
engines.node
to
>=20.19.0
in package.json. This documents the minimum supported Node.js version (first LTS with stable
```
require(esm)
```
).

Testing

Use Vitest, not bun:test. bun:test lacks test isolation — module mocks leak between files. Vitest runs each test file in its own worker.
Set coverage thresholds (branches, functions, lines, statements all ≥ 80%). Enforced in vitest.config.ts.

Development Workflow

bash

# Write code and tests
bun run test:watch    # Vitest watch mode

# Check everything
bun run lint          # Biome + ESLint
bun run typecheck     # tsc --noEmit
bun run test          # Vitest run

# Build
bun run build         # Bunup → dist/

# Prepare release
bunx changeset        # Create changeset describing changes
bunx changeset version  # Bump version, update CHANGELOG

# Publish
bun run release       # Build + npm publish --provenance

Adding Subpath Exports

When the package needs to expose multiple entry points:

Add the source file:
```
src/utils.ts
```
Add to bunup.config.ts entry:
```
entry: ['src/index.ts', 'src/utils.ts']
```
Add to package.json exports:

json

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "default": "./dist/utils.js"
    },
    "./package.json": "./package.json"
  }
}

Reminder: Adding or removing export paths is a semver-major change.

Switching to Dual CJS/ESM Output

If consumers require CJS support for Node.js < 20.19.0:

Update bunup.config.ts:
```
format: ['esm', 'cjs']
```
Update package.json exports to include
```
module-sync
```
,
```
import
```
, and
```
require
```
conditions
See reference/esm-cjs-guide.md for the exact exports map structure

Bun-Specific Gotchas

bun build
does not generate .d.ts files. Use Bunup (which delegates to tsc) or run
```
tsc --emitDeclarationOnly
```
separately.
bun build
CJS output is experimental. Always use
```
target: "node"
```
for npm-publishable CJS.
```
target: "bun"
```
produces Bun-specific wrappers.
bun build
does not downlevel syntax. Modern ES2022+ syntax ships as-is. If targeting older runtimes, additional transpilation is needed.
bun publish
does not support
--provenance
. Use
```
npm publish
```
for provenance signing.
bun publish
uses
NPM_CONFIG_TOKEN
, not
```
NODE_AUTH_TOKEN
```
. CI pipelines may need adjustment.

npm-package

NPX Install

Tags

SKILL.md Content

npm Package Development (Bun-First)

When to Use This Skill

Toolchain

Scaffolding a New Package

Project Structure

Critical Configuration Details

Key Rules (Non-Negotiable)

Package Configuration

TypeScript

Code Quality

Build

Testing

Development Workflow

Adding Subpath Exports

Switching to Dual CJS/ESM Output

Bun-Specific Gotchas