Frontend Academy · Lesson

Versioning and Publishing to npm

Use semantic versioning, automate changelog generation with Changesets or standard-version, and publish the library to npm or a private registry.

Versioning and Publishing to npm is a free Frontend Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Frontend Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Publish to npm?

If your design system is used by more than one app, publish it as a package. Consumers install with npm/yarn/pnpm, lock to versions, and update on their schedule.

Semantic Versioning (SemVer)

Versions follow MAJOR.MINOR.PATCH. MAJOR: breaking changes. MINOR: new features, backwards-compatible. PATCH: bug fixes only.

When to Bump

Renamed a prop? MAJOR. Added a new optional prop? MINOR. Fixed a CSS bug? PATCH. Pre-1.0 releases (0.x.y) can break in MINOR — but be kind.

package.json — The Manifest

Configure how your package looks on npm.

{
  "name": "@yourorg/design-system",
  "version": "1.4.2",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js" },
    "./theme": "./dist/theme.js"
  },
  "files": ["dist", "README.md"],
  "peerDependencies": { "react": "^18.0.0" }
}

Build Output

Ship CommonJS, ESM, and type declarations. Tools like tsup or vite build --lib handle this.

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom']
};

// package.json: "build": "tsup"

peerDependencies

List React/Vue/etc. as peerDependencies so consumers use their own version. Marking them as regular dependencies bundles them twice — broken hooks, broken context.

Tree-shaking Friendly

Use ESM exports and avoid side effects so bundlers can drop unused components. Mark in package.json: "sideEffects": false (or list specific files like CSS).

Publishing to npm

npm login

# Bump version + publish:
npm version patch   # 1.4.2 -> 1.4.3
npm publish

# Or scoped public package:
npm publish --access public

Automating Releases with Changesets

Changesets is the modern toolkit for monorepo + library publishing. PRs include a 'changeset' file describing the change; the release CI bumps versions and publishes.

npm install -D @changesets/cli
npx changeset init

# In each PR:
npx changeset
# pick package, type (major/minor/patch), describe change
# commits .changeset/<random>.md

# CI on main:
npx changeset version  # bumps versions in package.json + generates changelog
npx changeset publish  # publishes to npm

Automated Changelog

Changesets generates a CHANGELOG.md per package automatically from the changeset descriptions — consumers can read what changed in each version.

npm Dist-Tags

Use dist-tags for pre-releases: npm publish --tag beta publishes without overwriting latest. Consumers opt in with npm install @yourorg/design-system@beta.

Private Registries

Internal packages can use GitHub Packages, GitLab Package Registry, or self-hosted Verdaccio. Configure with .npmrc: @yourorg:registry=https://npm.pkg.github.com.

Deprecating Old Versions

Mark a version as deprecated to warn installers.

npm deprecate @yourorg/design-system@1.0.0 'Use 2.x for React 18 support'

Quick Check

If you rename a prop on an exported component, what kind of SemVer version bump is required?

Recap: Versioning & Publishing

SemVer: MAJOR.MINOR.PATCH — breaking, feature, fix. Build CJS + ESM + types (tsup, vite --lib). React/Vue as peerDependencies. sideEffects:false for tree-shaking. npm publish or automate with Changesets. CHANGELOG generated automatically. Dist-tags for betas. Private registries for internal packages.

Frequently asked questions

Is the “Versioning and Publishing to npm” lesson free?

Yes — the full text of “Versioning and Publishing to npm” is free to read here on the web, and the Frontend Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Frontend Academy course, upgrade to CoddyKit PRO.

What will I learn in “Versioning and Publishing to npm”?

Use semantic versioning, automate changelog generation with Changesets or standard-version, and publish the library to npm or a private registry. You practise Frontend Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Frontend Academy?

No prior experience is required. Frontend Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Versioning and Publishing to npm” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Frontend Academy lesson?

Yes. Every Frontend Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Frontend Academy