Publishing TypeScript Packages to npm: ESM, CommonJS, Declarations, and Release Checks
TypeScriptnpmPackage PublishingESMCommonJSLibraries

Publishing TypeScript Packages to npm: ESM, CommonJS, Declarations, and Release Checks

TTypeScript.page Editorial Team
2026-11-10
7 min read

A practical checklist for publishing TypeScript packages with ESM, CommonJS, declarations, exports, and reliable npm release checks.

Publishing a TypeScript library is more than compiling .ts files. This reusable checklist covers build-tool choices, ESM and CommonJS compatibility, declaration files, package metadata, local consumer testing, and release checks so your npm package is easier for applications, bundlers, and editors to consume correctly.

Overview

A publishable TypeScript package has three related but separate concerns:

  • Runtime output: JavaScript that a consumer's runtime or bundler can load.
  • Type information: declaration files that editors and the TypeScript compiler can discover.
  • Package metadata: the package.json instructions that connect import conditions to the correct files.

Supporting only one module format can be reasonable for a private application, but a public library should make its intended module behavior explicit. ESM and CommonJS differ in how consumers resolve and execute modules, while bundlers may interpret fields such as exports, module, and main differently. The safest approach is to choose a supported consumer matrix first, then build and test against it.

Before publishing, decide whether the package will offer ESM only, CommonJS only, or both. Also decide whether the package exposes one root entry point or multiple subpath entry points. Keep the public surface deliberate: the files you publish, the declarations you generate, and the paths you advertise should describe the same API. For broader API design guidance, see this guide to TypeScript module boundaries and public API design.

Checklist by scenario

Choose a build workflow

WorkflowUseful whenThings to verify
Plain tscYou want TypeScript to compile source with minimal transformation and you are comfortable managing output structure.Separate ESM and CommonJS configurations if needed; confirm declarations, source maps, and output paths.
tsupYou want a small library-oriented build configuration with bundling and common output options.Check its declaration generation, external dependency behavior, format settings, and how it handles your entry points.
RollupYou need detailed control over entry points, plugins, output formats, tree-shaking, or package structure.Review plugin compatibility, declaration generation, external dependencies, and output extensions.
esbuildYou value fast builds and straightforward bundling with a small configuration.Plan separately for declaration files, type checking, declaration maps, and any syntax that requires additional tooling.

There is no universally correct tool. Plain tsc keeps the relationship between source and output visible, while a bundler can simplify distribution and reduce the number of published files. Whichever workflow you choose, run TypeScript checking independently when the build tool does not perform full type checking. A build that emits JavaScript is not automatically proof that the public types are correct.

Scenario: ESM-only package

  • Declare the intended module behavior consistently in package.json and your TypeScript configuration.
  • Publish JavaScript with extensions and import paths that match the runtime and build output.
  • Set the root exports entry to the ESM file and expose its declaration file through the corresponding types condition where your toolchain supports that structure.
  • Test a clean install in an ESM consumer rather than importing directly from your repository source.

Scenario: ESM and CommonJS package

  • Produce distinct output for each format instead of asking one file to satisfy incompatible loading rules.
  • Use conditional exports so ESM consumers and CommonJS consumers receive the appropriate file.
  • Give each output a clear extension, such as .js and .cjs, when that is necessary to remove ambiguity.
  • Generate declarations that match the public API, and verify that both import styles resolve types correctly.
  • Test direct Node.js usage as well as at least one bundler or application setup relevant to your audience.

Scenario: Multiple public entry points

  • List every supported subpath explicitly in exports; do not assume consumers should reach into dist or src.
  • Generate declarations for each entry point or provide a predictable declaration layout.
  • Test both the root import and every documented subpath from a separate fixture project.
  • Check that internal files are not accidentally exposed as part of the public contract.

A starting package.json template

Adapt the paths and conditions to the output produced by your build. This example shows the metadata that deserves deliberate review; it is not a drop-in configuration for every package.

{
  "name": "your-package",
  "version": "1.0.0",
  "type": "module",
  "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", "README.md", "LICENSE"],
  "sideEffects": false,
  "scripts": {
    "build": "your-build-command",
    "typecheck": "tsc --noEmit",
    "pack:check": "npm pack --dry-run"
  }
}

