Index of every page on this site: llms.txt
All skills
jwynia avatar

/npm-package

@e02ec7e
by J Wyniajwynia/agent-skills191 stars
24
Run it yourself

Build and publish npm packages using Bun as the primary toolchain with npm-compatible output. Use when the user wants to create a new npm library, set up a TypeScript package for publishing, configure build/test/lint tooling for a package, fix CJS/ESM interop issues, or publish to npm. Covers scaffolding, strict TypeScript, Biome + ESLint linting, Vitest testing, Bunup bundling, and publishing workflows. Keywords: npm, package, library, publish, bun, bunup, esm, cjs, exports, typescript, biome, vitest, changesets.

Use this Skill: https://skilld.dev/gh/jwynia/agent-skills/npm-package

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈133 tokens for metadata: the name and description. ≈2k when used: this file. ≈5k more on demand in 5 files.

Description uses 6.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈533 characters, or 6.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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:

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:

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

  1. Always use "type": "module" in package.json. ESM-only is the correct default. require(esm) works in all supported Node.js versions.

  2. Always use exports field, not main. main is legacy. exports gives precise control over what consumers can access.

  3. types must be the first condition in every exports block. TypeScript silently fails to resolve types if it isn't.

  4. Always export "./package.json": "./package.json". Many tools need access to the package.json and exports encapsulates completely.

  5. Use files: ["dist"] in package.json. Whitelist approach prevents shipping secrets. Never use .npmignore.

  6. Run npm pack --dry-run before every publish. Verify the tarball contains exactly what you intend.

TypeScript

  1. Use module: "nodenext" for published packages. Not "bundler". Code satisfying nodenext works everywhere; the reverse is not true.

  2. strict: true is non-negotiable. Without it, your .d.ts files can contain types that error for consumers using strict mode.

  3. Enable noUncheckedIndexedAccess. Catches real runtime bugs from unguarded array/object access.

  4. Ship declarationMap: true. Enables "Go to Definition" to reach original source for consumers.

  5. Do not use path aliases (paths) in published packages. tsc does not rewrite them in emitted code. Consumers can't resolve them.

Code Quality

  1. any is banned. Use unknown and narrow. Suppress with // biome-ignore suspicious/noExplicitAny: <reason> only when genuinely unavoidable, and always include the reason.

  2. Prefer named exports over default exports. Default exports behave differently across CJS/ESM boundaries.

  3. Always use import type for type-only imports. Enforced by both verbatimModuleSyntax and Biome's useImportType rule.

Build

  1. Build with Bunup using format: ['esm'] (or ['esm', 'cjs'] for dual). Bunup handles .d.ts generation, external detection, and correct file extensions.

  2. 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

  1. Use Vitest, not bun:test. bun:test lacks test isolation — module mocks leak between files. Vitest runs each test file in its own worker.

  2. Set coverage thresholds (branches, functions, lines, statements all ≥ 80%). Enforced in vitest.config.ts.

Development Workflow

# 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:

  1. Add the source file: src/utils.ts
  2. Add to bunup.config.ts entry: entry: ['src/index.ts', 'src/utils.ts']
  3. Add to package.json exports:
{
  "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:

  1. Update bunup.config.ts: format: ['esm', 'cjs']
  2. Update package.json exports to include module-sync, import, and require conditions
  3. 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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides a comprehensive toolkit for npm package development using the Bun toolchain, promoting modern security best practices like npm provenance and restricted file whitelisting. It includes templates and a local scaffolding script for project setup without any detected malicious patterns.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    14/14 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at e02ec7e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 9 months ago

README badge

README badge for jwynia/agent-skills/npm-package