Publishing to npm and Semantic Versioning

Before publishing, always run npm publish --dry-run. This simulates the publish without actually uploading anything, showing you exactly which files would be included, their sizes, and the package tarball contents. It catches common mistakes like accidentally including source files or missing the dist directory.

Control what gets published using the files field in package.json: "files": ["dist", "README.md"]. This whitelist approach is safer than .npmignore (which is a blacklist and can leak sensitive files if you forget to add them). Always include dist, type declarations, and documentation. Never include src, tests, or node_modules.

npm packages follow semantic versioning (semver): MAJOR.MINOR.PATCH. Increment MAJOR for breaking changes (removing props, changing API signatures). Increment MINOR for new backwards-compatible features (new components, new optional props). Increment PATCH for backwards-compatible bug fixes. Version 0.x.x is considered pre-stable where anything may break.

Pre-release identifiers signal that a version is not production-ready: 1.0.0-alpha.1 for early experimental builds, 1.0.0-beta.2 for feature-complete but possibly buggy versions, and 1.0.0-rc.1 (release candidate) for versions ready for final testing. Publish pre-releases with npm publish --tag beta so they do not become the default install.

Changesets is the standard tool for managing package versioning and changelogs in component libraries. Workflow: contributors run yarn changeset add to record what changed and the change type (major/minor/patch). CI runs yarn changeset version to bump package versions. Publishing runs yarn changeset publish to push to npm.

Changesets automatically generates and maintains CHANGELOG.md based on the changeset files committed by contributors. Each entry includes the version number, release date, and descriptions of changes. This creates a human-readable history of every version without requiring manual changelog maintenance.

semantic-release is a fully automated versioning tool that determines the next version from conventional commit messages (feat: → minor, fix: → patch, BREAKING CHANGE: → major). It bumps the version, generates the changelog, and publishes to npm — all triggered by CI on merge to main. Zero manual version management.

Unscoped packages (my-component) are always public. Scoped packages (@myorg/my-component) default to restricted (private) — publish them public with npm publish --access public. Restricted packages require an npm paid account or organization. Confirm access settings before your first publish.

npm provenance links your published package to its specific git commit in a verifiable way. Enable it with npm publish --provenance in GitHub Actions. Consumers can verify that the package they installed was built from the exact source commit shown on the npm registry page. This significantly improves supply chain security.

When a version has a critical bug or breaking change, deprecate it: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm shows a deprecation warning to anyone installing that version. This does not remove the version (npm does not delete published versions by default) but alerts users to upgrade.

Scoped packages use the format @scope/package-name. The scope is typically your npm username or organization name. Scoped packages make it clear who maintains the package and prevent naming conflicts with unscoped packages. Use scoped packages for private packages and for open-source packages associated with your organization.

According to semantic versioning, when should you increment the MAJOR version number?

Use npm publish --dry-run to preview and files field to control what is published. Semantic versioning: MAJOR for breaking changes, MINOR for new features, PATCH for fixes. Pre-releases use -alpha/-beta/-rc tags. Changesets automates versioning and CHANGELOG generation for collaborative libraries. semantic-release automates from conventional commits. Enable --provenance for supply chain security. Deprecate buggy versions with npm deprecate.