How to Publish a TypeScript Package: Declarations, ESM, CommonJS, Exports, and Release Checks
npmpackage publishingTypeScript librariesESMCommonJSdeclarations

How to Publish a TypeScript Package: Declarations, ESM, CommonJS, Exports, and Release Checks

TTypeScript Website Editorial Team
2026-11-10
8 min read

A practical checklist for publishing TypeScript packages with declarations, ESM, CommonJS, exports, source maps, and consumer tests.

Publishing a TypeScript package is more than compiling .ts files and running npm publish. This guide provides a reusable release checklist for declarations, ESM and CommonJS output, package exports, source maps, dependencies, and local consumer testing so your library is easier to install, import, and type-check.

Overview

A publishable TypeScript library has two audiences: the JavaScript runtime and the developer using the package in an editor or build. Runtime consumers need executable JavaScript in the module formats you support. TypeScript consumers need accurate declaration files that describe the same public API. Package managers and bundlers need clear metadata that points to those files.

A practical package workflow separates source code from release artifacts:

  • Source: usually stored in src/ and written in TypeScript.
  • Build output: generated into a directory such as dist/.
  • Declarations: .d.ts files generated from the public TypeScript API.
  • Metadata: a carefully tested package.json that defines entry points and included files.
  • Release checks: validation in a clean consumer project, not only inside the library repository.

The most important design decision is which consumers you intend to support. A package used only by modern ESM applications can have a simpler output strategy than a package that must work in both ESM and CommonJS projects. Decide this before configuring the build, because module format, file extensions, exports, and declaration paths need to agree.

For broader TypeScript project configuration context, see this TypeScript tsconfig guide. If your package exposes a complicated public API, a review of TypeScript utility types and API patterns can also help you keep declarations readable and intentional.

Checklist by scenario

Scenario 1: An ESM-only package

Choose this route when your supported consumers already use ESM and you do not need a CommonJS entry point. Mark the package appropriately and make the generated file extensions consistent with that decision. A minimal metadata shape might look like this:

{
  "name": "@example/date-tools",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "prepublishOnly": "npm run check"
  }
}

The exact fields your consumers need depend on their tools. The exports map is the important contract for modern resolution. Keep the legacy main and types fields only when they provide useful compatibility for the environments you support; do not point them at files that are not published.

  • Use an ESM-compatible TypeScript and bundler configuration.
  • Generate declarations alongside the ESM build.
  • Test both a direct package import and a TypeScript editor or compiler.
  • Check that relative imports in emitted JavaScript use the extensions expected by your module configuration.

Scenario 2: A package supporting ESM and CommonJS

Dual-format packages need two executable entry points and one clear type entry point. A common layout is:

