Refactor extensions to move framework modules to peerDependencies #5959
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -36,6 +36,59 @@ export class MyComponent implements Component { | |
| } | ||
| ``` | ||
|
|
||
| ## Working with dependencies | ||
|
|
||
| Extensions should preferably use LoopBack modules installed by the target | ||
| application, to allow application developers to choose the version of framework | ||
| modules they want to use. For example, they may want to hold to an older version | ||
| until a regression is fixed in the latest version, or even use their own fork to | ||
| have a bug fix available before it's officially published. | ||
|
|
||
| We recommend to use `peerDependencies` to specify what packages is your | ||
| extension expecting in the target application and `devDependencies` to make | ||
| these packages available for extension tests. | ||
|
|
||
| For example: | ||
|
|
||
| ```json | ||
| { | ||
| "name": "my-lb4-extension", | ||
| "version": "1.0.0", | ||
| "dependencies": { | ||
| "tslib": "^2.0.0" | ||
| }, | ||
| "peerDependencies": { | ||
| "@loopback/core": "^2.9.1", | ||
| "@loopback/rest": "^5.2.0" | ||
| }, | ||
| "devDependencies": { | ||
| "@loopback/build": "^6.1.0", | ||
| "@loopback/core": "^2.9.1", | ||
| "@loopback/eslint-config": "^8.0.3", | ||
| "@loopback/rest": "^5.2.0", | ||
| "@loopback/testlab": "^3.2.0" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| It is also possible for a single extension version to support multiple versions | ||
| of a framework dependency: | ||
|
|
||
| ```json | ||
| { | ||
| "peerDependencies": { | ||
| "@loopback/core": "^1.9.0 || ^2.0.0" | ||
|
There was a problem hiding this comment. Can lerna or our build update such version ranges for new releases? There was a problem hiding this comment. See the discussions in #4937 and your pull request #4972. Quoting from #4972 (comment):
The current implementation: |
||
| } | ||
| } | ||
| ``` | ||
|
|
||
| {% include important.html content=' Shrinking the supported version range of a | ||
| peer dependency is a breaking change that should trigger a semver-major release. | ||
|
|
||
| For example, changing the range from `"^1.5.3"` to `"^1.5.3 || ^2.0.0"` is | ||
| backwards compatible, while changing the range from `"^1.5.3"` to `"^2.0.0"` is | ||
| a breaking change. ' %} | ||
|
|
||
| ## Injecting the target application instance | ||
|
|
||
| You can inject anything from the context and access them from a component. In | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,14 +38,18 @@ | |
| "url": "https://github.com/strongloop/loopback-next.git", | ||
| "directory": "extensions/apiconnect" | ||
| }, | ||
| "peerDependencies": { | ||
| "@loopback/core": "^2.9.1", | ||
| "@loopback/rest": "^5.2.0" | ||
|
There was a problem hiding this comment. Should
There was a problem hiding this comment. Another criteria: If the dependency is the target extension point for this package to contribute extensions, it's a peer dependency. Using this rule, There was a problem hiding this comment.
Your criteria make sense to me, however I have a different view on how to interpret them. In my opinion, there should be only one version of Also, if the application developer decides to use their forked version of I would also like to add one more criteria:
The use case to consider: where a single version of an extension (e.g. Let's discuss! There was a problem hiding this comment. That's a valid use case that one extension package can support multiple versions of the LoopBack runtime. But it's hard to ensure that with our CI and release process though. In addition to the containing application, we probably should also take into consideration that certain LoopBack packages can be used standalone outside a scaffolded LB4 application. There was a problem hiding this comment.
I now. Personally, I am fine to keep the support for older major versions on a "best effort" basis with no CI check for now. We can setup a more comprehensive CI solution once there are complaints from users about incompatibilities.
That's a good argument. IIRC, packages that can be used standalone outside of LB4 apps are usually more low level ( If a LB package is used by a LB4 application that's not scaffolded via Are you envisioning a project where the developer wants to use an extension depending on There was a problem hiding this comment.
No. At minimum, we'll use There was a problem hiding this comment.
In that case, I think it's reasonable to for extensions to declare @raymondfeng Do you agree to keep the currently proposed direction? May I proceed to rebase this PR on top of latest master (there are going to be many merge conflicts to resolve, so I don't want to do it too many times) and get this PR landed soon? |
||
| }, | ||
| "dependencies": { | ||
| "tslib": "^2.0.0" | ||
| }, | ||
| "devDependencies": { | ||
| "@loopback/build": "^6.1.0", | ||
| "@loopback/core": "^2.9.1", | ||
| "@loopback/eslint-config": "^8.0.3", | ||
| "@loopback/rest": "^5.2.0", | ||
| "@loopback/testlab": "^3.2.0", | ||
| "@types/node": "^10.17.27" | ||
| } | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should mention that
npm 6does not installpeerDependencies. As a workaround, we need to add duplicate entries indevDependenciesso that they can be installed and used for testing.