InterviewLane
Back to System Design
System Design
medium
mid

How would you build and publish your own npm package?

Scaffold with package.json, build to ESM (+ CJS) with TypeScript declarations, set exports/main/module/types fields and the files allowlist, version with semver, test and lint, then npm publish (with CI, provenance, and a changelog). Keep the API small and well-documented.

7 min read·~15 min to think through
Sign in to bookmark & track progress

Publishing an npm package is straightforward; publishing a good one is about correct packaging, clear API, and release hygiene.

1. Scaffold

  • npm init → package.json. Pick a clear, available name (or a scope: @yourorg/pkg).
  • Decide scope: public vs private ("private": true or publishConfig.access).
  • Choose a license, write a real README (install, usage, API, examples).

2. Build & module formats

Ship compiled, consumable output — not raw TS/JSX:

  • TypeScript source → emit ESM (and CJS if you need to support older consumers) plus .d.ts type declarations.
  • Use a bundler/build tool — tsup, unbuild, Rollup, or Vite library mode — they handle ESM+CJS+types cleanly.
  • Configure package.json fields correctly — this is where most packages get it wrong:

``json { "main": "./dist/index.cjs", "module": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" } }, "files": ["dist"], "sideEffects": false } ``

  • exports is the modern source of truth for entry points.
  • files allowlist (or .npmignore) so you don't publish tests/src/config.
  • sideEffects: false helps consumers tree-shake.
  • peerDependencies for things like react — don't bundle the consumer's framework.

3. Quality gates

  • Tests (Vitest/Jest), lint, type-check.
  • npm pack --dry-run (or publint / arethetypeswrong) to inspect exactly what ships and verify the package resolves correctly.
  • Keep the public API small and intentional — every export is a forever contract.

4. Version & publish

  • Semver — patch (fix), minor (feature, backward-compatible), major (breaking).
  • npm login, then npm publish (--access public for a scoped public package).
  • A prepublishOnly script to build + test so you never publish stale artifacts.
  • Use npm version to bump + tag; maintain a CHANGELOG.

5. Automate (for anything real)

  • CI publish — GitHub Actions on a release tag; changesets or semantic-release for automated versioning + changelog.
  • npm provenance (--provenance in CI) for supply-chain trust.
  • Test it for real: npm pack and install the tarball in a sample project, or npm link.

6. Maintain

  • Respond to issues, keep deps updated, document breaking changes, deprecate gracefully (npm deprecate).

The framing

"Scaffold package.json, build TS to ESM+CJS with .d.ts types, and — the part people get wrong — set exports/types/files correctly so it resolves in every consumer. Gate with tests/lint and publint, version with semver, and automate publishing via CI with changesets and provenance. Keep the API minimal — every export is a contract you'll maintain."

Follow-up questions

  • •Why does the package.json 'exports' field matter and what does it replace?
  • •When do you use peerDependencies vs dependencies?
  • •How do you support both ESM and CJS consumers?
  • •How would you automate versioning and changelog generation?

Common mistakes

  • •Publishing raw source instead of compiled output, or shipping no type declarations.
  • •Misconfigured main/module/exports so it doesn't resolve for some consumers.
  • •Publishing tests/src/config because there's no files allowlist.
  • •Bundling react (or another framework) instead of declaring it a peerDependency.
  • •A huge, accidental public API surface.

Performance considerations

  • •Ship ESM and mark sideEffects:false so consumers tree-shake. Keep the dependency footprint small — every dep becomes the consumer's bundle weight. Provide granular entry points if the package is large.

Edge cases

  • •Dual ESM/CJS support and the 'dual package hazard'.
  • •Scoped packages needing --access public.
  • •Breaking changes requiring a major bump and migration notes.
  • •Tree-shaking broken by missing sideEffects:false.

Real-world examples

  • •A shared internal component library or hooks package published to a private registry.
  • •tsup-built dual ESM/CJS package, released via changesets in GitHub Actions with provenance.

Senior engineer discussion

Seniors emphasize correct packaging (the exports/types/files fields, ESM+CJS, peerDependencies) and verification with publint/arethetypeswrong, treat the public API as a long-lived contract to keep minimal, and automate the release pipeline (CI, changesets/semantic-release, semver, provenance, changelog). They mention the dual-package hazard and tree-shaking hygiene.

Related questions