@salesforce/vite-plugin-lwc-ui-bundle 1.135.0 → 2.1.0

package/skills/setup-lwc-vite-plugin/SKILL.md

@@ -75,8 +75,18 @@ Surface this early:
 > A) Upgrade Node (recommended — `nvm install 20.19` or `22`)
 > B) Pin `vite@^7` and a compatible `@lwc/rollup-plugin` major"
 
+**Stop here.** Report the detected layout and the Node decision, then
+wait for the user to answer. Do **not** bundle Step 2's chat-wrapper
+question into the same turn — a misdetection in Step 1 cascades into
+every later decision, so the user needs a clean moment to confirm or
+correct before anything else lands.
+
 ### Step 2: Ask about chat wrappers
 
+Only start this step **after** Step 1 has been answered and resolved.
+Ask the chat-wrapper question in its own turn — don't stack it on top
+of Step 1's findings report.
+
 If the project will run inside a ChatGPT/MCP host (tool output drives
 the UI), components need a thin chat-aware wrapper + mapper. The wrapper
 reads tool output from the host, the mapper normalizes it into the
@@ -162,11 +172,63 @@ Report what you found — plainly, so the user can correct misdetections:
 > - 3 label imports: `c.appTitle`, `c.greeting`, `c.save`
 > - Uses `lightning-card` → needs lightning-base-components + the
 >   gate/accessCheck/primitiveUtils providers
-> - Uses `lightning/graphql` → needs `builtins.lds()` (graphql specifiers
->   are registered by default) + a `graphqlQuery` mock branch in
->   `bootstrap.js`
-> - Uses `lightning/uiRecordApi` → needs `builtins.lds()` + a
->   `getRecordMcpTool` mock branch"
+> - Uses `lightning/graphql` → needs `builtins.lds()` provider (graphql
+>   specifiers are registered by default) + the `@conduit-client/*` LDS
+>   runtime peers (verified after install in Step 8.1) + a `graphqlQuery`
+>   mock branch in `bootstrap.js`
+> - Uses `lightning/uiRecordApi` → needs `builtins.lds()` provider + the
+>   `@conduit-client/*` LDS runtime peers + a `getRecordMcpTool` mock
+>   branch"
+
+### Step 4.5: Verify existing `vite.config.js` against findings
+
+If `vite.config.js` already exists (Step 1 noted whether it does), open it
+now and cross-check against what Step 4 found. This catches the silent-
+failure case where a project builds successfully but wire adapters and
+scoped imports return `undefined` at runtime because the `providers` array
+is missing or incomplete.
+
+Check in this order:
+
+1. **Does `lwcVitePlugin({...})` include a `providers` array at all?**
+   If not, flag it. Without the array, every `@salesforce/*` import returns
+   `undefined` — labels, gates, access checks, i18n, client — even though
+   the build succeeds. See `references/known-pitfalls.md#11`.
+
+2. **For each finding from Step 4, verify the matching provider is present:**
+   - Step 4 found `@salesforce/label/*` usage → `builtins.label({...})` must be in `providers`
+   - Step 4 found `@wire(graphql)`, `executeMutation`, or any `lightning/graphql` import →
+     `builtins.lds()` must be present (graphql specifiers are in the default registry)
+   - Step 4 found `@wire(getRecord)` from `lightning/uiRecordApi` →
+     `builtins.lds()` must be present (one `builtins.lds()` covers both)
+   - Step 4 found any `@salesforce/i18n/*` → `builtins.i18n()` must be
+     present
+   - Step 4 found any `@salesforce/client/*` → `builtins.client()` must
+     be present
+   - `modules.npm` includes `lightning-base-components` (or
+     `lwc-components-lightning`) → `builtins.gate()`,
+     `builtins.accessCheck()`, `builtins.primitiveUtils()` must all be
+     present. Base components use these modules internally even if user
+     code doesn't.
+
+3. **Report the gaps explicitly** before proceeding to later steps:
+
+   > "Your `vite.config.js` exists but its `providers` array is missing:
+   >
+   > - `builtins.label({...})` — Step 4 found 3 `@salesforce/label/*` imports
+   > - `builtins.lds()` — Step 4 found `@wire(graphql)` / `executeMutation` in `c/recordDetail`
+   > - `builtins.gate()`, `builtins.accessCheck()`, `builtins.primitiveUtils()` — `lightning-base-components` is in `modules.npm` and needs these
+   >
+   > I'll add these in Step 7. The build may currently succeed even with
+   > these missing, but wire adapters and labels will fail silently at
+   > runtime."
+
+4. **If the existing `providers` array is complete**, say so and move on.
+
+Do not skip this verification. A build that compiles fine but has no
+providers registered is the single most common failure mode for projects
+that already have a partial config — the compiler doesn't care, but the
+runtime silently returns `undefined` for everything.
 
 ### Step 5: Decide the runtime mode
 
