Notify of breaking changes in a package's exports map on publish or install

[thepassle]

Many people don't seem to realize that changes in a package's exports are usually (if not always?) a breaking change. Today we had a team unsuspectingly change their package exports from:

{
  "exports": "./index.js"
}

to:

{
  "exports": {
    "./index.js": "./index.js"
  }
}

Where the former will only allow imports like: import 'my-package';, and the latter only allows imports like: import 'my-package/index.js';, (and thus breaking any existing imports for 'my-package')

And this is something I've seen many packages do as well; changing and/or adding package exports in a minor or patch version, and frankly, has become a bit of a pain to deal with over time.

It feels like NPM could be doing more to educate and or warn about these things. I'm not sure if any of these are viable solutions, but I'd just like to create this post as a point of feedback and starting point for discussion to see if this can't be improved in any way:

• On npm publish, if the publish is a minor or patch version, detect if the publish contains breaking changes in the package exports by comparing to the previous published version, and warn the user publishing about this
• On npm install, if a package is installed with a higher minor or patch version contains a breaking change in the package exports, log a warning to the terminal

I'd be happy to discuss other options, by in any case it would be great to see if we could somehow improve on this 🙂

[ljharb]

fwiw I’ve been working on npmjs.com/list-exports which can help with this, and after an upcoming overhaul I’ll be working on a package to achieve exactly this behavior.

[MylesBorins]

An off-the-shelf tool that can integrate as a lifecycle script seems like a great solution to this problem.

[thepassle]

Is that to say something like this wont be considered in npm itself? In good faith; can I ask why not? Having a third party tool do this via a script would mean opting into it; package authors would have to know about this tool and set it up, rather than it being widely available out of the box, decreasing the chance of breaking changes

[ljharb]

What I’d hope is that once an off the shelf tool had been sufficiently battle-tested, that npm would consider incorporating it.

[nickserv]

I don't think this check should be enabled in npm by default. While npm packages are expected to follow SemVer, this isn't a requirement, and some popular packages like TypeScript and Prettier don't adhere fully. Seeing a warning that you're not following SemVer when it's intentional could be confusing.

I think this is more of an education issue, so I'd prefer clarifications in docs and other messaging. A general tool or opt-in check (possibly part of npm pkg fix or with a config option that explicitly opts in to strict SemVer) could help automate this, though.

[thepassle]

This is a fair point, naturally there will always be a few outliers/edgecases that don't follow semver, but I don't think thats a good enough reason not to do anything at all; the vast majority of NPM packages does use semver and would largely benefit from something like this. Additionally, it doesn't have to be a big red error message in the terminal, it could also be more neutral. I'm sure that with our powers combined we can think of something that would be useful to mitigate this problem :)

Opt-in checks are of less value, because it would require package authors to know about the tool and set it up. A large number of packages that I've seen make breaking changes in package exports (both internally at work, and in the open source ecosystem) seem like they probably wouldn't know about tooling like this.

[nickserv]

True, there is a discoverability problem, but I think there's more we can do to improve this with documentation, blog posts, and other resources.

[thepassle]

Im not entirely convinced that this is purely a documentation problem, there already exist many blogs etc today, but package exports have so many footguns that even more experienced developers make mistakes. Im happy to be proven wrong though :)

[nickserv]

I'm not sure it is, but it would at least be a good interim solution, and less intrusive.