exports should be treated as the primary map of supported entry points. main remains useful for compatibility with tools that do not fully use conditional exports, while module is recognized by some bundlers but is not a substitute for a carefully tested exports map. The types field provides a package-level fallback for declaration discovery. Keep files narrow so tests, source maps, private configuration, and credentials are not published by accident. Set sideEffects only when you understand whether importing the package can trigger required global behavior or registration.

What to double-check

Declarations and source maps

Open the generated .d.ts files and inspect the public signatures. Look for declarations that reference private source paths, unavailable internal types, or development-only dependencies. If you publish declaration maps, confirm that their paths are useful to consumers and do not reveal an unwanted repository layout. A package can run correctly while its declarations still fail in an editor.

Included files

Use npm pack --dry-run before publishing and inspect the file list. Confirm that the archive includes JavaScript, declarations, source maps if intended, the README, and the license file. Confirm that it excludes tests, local fixtures, environment files, credentials, and unrelated build output. Test the actual tarball rather than only testing the repository directory.

Dependencies and externalization

Decide which dependencies are bundled and which remain package dependencies. A bundled dependency may increase output size or create duplicate runtime copies; an external dependency must be declared correctly so consumers receive it. Check peer dependency expectations for libraries that integrate with a host framework. Avoid relying on a dependency that exists only because another package happens to install it.

Consumer tests

Create a temporary fixture with the packed archive and test the documented usage. Include an ESM import, a CommonJS require when supported, TypeScript compilation, editor type discovery, and the bundler or framework combinations your users are likely to have. This catches incorrect paths that unit tests inside the library cannot detect. Pair package tests with a broader TypeScript testing workflow when appropriate; the Vitest and Jest comparison can help structure that decision.

Release integrity

  • Run the build from a clean checkout.
  • Run type checking and the test suite.
  • Inspect the packed archive.
  • Verify the version change follows your chosen semantic versioning policy.
  • Review changelog entries and migration notes for breaking API changes.
  • Use npm's supported provenance or publishing options when they fit your release environment, and verify current registry requirements before relying on them.
  • Publish only after the packed artifact passes consumer tests.

Common mistakes

  • Publishing src as the API: Consumers should use documented package entry points, not internal repository paths.
  • Using exports without testing it: An exports map can intentionally block paths that previously worked. Treat every blocked import as either a migration task or a useful boundary.
  • Generating declarations from a different source than the runtime build: This can make types describe files or exports that do not exist in the package.
  • Assuming a bundler performs type checking: Keep a dedicated tsc --noEmit or equivalent check in the release process.
  • Testing only with the workspace: Monorepo links and hoisted dependencies can hide missing files and incorrect dependency declarations.
  • Calling a dual-format package finished after one import succeeds: Test both module systems, declaration discovery, and the actual packed archive.
  • Changing module settings casually: A change to TypeScript module or resolution options can alter emitted paths and consumer behavior. Review the related TypeScript compiler options together.

When to revisit

Use this checklist before every first release and whenever the package's inputs change. Revisit it before seasonal planning or maintenance cycles, after changing Node.js or TypeScript module settings, when switching build tools, and after adding a new entry point or dependency. Return to it when a consumer reports a broken import, missing declarations, an unexpected CommonJS or ESM error, or a bundler-specific resolution problem.

For the next release, make the process concrete:

  1. Write down the supported consumer matrix: ESM, CommonJS, TypeScript, Node.js, bundlers, and frameworks.
  2. Build from a clean checkout and run type checking, tests, and the package archive preview.
  3. Install the archive into a fresh fixture and test every documented import.
  4. Inspect declarations, source maps, exports, and included files.
  5. Review the version, changelog, release command, and current npm guidance before publishing.
  6. Record any compatibility decision in the README so the next release starts with an explicit baseline.

A reliable TypeScript npm package is not defined by a particular bundler. It is defined by a clear public contract, matching runtime and type outputs, and a release process that tests what consumers actually install.

Related Topics

#TypeScript#npm#Package Publishing#ESM#CommonJS#Libraries
T

TypeScript.page Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.