@@ -318,8 +380,8 @@ builtins.lds(),                         // default registry:
 // unmentioned entries (e.g. `getRecord`, `createRecord`) are preserved.
 builtins.lds({
   "lightning/graphql": {
-    graphql: { type: "graphql-wire", toolName: "myGraphqlTool" },
-    executeMutation: { type: "graphql-mutation", toolName: "myGraphqlTool" },
+    graphql: { type: "graphql-wire", mcp: { toolName: "myGraphqlTool" } },
+    executeMutation: { type: "graphql-mutation", mcp: { toolName: "myGraphqlTool" } },
   },
 }),
 ```
@@ -340,7 +402,7 @@ Adapt based on earlier findings:
 
 - `builtins.lds()` default for `lightning/uiRecordApi.getRecord`:
   `getRecordMcpTool`. Override via
-  `builtins.lds({ "lightning/uiRecordApi": { getRecord: { type: "wire", toolName: "..." } } })`.
+  `builtins.lds({ "lightning/uiRecordApi": { getRecord: { type: "wire", mcp: { toolName: "..." } } } })`.
 - `builtins.lds()` default for `lightning/graphql` (both `graphql` wire
   and `executeMutation`): `graphqlQuery`. Override by registering the
   specifier explicitly — see example above.
@@ -387,12 +449,79 @@ Only add these if the component tree inspection reveals a need:
   system. Useful when an npm package has its own label definitions that
   shouldn't be intercepted.
 - **`ignorePatterns`**: Specifier prefixes that providers should never
-  intercept. Defaults include `@salesforce/sdk-*` and `@salesforce/core`.
+  intercept. Defaults include `@salesforce/sdk-*`, `@salesforce/platform-sdk-*`, and `@salesforce/core`.
 
 ### Step 8: Install and build
 
 ```bash
 npm install
