dev-npm-package

# npm Package Development

## Quick Start: Recommended Stack

- **Build**: tsup (esbuild-powered, zero-config, dual CJS/ESM) or tsc alone (for ESM-only packages)
- **Test**: vitest (native ESM/TS, Jest-compatible API)
- **Lint**: Biome (all-in-one linter+formatter) or ESLint flat config + Prettier
- **Types**: TypeScript with `moduleResolution: "Bundler"` (with tsup) or `"Node16"` (with tsc alone)
- **Dev**: tsx for running TS, tsup --watch for rebuilding
- **Publish validation**: publint + @arethetypeswrong/cli (attw)

## Determine Package Type

1. **Library package** -> Follow "Library Setup" below
2. **CLI tool package** -> Follow "CLI Setup" below
3. **Both** -> Combine both patterns

## Library Setup

### Minimal package.json

```json
{
  "name": "my-library",
  "version": "0.1.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"],
  "sideEffects": false,
  "engines": { "node": ">=18" },
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest",
    "test:run": "vitest run",
    "lint": "biome check .",
    "typecheck": "tsc --noEmit",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": {
    "@biomejs/biome": "^2.3",
    "tsup": "^8.4",
    "typescript": "^5.7",
    "vitest": "^3.0"
  }
}
```

### tsup.config.ts

```ts
import { defineConfig } from "tsup";

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

### tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "noUncheckedIndexedAccess": true,
    "noEmit": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

### File Structure

```
my-library/
  src/
    index.ts
    index.test.ts
  package.json
  tsconfig.json
  tsup.config.ts
  vitest.config.ts
  biome.json
  .gitignore
  LICENSE
  README.md
```

## ESM-Only Library Setup

For packages targeting modern Node.js (>=18) without CJS compatibility needs. Simpler than dual publishing.

### Minimal package.json

```json
{
  "name": "@myorg/my-library",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "engines": { "node": ">=18" },
  "scripts": {
    "build": "tsc",
    "test": "vitest run",
    "prepublishOnly": "tsc && vitest run"
  },
  "devDependencies": {
    "typescript": "^5.7",
    "vitest": "^3.0"
  }
}
```

### tsconfig.json (Node16, no bundler)

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

**Important**: With `Node16` resolution, all relative imports must include the `.js` extension (even for `.ts` source files): `import { foo } from './utils.js'`.

### When to choose ESM-only over dual CJS/ESM

- Your package targets Node.js >=18 (or >=22 where CJS can `require()` ESM natively)
- You don't need CJS consumers
- You want the simplest possible setup with `tsc` only (no bundler)

## CLI Setup

### package.json (CLI-specific fields)

```json
{
  "bin": {
    "my-cli": "dist/cli.js"
  },
  "files": ["dist"]
}
```

**Note**: npm recommends bin paths without a `./` prefix (`"dist/cli.js"` not `"./dist/cli.js"`). Modern npm normalizes this automatically, but omitting `./` avoids warnings in older npm versions. Run `npm pkg fix` to check for issues.

### Entry file (src/cli.ts)

```ts
#!/usr/bin/env node
import { program } from "commander";

program
  .name("my-cli")
  .version("1.0.0")
  .description("Description here");

program
  .command("init")
  .option("-t, --template <name>", "template to use", "default")
  .action((options) => {
    console.log(`Template: ${options.template}`);
  });

program.parse();
```

CLI argument parsing libraries: **commander** (most popular, subcommands), **yargs** (validation, middleware), **citty** (lightweight ESM-first).

## Key Rules

### exports Field

- Always place `types` before `default` within each condition block
- `import` condition for ESM, `require` condition for CJS
- `main`/`module`/`types` at top level exist for backward compatibility with older tools

### files Field

Always use `files` as a whitelist (not `.npmignore`). Set to `["dist"]` to publish only build output. Verify with `npm pack --dry-run`.

### prepublishOnly

Always include a `prepublishOnly` script to build (and ideally test) before publishing:

```json
{ "prepublishOnly": "npm run build && npm test" }
```

For tsc-only projects, you can call commands directly: `"prepublishOnly": "tsc && vitest run"`.

### Scoped Packages

For scoped packages (`@myorg/pkg`), configure public access via `.npmrc` in the project root:

```
access=public
```

Alternatively, use `publishConfig` in `package.json`:

```json
{ "publishConfig": { "access": "public" } }
```

### sideEffects

Set `"sideEffects": false` for pure utility libraries to enable tree-shaking. If some files have side effects, list them: `"sideEffects": ["*.css"]`.

### Tree-Shaking

Use named exports (not default export of objects). Avoid classes when individual functions suffice.

## Pre-Publish Checklist

```bash
npm run build              # Build the package
npx publint                # Validate package.json/exports
npx attw --pack .          # Validate TypeScript types
npm pack --dry-run         # Inspect package contents
npm publish --dry-run      # Simulate publish
```

## Detailed References

Read these when you need specifics:

- **Build tools, tsconfig, testing, linting, monorepo**: [references/tooling.md](references/tooling.md) - tsup/tsdown/unbuild comparison, TypeScript config, vitest setup, Biome vs ESLint, pnpm workspaces + Turborepo, dev workflow
- **Publishing, versioning, CI/CD, security**: [references/publishing.md](references/publishing.md) - semver, Changesets/semantic-release, GitHub Actions OIDC trusted publishing, npm provenance, publint/attw, size-limit, supply chain security
- **Architecture, ESM/CJS, exports, CLI, dependencies**: [references/patterns.md](references/patterns.md) - dual publishing patterns, conditional exports, subpath exports, dependency types (peer/optional/bundled), CLI bin setup, argument parsing, tree-shaking optimization