From a1f21fc5a930431c6e6239a705feda9e5e9c5d41 Mon Sep 17 00:00:00 2001 From: Mobeen Abdullah Date: Mon, 17 Aug 2026 12:44:10 +0500 Subject: [PATCH] docs(plugin-page-builder): name the builder peer in the fallback install 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. --- packages/plugin-page-builder/GUIDE.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/packages/plugin-page-builder/GUIDE.md b/packages/plugin-page-builder/GUIDE.md index e387be6582..f2cc73d557 100644 --- a/packages/plugin-page-builder/GUIDE.md +++ b/packages/plugin-page-builder/GUIDE.md @@ -44,9 +44,14 @@ That's it — the plugin and the pieces it depends on are now in your project. > install with: > > ```bash -> npm install @nextlyhq/plugin-page-builder --legacy-peer-deps +> npm install @nextlyhq/plugin-page-builder @nextlyhq/builder --legacy-peer-deps > ``` > +> `@nextlyhq/builder` is named explicitly on purpose. `--legacy-peer-deps` tells +> npm to skip peer dependencies altogether, and the editor's chrome is a peer that +> this plugin imports at runtime — so the flag on its own gives you an install that +> resolves and then fails when the editor loads. Asking for it by name puts it back. +> > This is safe for experimenting. Once the corrected version is released, the plain > command above works and you can delete this note. @@ -354,7 +359,9 @@ Your built page is now served to the public. 🎉 ## Troubleshooting **Install fails with `ERESOLVE` / peer dependency error** -See the temporary note in Step 1 — install with `--legacy-peer-deps` for now. +See the temporary note in Step 1. Install with `--legacy-peer-deps` for now, and +name `@nextlyhq/builder` alongside the plugin — the flag skips peers, and that one +is a peer the editor needs at runtime. **The `/admin` page or editor shows an error like `Can't resolve '@nextlyhq/plugin-sdk'` or `Cannot find module 'next/link'`** @@ -391,7 +398,7 @@ add at least one block, and Publish again. ```bash # 1. Install -npm install @nextlyhq/plugin-page-builder # add --legacy-peer-deps for now +npm install @nextlyhq/plugin-page-builder # see Step 1 if this hits ERESOLVE # 2. next.config.ts -> add plugin to transpilePackages (NOT serverExternalPackages)