Course contentsShow
← JavaScript
Lesson 2519 of 2,72351. Package ManagementFree lesson

MAJOR: Breaking Changes

When to increment the major version and what constitutes a breaking change in your API or public interface.

MAJOR: Breaking Changes

You'll learn when to increment the major version number and what qualifies as a breaking change in your package's API.

What Is a Breaking Change?

In semantic versioning (MAJOR.MINOR.PATCH), the MAJOR version increments when you introduce changes that break backward compatibility. If existing code using your package will throw errors, behave differently, or require modification after updating, that's a breaking change.

Think of it like changing the shape of a puzzle piece. Code that relied on the old shape won't fit anymore without adjustments.

Examples of Breaking Changes

  • Removing a function or method: If you delete an exported function, any code calling it will break.
  • Renaming exports: Changing export function oldName() to export function newName() forces users to update all references.
  • Changing function signatures: Removing parameters, reordering them, or changing return types can break existing usage.
  • Altering behavior: If a function previously returned a number but now returns a string, downstream code may fail.
  • Raising minimum requirements: Requiring a newer Node.js version or dropping support for an older one breaks environments that can't upgrade.

What Isn't a Breaking Change

Adding new features (MINOR), fixing bugs (PATCH), or internal refactoring that doesn't affect the public API are not breaking changes. The key question: "Will existing code continue to work without modification?"

Why It Matters

When you bump from 2.x.x to 3.0.0, you're signaling to users: "Read the changelog carefully before upgrading." This honesty prevents unexpected production failures and maintains trust in your package.

Key Takeaway: Increment the MAJOR version whenever changes force users to modify their code, rename imports, or adjust how they use your package—backward compatibility is the deciding factor.