ConsumerPublished filePurpose
ESM importdist/index.jsModern module consumers
CommonJS requiredist/index.cjsCommonJS consumers
TypeScript typesdist/index.d.tsStatic type resolution
Source mapsdist/*.mapDebugging generated code

One possible exports map is:

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  }
}

The types condition tells TypeScript where to find declarations, while import and require select runtime files for different consumers. Keep the conditions and file paths aligned with the actual tarball. Some tools handle conditional exports differently, so local testing should include the package managers, runtimes, or bundlers that matter to your audience.

Configuration choiceAdvantagesThings to verify
ESM onlySmaller release surface and fewer build variantsConsumers must support ESM and your chosen resolution rules
ESM plus CommonJSBroader compatibilityBoth builds, exports conditions, and interop behavior need testing
Bundler-generated outputCan create optimized, predictable artifactsDeclarations, external dependencies, and source maps need explicit configuration
TypeScript-only outputSimple and transparent compilationMultiple module formats may require separate build configurations

Scenario 3: A package with subpath exports

If you want consumers to import paths such as @example/date-tools/format, define each public subpath explicitly. Do not assume that every file in dist/ should be public.

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  },
  "./format": {
    "types": "./dist/format.d.ts",
    "import": "./dist/format.js",
    "require": "./dist/format.cjs"
  }
}

Every new subpath becomes part of your package API. Add it only after testing its runtime and type-resolution behavior. If you later remove or rename an export, treat that as a compatibility decision rather than an internal file cleanup.

Scenario 4: A package with React, Node.js, or other peer dependencies

Libraries that integrate with a host application often need peerDependencies. React components, for example, generally should not silently install a second incompatible copy of the host framework. Put packages that the consumer is expected to provide in peerDependencies, and keep build-time tools such as TypeScript, test runners, and bundlers in devDependencies.

Be precise about runtime dependencies. If emitted JavaScript imports a package at runtime, that package must be available to consumers through the appropriate dependency declaration or a deliberate bundling strategy. Test the packed artifact rather than relying on the workspace's installed modules.

What to double-check before publishing

Declarations describe the public API

Enable declaration generation in the release build, typically with declaration: true. If you publish source maps, consider declarationMap: true when the resulting source references are useful to consumers. Check that declarations do not expose private source paths, test-only types, or accidental implementation details.

Use a separate build configuration when the development configuration includes tests, application code, or settings that should not affect the package. For example, a release config can define rootDir, outDir, declaration, and sourceMap specifically for the published library. Run the compiler with no emit before building to catch type errors, then inspect the generated directory.

The published file list is intentional

Use the files field or an equivalent ignore strategy to control what enters the package tarball. The release should normally contain runtime files, declarations, source maps if supported, and documentation such as a README and license. It should not contain tests, local configuration, credentials, editor folders, or an unnecessary source tree.

"files": [
  "dist",
  "README.md",
  "LICENSE"
]

Before publishing, run a pack command and inspect the archive contents. This catches missing declarations and unwanted files without changing the registry.

Exports, legacy fields, and extensions agree

Check every path in exports, main, module, and types. A common failure is updating the build directory while leaving package metadata pointed at an old filename. Another is mixing a package-level type setting with output extensions that imply a different module interpretation.

Do not add compatibility fields merely because a template includes them. Document which environments you test, then keep metadata consistent with that support boundary.

Local consumer testing is separate from library testing

Unit tests confirm that your source behaves correctly; they do not necessarily prove that another project can resolve your package. Create a temporary consumer project, install the packed archive, and test:

  • An ESM import, if supported.
  • A CommonJS require, if supported.
  • TypeScript compilation with the intended module resolution settings.
  • Editor navigation from an exported function to its declaration.
  • Each documented subpath export.
  • Runtime behavior after installation without workspace-only aliases.

For a broader testing workflow, use the principles in Testing TypeScript code. If compiler diagnostics appear during consumer testing, the TypeScript error messages reference can help separate a declaration problem from a module-resolution problem.

Reusable prepublish checklist

  1. Confirm the supported Node.js, TypeScript, bundler, and package-manager range for this release.
  2. Remove the previous build directory.
  3. Run linting, tests, and a no-emit type check.
  4. Run the release build and generate declarations.
  5. Inspect JavaScript, .d.ts, and source-map output.
  6. Run the package manager's pack or equivalent archive command.
  7. Inspect the archive for missing and unwanted files.
  8. Install the archive into a clean ESM consumer.
  9. Install it into a CommonJS consumer when that format is supported.
  10. Compile a TypeScript consumer and exercise every documented entry point.
  11. Review dependency, peer dependency, version, README, and license metadata.
  12. Publish only after the archive and consumer checks pass.

Common mistakes

  • Publishing only TypeScript source: consumers should not have to reproduce your private build process. Publish the intended JavaScript and declaration artifacts.
  • Declaring types without shipping them: a types field is not useful when the referenced .d.ts file is excluded from the archive.
  • Testing only from the monorepo: workspace links and path aliases can hide missing dependencies and incorrect package paths.
  • Using a broad wildcard export: exposing every generated file makes internal paths part of the public API. List supported entry points deliberately.
  • Mixing module assumptions: ESM and CommonJS output require consistent package metadata, extensions, and consumer tests.
  • Bundling peer dependencies unintentionally: decide whether a dependency belongs to the consumer, the package, or the bundle, then verify the emitted output.
  • Skipping the packed archive: the source repository is not the same thing as the package a registry consumer receives.
  • Changing exports casually: adding, removing, or moving an entry point can affect imports and editor resolution even when internal code still passes tests.

When to revisit

Use this checklist before every release, especially when changing the package entry point, adding a subpath export, switching bundlers, changing the TypeScript module configuration, or introducing a peer dependency. Revisit it during seasonal planning cycles as well, when you review supported runtimes and decide whether older module consumers still belong in the support matrix.

Toolchain conventions can change. When upgrading Node.js, TypeScript, a bundler, or a package manager, rebuild a packed archive and repeat the clean-consumer tests instead of assuming that old resolution behavior remains unchanged. Do the same when consumers report errors such as an import that works in development but fails after installation, missing declarations, or a package that cannot be loaded by require.

A practical release note should record the package's supported module formats, public entry points, declaration location, and validation commands. Keeping that contract visible makes future changes easier to review. If the project has grown beyond a single entry point, also review your TypeScript project structure and TypeScript ESLint workflow so build and quality checks remain maintainable.

Action to take now: build your package, create an archive, inspect its contents, and install that archive into a clean consumer project. If ESM, CommonJS, and TypeScript resolution all work from the artifact—not merely from the repository—you have tested the package that users will actually receive.

Related Topics

#npm#package publishing#TypeScript libraries#ESM#CommonJS#declarations
T

TypeScript Website 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.