docs(plugin-page-builder): name the builder peer in the fallback install - #897
Conversation
The guide's ERESOLVE workaround tells users to install with --legacy-peer-deps, which npm documents as ignoring peerDependencies altogether. @nextlyhq/builder is a peer, and the plugin imports it at runtime: EditorSurface loads @nextlyhq/builder/shell and editor.css imports its stylesheet. So the documented command resolved and then failed when the editor loaded, which is a worse outcome than the ERESOLVE it avoids. Naming the package explicitly puts it back. The note stays temporary and still says to delete it once the corrected version publishes, since the version mismatch it exists for is already fixed in source.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 46 minutes Limit details: You’ve used all 1 included review currently available under your plan. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@nextly-bot review |
github-actions
Bot
added
type: docs
1 participant
Closes the last open thread on #865.
The documented install is currently a broken install
GUIDE.mdtells users to work around anERESOLVEerror with:npm documents that flag as ignoring
peerDependenciesaltogether. Measured againstmain:@nextlyhq/builderis a peer of this plugin (package.jsonpeerDependencies)EditorSurface.tsx:12loads@nextlyhq/builder/shell,controls/MediaControl.tsx:10loadsuseShellIsActive, andstyles/editor.css:24imports@nextlyhq/builder/styles.cssSo the command resolves and then fails when the editor loads. That is worse than the
ERESOLVEit exists to avoid: a resolution error is loud and immediate, while this one arrives later, somewhere else, as a missing module.It became true with #865, which added the builder peer. Before that, skipping peers was survivable here.
The change
Name the package explicitly in the fallback, and say why:
Three places: the Step 1 note, the Troubleshooting entry that points at it, and the quick reference, which now defers to Step 1 rather than carrying a half-instruction.
What I deliberately did NOT do
Make
@nextlyhq/buildera realdependency. That is the tempting fix and it is wrong here.packages/ui'sSTABILITY.mdstates that a second copy means a second context; builder is a React UI package, so it has to be a single shared copy in the host's tree, which is what a peer expresses.@nextlyhq/uiand@nextlyhq/adminare peers of this plugin for the same reason. A dependency would trade a documented install step for duplicated-copy bugs that are far harder to diagnose.Delete the note. Its stated cause — the plugin advertising
^18.0.0 || ^19.0.0againstblocks-react's^19.0.0— is already fixed in source, so the note becomes deletable at the next publish. It is not deletable yet, because the version on npm still has the mismatch. The note keeps saying to remove it once the corrected version ships.The gap this leaves, which is real and separate
Nothing checks that the documented install command actually resolves. The guide and the manifest are two answers to "what does a consumer need to install", and only the manifest is tested — which is why this drifted silently and was found by a reviewer reading a diff rather than by anything running.
A check that installs the published tarball into a scratch project and imports the plugin's admin entry would make it a boundary rather than a habit. That is its own piece of work, larger than this, and I am flagging it rather than smuggling it in.
Verification
Docs-only, and
GUIDE.mdis not in the package'sfiles(["dist", "README.md"]), so nothing ships from this. No changeset, perAGENTS.md: docs-only PRs get none.The three factual claims above are each measured rather than recalled: the peer list from
package.json, the runtime imports by grep oversrc, and the flag's semantics from npm's own documentation.