+```
+
+#### Step 8.1: Verify LDS runtime peers (only if LDS is in use)
+
+Run this check **only** if Step 4 found actual usage of any of:
+
+- `lightning/graphql` with real `@wire(graphql)`, `executeMutation`, or
+  graphql-imperative calls
+- `lightning/uiRecordApi` with real `@wire` usage of `getRecord` /
+  `createRecord` / `updateRecord`
+- `lightning/uiObjectInfoApi` with real usage
+
+If none of the above are in the component tree, skip this sub-step
+entirely — the LDS runtime is never loaded and the peers don't matter.
+
+**Why this check exists:** the plugin's `dist/providers/lds/runtime.js`
+statically imports three `@conduit-client/*` packages at build time.
+Depending on the plugin version, these may ship as the plugin's own
+`dependencies`/`optionalDependencies`, or may be left undeclared (as of
+`@salesforce/vite-plugin-lwc-ui-bundle@1.135.0`). The skill does not
+need to know which — it just verifies they are resolvable in the
+consumer's `node_modules` after install, regardless of how they got
+there.
+
+**Check:**
+
+```bash
+node -e "
+  const peers = [
+    '@conduit-client/service-bindings-imperative',
+    '@conduit-client/service-bindings-lwc',
+    '@conduit-client/utils'
+  ];
+  const missing = peers.filter(p => {
+    try { require.resolve(p); return false; }
+    catch { return true; }
+  });
+  if (missing.length) {
+    console.error('Missing LDS runtime peers:', missing.join(', '));
+    process.exit(1);
+  } else {
+    console.log('LDS runtime peers OK');
+  }
+"
+```
+
+**If any are missing**, install the set as consumer `dependencies` (not
+`@salesforce/ui-bundle` — that package does not pull these three
+transitively and installing it does not resolve the error):
+
+```bash
+npm install --save \
+  @conduit-client/service-bindings-imperative@^3 \
+  @conduit-client/service-bindings-lwc@^3 \
+  @conduit-client/utils@^3
+```
+
+Re-run the check. See `references/known-pitfalls.md#13` for the full
+background.
+
+**If all three are already present** (e.g., a future plugin version
+ships them as its own deps, or a sibling package already pulled them
+in), do nothing — no lockfile churn, no duplicate entries.
+
+#### Step 8.2: Build
+
+```bash
 npm run build
 ```
 
@@ -412,6 +541,8 @@ frequent issues have symptoms that map directly to specific entries:
 - "No matching version found for \<pkg\>" → pitfall #2 (stale dep pins)
 - Missing `isOpen` / missing `lightning/button` → pitfalls #8 / #6
 - `force/someModule` not resolved → pitfall #9
+- `Rollup failed to resolve import "@conduit-client/..."` → pitfall #13
+  (LDS runtime peers missing; Step 8.1 was skipped or failed silently)
 - Component renders but unstyled → missing SLDS CSS import in
   `bootstrap.js`
 

package/skills/setup-lwc-vite-plugin/references/bootstrap-js-patterns.md

@@ -21,7 +21,7 @@ bundle, so the guard short-circuits and real host calls run.
 
 Do **not** expect `npm run build && open dist/index.html` to render mock
 data. Rollup hoists module-init code to the top of the bundle, which
-means `@salesforce/sdk-chat`'s `detectSurface()` runs _before_ the
+means `@salesforce/platform-sdk-chat`'s `detectSurface()` runs _before_ the
 `main.js` / `bootstrap.js` body executes the `if (!window.openai?.
 callTool)` block. The SDK caches surface = `"WebApp"` and never observes
 the mock — LDS / graphql wire adapters silently return empty data.

package/skills/setup-lwc-vite-plugin/references/known-pitfalls.md

@@ -74,8 +74,8 @@ the same custom name to both the provider and the mock:
 // vite.config.js — override the default "graphqlQuery" tool name
 builtins.lds({
   "lightning/graphql": {
-    graphql: { type: "graphql-wire", toolName: "myCustomGraphql" },
-    executeMutation: { type: "graphql-mutation", toolName: "myCustomGraphql" },
+    graphql: { type: "graphql-wire", mcp: { toolName: "myCustomGraphql" } },
+    executeMutation: { type: "graphql-mutation", mcp: { toolName: "myCustomGraphql" } },
   },
 }),
 
@@ -188,7 +188,7 @@ expects.
 the console. Dev server (`npm run dev`) works fine.
 
 **Cause:** Rollup hoists module-init code to the top of the bundle.
-`@salesforce/sdk-chat`'s top-level `const surface = detectSurface()`
+`@salesforce/platform-sdk-chat`'s top-level `const surface = detectSurface()`
 runs before `main.js` / `bootstrap.js` installs the mock, so the SDK
 caches `surface = "WebApp"` forever.
 
@@ -196,3 +196,128 @@ caches `surface = "WebApp"` forever.
 builds only target real MCP hosts (where the host sets `window.openai`
 before the bundle loads, so surface detection correctly resolves to
 `OpenAI`). See `bootstrap-js-patterns.md` for the full explanation.
+
+## 11. `providers` array missing entirely from `vite.config.js`
+
+**Symptom:** Build succeeds, but:
+
+- Labels render as `undefined` instead of their configured values
+- `@wire(graphql)` returns `undefined` or silently no-ops
+- `executeMutation()` fails with "No SDK found" or similar
+- Console shows `[scoped-module-providers] Unhandled import: @salesforce/...`
+  lines for every scoped import
+
+**Cause:** `lwcVitePlugin({ modules: {...} })` is called **without** a
+`providers: [...]` array. The plugin loads and compiles LWC just fine,
+but no scoped-module providers are registered — so every
+`@salesforce/label/*`, `@salesforce/i18n/*`, `@salesforce/gate/*`,
+`@salesforce/accessCheck/*`, `lightning/graphql`, `lightning/uiRecordApi`
+import resolves to `undefined` at runtime.
+
+**Fix:** Add the `providers: [...]` array with the appropriate builtins
+for what the component tree actually uses:
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: {
+    /* ... */
+  },
+  providers: [
+    builtins.label({
+      /* label overrides */
+    }),
+    builtins.i18n(),
+    builtins.client(),
+    // Required when using base components:
+    builtins.gate(),
+    builtins.accessCheck(),
+    builtins.primitiveUtils(),
+    // Add only if detected in the component tree:
+    builtins.lds(), // covers lightning/uiRecordApi and lightning/graphql
+  ],
+});
+```
+
+**Prevention:** SKILL.md Step 4.5 ("Verify existing `vite.config.js`
+against findings") catches this by cross-checking Step 4's tree-walk
+findings against the providers actually listed in the config.
+
+## 12. `lwc-components-lightning` vs `lightning-base-components`
+
+**Symptom:** Config references one package name but the project has the
+other installed, or provider behavior differs between environments.
+
+**Cause:** Both names appear in the wild:
+
+- `lightning-base-components` — the public npm package
+- `lwc-components-lightning` — an internal-workspace name that some
+  Salesforce projects resolve through private registries, aliases, or
+  monorepo linking. The public-registry entry for this name is a
+  security-reserved placeholder, not a real package.
+
+Both resolve to the same LWC base components and **require the same
+scoped providers**: `builtins.gate()`, `builtins.accessCheck()`,
+`builtins.primitiveUtils()`.
+
+**Fix:** Use whichever package your project already depends on. For
+public-facing consumers, use `lightning-base-components`. In either
+case, make sure the three providers above are in the `providers` array
+whenever the package name is in `modules.npm`.
+
+## 13. Missing `@conduit-client/*` peers for `builtins.lds()`
+
+**Symptom:** `vite build` fails with:
+
+```
+Rollup failed to resolve import "@conduit-client/service-bindings-imperative/v1"
+  from "\0sf-lds-adapter:lightning/graphql"
+```
+
+(or `service-bindings-lwc`, or `utils` — errors cascade one at a time as
+each is resolved.)
+
+**Cause:** The plugin's LDS runtime
+(`node_modules/@salesforce/vite-plugin-lwc-ui-bundle/dist/providers/lds/runtime.js`)
+statically imports three `@conduit-client/*` packages. Depending on the
+plugin version, these may be declared as the plugin's own
+`dependencies` / `optionalDependencies`, or may be left undeclared (as
+of `@salesforce/vite-plugin-lwc-ui-bundle@1.135.0`). The plugin reads
+`runtime.js` as a string at init, so nothing resolves until a consumer
+module imports `lightning/graphql`, `lightning/uiRecordApi`, or
+`lightning/uiObjectInfoApi` — then Rollup has to resolve the
+conduit-client imports in the consumer's `node_modules`, where they may
+be missing.
+
+The packages **are** publicly published on `registry.npmjs.org`; this
+is a missing-peer-declaration issue in the plugin for the plugin
+versions that don't ship them, not a registry / auth issue.
+
+**Fix (consumer side, works against any plugin version):** when a
+component actually imports `lightning/graphql`,
+`lightning/uiRecordApi`, or `lightning/uiObjectInfoApi`, install the
+three packages directly:
+
+```bash
+npm install --save \
+  @conduit-client/service-bindings-imperative@^3 \
+  @conduit-client/service-bindings-lwc@^3 \
+  @conduit-client/utils@^3
+```
+
+If no component imports those specifiers, the packages are not
+needed — omit them AND omit `builtins.lds()` from the `providers`
+array.
+
+**Forward compatibility:** if a future plugin version adds these to its
+own `dependencies` / `optionalDependencies`, they will already be
+present after `npm install @salesforce/vite-plugin-lwc-ui-bundle` and
+Step 8.1's post-install check becomes a no-op — it simply observes that
+the packages are already resolvable and skips the additional install.
+No skill change needed.
+
+**Prevention:** SKILL.md Step 8.1 ("Verify LDS runtime peers") runs the
+`require.resolve()` check after `npm install` and installs the three
+packages only when they are actually missing AND the component tree
+uses LDS specifiers.