"@blu/sdk/shell" is internal to the Blu shell |
Code reached for the shell's provider side. Modules read context with the @blu/sdk hooks only. |
"@blu/host-sdk" was renamed (also @blu/service-sdk, @blu/module-dev-harness) |
Old package names. Use @blu/sdk, @blu/sdk/server, @blu/sdk/dev. |
federation() must share "@blu/sdk": { singleton: true } |
Without it the module bundles its own SDK copy, a separate React context, and useUser() throws "called outside " inside Blu. |
federation() name isn't … / doesn't expose … |
The build's name / exposes key must equal the manifest's remote.name / remote.exposed. |
uses the published name / Use the published package under that name |
Install as "@blu/sdk": "npm:@horizonmedia/blu-sdk@^…" and import @blu/sdk. The alias keeps one name in code. |
.npmrc points @horizonmedia at GitHub Packages |
The SDKs are public on npm now. Remove that line (and any token for it) and reinstall. |
moduleId "x" isn't the manifest's id |
Blu issues tokens for blu-module:<manifest id>; any other moduleId refuses every Blu call (invalid_token). |
tool "x" is declared in the manifest but no code defines it / pass your blu.module.json as manifest |
Manifest tools and code tools must match exactly. Pass manifest so a mismatch stops the API at startup instead of surprising the Concierge. |
link("x", …) names a route the manifest doesn't declare |
Add the route to routes, or link to an existing one. Undeclared links are dropped at runtime. |
routes.x: path must be /literal/:param/… |
Route paths can't be / alone, and use :param for variables. The module's landing page needs no route entry. |
| The page renders in Blu but data never loads |
The API's CORS doesn't list the Blu shell origin. |
Every API call gets 401 untrusted_issuer |
BLU_ISSUER doesn't match the environment the token came from (each environment's Blu has its own issuer). |
401 dev_identity_refused |
A local test sign-in was used against a deployed API. Expected: only APIs on localhost accept those. |
| Styles leak into Blu, or Blu's styles break the module |
Don't style html / body / :root, or use global resets, in the module. Next.js apps: the adapter scopes globals.css for you. |
| Inside Blu the URL changes but the module doesn't follow (or the other way round) |
The module routes with window.location or its own history. Route with useRoute() (or the Next adapter), which keeps Blu's address bar and back button in sync. |
| A module built against a newer SDK fails in an older Blu shell |
The shell provides @blu/sdk at runtime. Keep the dependency range at the version Blu runs (blu check warns when it's below what it came with). |