Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Publishing

Preparing a Package for Publishing

Get a package ready for the registry. Set name, version, exports, files, types, engines and license, and check the manifest with a small readiness linter.

Publishing is where a package stops being your private code and becomes something strangers install, depend on and blame when it breaks. The good news: almost everything that makes a package "ready" lives in one file, package.json, plus a handful of habits. This lesson walks through the fields that matter for consumers, then shows you how to check them automatically.

Everything here applies to npm, Yarn and pnpm alike. They all publish to the same kind of registry and read the same manifest. Only the commands differ, and we cover those in npm pack and publish.

The npm registry itself cannot run on this site, and neither can the npm command. The examples below use plain Node.js to model what the tools do, and every stand-in is labelled. Commands shown in plain code blocks are read-only.

The identity fields

Three fields decide whether a package can be published at all:

  • name: lowercase, no spaces, up to 214 characters, URL-safe. Scoped names look like @acme/parser (see scopes and registries).
  • version: a valid semantic version such as 1.4.0. A version can be published only once, forever.
  • private: if this is true, the package manager refuses to publish. Set it on apps and monorepo roots as a safety net.

Then the fields that help people trust and find you: description, keywords, license (use an SPDX id such as MIT or Apache-2.0), repository, homepage, bugs and author. Search results and the package page are built from these.

Telling consumers what to import

Modern packages describe their entry points with exports. It replaces the older main field and has two jobs: choose which file each import path points to, and block every path you did not list, so users cannot reach into your internals.

JSON
{
  "name": "@acme/slugify",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "engines": { "node": ">=20" },
  "sideEffects": false
}

Key points:

  • Conditions (types, import, require, default) are checked in object order, and the first match wins. Put types first.
  • A string key such as "./cli" creates a sub-path import: import x from '@acme/slugify/cli'.
  • main and module are still worth keeping as a fallback for very old tools, but exports wins when both exist.
  • type: "module" makes .js files ES modules. Use .cjs for CommonJS files in such a package.
  • sideEffects: false tells bundlers they may drop unused imports (tree shaking). Only set it when it is true.

Choosing what ships

By default the registry tarball includes everything in the folder except a few hard-coded exclusions (node_modules, .git, lockfiles). You control the rest with the files array (an allow-list) or an .npmignore file (a deny-list). Prefer files: a forgotten secret in an .env file cannot leak if you never listed it. package.json, README, LICENSE and the files named by main or bin always ship.

Documentation and types

Ship a README.md that shows installation and a minimal example first. Ship a LICENSE file. For TypeScript users, either write the code in TypeScript and publish the generated .d.ts files, or write the declarations by hand, and point to them with the types condition shown above.

Declaring what your package needs

  • dependencies: packages your code imports at run time.
  • peerDependencies: packages the host must provide (a React plugin lists react here, so only one copy exists).
  • optionalDependencies: nice to have; installation continues if they fail.
  • devDependencies: tools for building and testing. They are never installed for your consumers.
  • engines: the Node versions you support. It is advisory unless the user sets engine-strict.

A readiness linter you can run

The tool publint checks many of these rules. Since npm packages cannot run here, this stand-in implements a few checks in plain Node so you can see the logic.

Node.js Stand-in: a publish-readiness checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Resolving the exports map

When Node loads import '@acme/slugify' it walks the map. This second stand-in resolves a request against a simplified exports object with a list of active conditions.

Node.js Stand-in: how an exports map is resolved

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Before the first real publish, run npm pack --dry-run and read the file list. It takes ten seconds and catches most mistakes.

Common mistakes

  • Forgetting to build before publishing, so dist/ is empty. Use a prepublishOnly or prepack script (see version and release workflow).
  • Listing a package in devDependencies that your published code imports at run time.
  • Leaving exports pointing at src/ while files ships only dist/.
  • Publishing an app: set "private": true so it cannot happen.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the exports field do that main cannot?

    exports maps import paths to files by condition (import, require, types) and makes unlisted paths unreachable, which keeps internals private.
  2. 2. Why is the files array safer than an .npmignore file?

    A deny-list must remember every secret or junk file. An allow-list ships only what you listed, plus the always-included files.
  3. 3. Where should a React plugin list react so that only one copy is installed?

    peerDependencies say the host application must provide the package, which avoids duplicate copies.
  4. 4. In an exports condition object, where should the types condition go?

    Conditions are checked in object order and the first match wins, so TypeScript's types must come before import or default.

Summary

  • name, version and license are the identity of a package; private: true blocks accidental publishing.
  • exports defines public entry points by condition and hides everything else.
  • files is an allow-list for the tarball; always check it with a dry run.
  • Dependencies, peers and engines tell consumers what your package needs.
  • A small script (or publint) can check these rules before every release.

Next: Versioning and the Release Workflow