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
In an empty directory, npm add --legacy-peer-deps @wordpress/components@9.2.6 @automattic/calypso-build webpack
Create src/index.js with contents const components = require( "@wordpress/components" );
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
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:
__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.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
npm add --legacy-peer-deps @wordpress/components@9.2.6 @automattic/calypso-build webpack
src/index.js
with contentsconst components = require( "@wordpress/components" );
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
WordPress information
Device information