Intra-monorepo dependencies are too broad and often break

[anomiex]

Description

It seems fairly common that you introduce an "experimental" API in one module and use it in others, then later on remove the experimental API (e.g. by promoting it to stable) while updating the other modules to use the new version.

That's ok. The problem is that the dependencies between your modules do not reflect this. For example, I recently had some trouble in a project with a dependency on @wordpress/components 9.2.6: that version of @wordpress/components depends on @wordpress/element ^2.11.0, but the promotion of __experimentalCreateInterpolateElement to stable in 2.13.0 breaks the older @wordpress/components. So when the package manager got confused about its locks (due to an unrelated package upgrade) and upgraded @wordpress/element to 2.20.3, things broke.

Possible ways to have avoided this:

• If you had depended on ~2.11.0 instead, that would have worked because the breaking change included a minor version bump.
• Or if you had kept the __experimentalCreateInterpolateElement name around as a deprecated alias until a future major version bump, that would have worked too. But deprecation warnings might have been annoying; I ran into that with @wordpress/components 9.2.6's dependency on @wordpress/compose ^3.11.0 when that got satisfied by 3.25.3.
• Or if you had done a major version bump in conjunction with the removal of the API that would have worked. But I understand why you might not want to do a major version bump when it's just an experimental API being changed.

I'm not asking that you go back and update all the old releases of all the modules. I am asking that you consider this sort of thing going forward.

Step-by-step reproduction instructions

1. In an empty directory, npm add --legacy-peer-deps @wordpress/components@9.2.6 @automattic/calypso-build webpack
2. Create src/index.js with contents const components = require( "@wordpress/components" );
3. Run npx calypso-build

You could also use webpack directly instead of calypso-build; the latter just provides in a useful default configuration for webpack.

Expected behaviour

No missing imports.

Actual behaviour

ERROR in ./node_modules/@wordpress/components/build-module/text-highlight/index.js 24:9-47
export '__experimentalCreateInterpolateElement' (imported as '__experimentalCreateInterpolateElement') was not found in '@wordpress/element' (possible exports: Children, Component, Fragment, Platform, RawHTML, StrictMode, Suspense, cloneElement, concatChildren, createContext, createElement, createInterpolateElement, createPortal, createRef, findDOMNode, forwardRef, isEmptyElement, isValidElement, lazy, memo, render, renderToString, switchChildrenNodeName, unmountComponentAtNode, useCallback, useContext, useDebugValue, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState)
 @ ./node_modules/@wordpress/components/build-module/index.js 72:0-60 72:0-60
 @ ./src/index.js 1:17-49

WordPress information

• WordPress version: N/A
• Gutenberg version: N/A
• Are all plugins except Gutenberg deactivated? N/A
• Are you using a default theme (e.g. Twenty Twenty-One)? N/A

Device information

• Device: N/A
• Operating system: N/A
• Browser: N/A

[gziolo]

I listed it as a topic to discuss in the weekly Core JS chat on WordPress Slack in the #core-js channel.

Meeting dates can be found at https://make.wordpress.org/meetings/: