@salesforce/vite-plugin-lwc-ui-bundle 11.13.1 → 11.14.0

package/docs/migration-guide.md

@@ -0,0 +1,334 @@
+# Migrating Platform LWC to an LWC UI Bundle
+
+This guide walks you through porting a Lightning Web Component that runs **inside a
+Salesforce org** to an **LWC UI Bundle** compiled off-platform with
+`@salesforce/vite-plugin-lwc-ui-bundle`. The build emits a static `dist/` (an
+`index.html` plus hashed `assets/*`, or a single inlined `dist/index.html` if you add
+`vite-plugin-singlefile`) that runs in any browser, an MCP host, or a Salesforce UI
+Bundle served from the `*.salesforce.app` domain.
+
+> **New to the plugin?** Read the [Consumer Guide](consumer-guide.md) first for the
+> baseline Vite setup. This guide focuses on what _changes_ when the component was
+> originally written for the platform, and links to the
+> [Limitations reference](limitations.md) for the features that don't come across.
+
+---
+
+## What actually changes
+
+A platform LWC and an LWC UI Bundle share the **same component source** — `.js`,
+`.html`, and `.css` files compile unchanged through `@lwc/rollup-plugin`. What
+changes is the _environment_ your component runs in:
+
+| On platform                                              | In an LWC UI Bundle                                                                             |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| The Lightning runtime mounts your component              | You mount it yourself in `bootstrap.js` via `createElement`                                     |
+| `@salesforce/*` modules resolve to live org services     | Scoped **providers** resolve them to generated JS (labels, i18n, gates, …)                      |
+| LDS wire adapters read from a reactive client-side store | Registered adapters dispatch through the Data SDK's host bridge to MCP tools; no reactive store |
+| Imperative Apex, LMS, and navigation are ambient         | They have **no provider** — you supply a stub or a GraphQL/REST replacement                     |
+| Metadata (`.js-meta.xml`) drives exposure and targets    | `.js-meta.xml` is ignored by the build; a `ui-bundle` manifest drives routing                   |
+
+The migration is therefore mostly about **the edges** of your component — how it gets
+mounted, how it gets data, and which platform capabilities it reaches for. The
+component logic in the middle usually ports verbatim.
+
+---
+
+## Migration at a glance
+
+1. [Inventory your dependencies](#step-1-inventory-your-dependencies) — find every
+   `import` that reaches the platform.
+2. [Set up the Vite project](#step-2-set-up-the-vite-project) — `vite.config.js`,
+   `index.html`, `bootstrap.js`.
+3. [Map each dependency](#step-3-map-each-dependency) to a provider, an SDK call, or
+   a stub.
+4. [Replace data access](#step-4-replace-data-access) — LDS/Apex → GraphQL or the
+   Data SDK.
+5. [Handle the unsupported edges](#step-5-handle-the-unsupported-edges) — LMS,
+   navigation, and other org-only APIs.
+6. [Build, run, and verify](#step-6-build-run-and-verify).
+
+---
+
+## Step 1: Inventory your dependencies
+
+Before touching config, list every non-relative import in your component tree. These
+are the imports that reach beyond your own `.js`/`.html` files and into the platform:
+
+```bash
+# From your LWC source root — list the platform-facing specifiers your bundle uses
+grep -rhoE "from \"(@salesforce/[^\"]+|lightning/[^\"]+|force/[^\"]+|aura)\"" \
+  force-app/main/default/lwc | sort -u
+```
+
+Sort what you find into four buckets — this table _is_ your migration plan:
+
+| Import pattern                                                                                        | Bucket             | Action                                                                               |
+| ----------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
+| `lwc`, `lightning/*` base components                                                                  | **Compiles as-is** | Nothing — bundled via `@lwc/rollup-plugin` + npm                                     |
+| `@salesforce/label/*`, `@salesforce/i18n/*`, `client`, `gate`, `accessCheck`                          | **Has a provider** | Add the matching `builtins.*` provider                                               |
+| `lightning/graphql`, registered LDS adapters                                                          | **Data access**    | See [Step 4](#step-4-replace-data-access)                                            |
+| `@salesforce/apex/*`, `lightning/messageService`, `lightning/navigation`, `force/*`, `aura`, `logger` | **Unsupported**    | Replace with GraphQL/REST or a stub — [Step 5](#step-5-handle-the-unsupported-edges) |
+
+Anything in the last two buckets needs a decision. The [Limitations
+reference](limitations.md) covers each unsupported module and its recommended
+workaround in detail.
+
+---
+
+## Step 2: Set up the Vite project
+
+Follow [Consumer Guide → Off-Platform Build](consumer-guide.md#off-platform-build) to
+add `vite.config.js`, `index.html`, and `bootstrap.js`. The one part worth calling out
+for migrations is that **you now own mounting**. On platform, the framework
+instantiated your top-level component; off-platform, `bootstrap.js` does:
+
+```js
+// bootstrap.js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+import App from "c/myApp"; // your existing root component, unchanged
+
+const el = createElement("c-my-app", { is: App });
+
+// Public @api properties the org used to set — set them here instead
+el.recordId = "001xx000003DGb2AAG";
+
+document.getElementById("app").appendChild(el);
+```
+
+Any `@api` property the org used to inject (`recordId`, `objectApiName`, flexipage
+attributes, etc.) now has no injector — set it explicitly when you mount, or read it
+from the URL/host. This is the single most common migration surprise.
+
+---
+
+## Step 3: Map each dependency
+
+For every import in the **"has a provider"** bucket, add the matching provider to
+your `vite.config.js`. The defaults cover the common set:
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: {
+    dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+    npm: ["lightning-base-components"],
+  },
+  providers: [
+    builtins.label(), // @salesforce/label/*
+    builtins.i18n(), // @salesforce/i18n/*
+    builtins.accessCheck(), // @salesforce/accessCheck/* (default false)
+    builtins.client(), // @salesforce/client/*
+    builtins.gate(), // @salesforce/gate/*   (default open)
+    builtins.primitiveUtils(), // lightning/primitiveUtils
+    builtins.lds(), // lightning/uiRecordApi, lightning/graphql, … (MCP-backed)
+  ],
+});
+```
+
+If you pass a `providers` array, it **replaces** the defaults — list every provider
+you need. Omit `providers` entirely to get the full default set: `label`, `i18n`,
+`accessCheck`, `client`, `gate`, `primitiveUtils`, and `lds`. Note there is no separate
+GraphQL provider — `lightning/graphql` is handled by `lds()`, whose default registry
+routes `graphql`/`executeMutation` to an MCP tool.
+
+A few provider-specific notes for migrated code:
+
+- **Labels** default to a human-readable fallback derived from the key
+  (`c.appTitle` → "App Title"). Port real values with
+  `builtins.label({ "c.appTitle": "My App" })`, or copy them from your
+  `CustomLabels.labels-meta.xml`. If you have a live data path and want translated
+  values at the user's locale, swap in `builtins.labelsGraphql()` instead — see
+  [Limitations → Custom Labels](limitations.md#custom-labels--static-default-or-live-via-graphql).
+- **Gates** default **open** and **access checks** default **false** off-platform.
+  If your component branches on either, pass overrides so its behavior matches the
+  org: `builtins.gate({ myGate: false })`, `builtins.accessCheck({ MyPerm: true })`.
+- **i18n** derives locale/currency from the browser via the `Intl` API; CLDR format
+  patterns use en-US defaults. Locale-identity is live, format specifics are static.
+
+---
+
+## Step 4: Replace data access
+
+This is the heart of most migrations. Platform LWC reaches org data three ways:
+**LDS wire adapters**, **imperative Apex**, and **`lightning/graphql`**. Off-platform,
+GraphQL is the through-line — it works in both a component wire and imperatively via
+the Data SDK.
+
+### LDS wire adapters (`getRecord`, `createRecord`, …)
+
+The `lds()` provider (on by default) routes a **registered** set of adapters to MCP
+tools. Out of the box that covers `getRecord`, `createRecord`, `updateRecord`
+(`lightning/uiRecordApi`) and `getObjectInfo_imperative` (`lightning/uiObjectInfoApi`). Code
+that uses only these ports **unchanged**:
+
+```js
+import { getRecord } from "lightning/uiRecordApi";
+
+// Same @wire on platform and off — the adapter resolves to an MCP tool off-platform
+@wire(getRecord, { recordId: "$recordId", fields: FIELDS })
+wiredRecord({ data, error }) { /* ... */ }
+```
+
+Two behavioral differences to plan for:
+
+- **No reactive store.** `subscribe()` on the imperative read shapes is a deliberate
+  no-op — the callback never fires. Data does not auto-refresh when it changes
+  elsewhere; call `refresh()` (on the `subscribable-refreshable` shape) or re-query.
+- **Only registered exports resolve.** Any LDS export not in the registry (e.g.
+  `getRelatedListRecords`, `getListUi`) passes through to normal `lightning/*`
+  resolution — which has no off-platform implementation, so the build fails to resolve
+  it. Register it with your own MCP tool via the `lds({ ... })` config, or replace the
+  call with GraphQL. See [Limitations → LDS](limitations.md#lds--partial-adapter-coverage-no-store).
+
+### Imperative Apex (`@salesforce/apex/MyClass.myMethod`)
+
+There is **no Apex provider**, and `@AuraEnabled` methods are **not** reachable
+off-platform. Migrate each imperative Apex call to one of:
+
+1. **GraphQL** — if the method just reads records, replace it with a UI API GraphQL
+   query (preferred; see below).
+2. **Apex REST** — expose the logic as an `@RestResource` and call it through the Data
+   SDK's `fetch`. Budget time to build this surface for any business logic you can't
+   express as GraphQL.
+
+See [Limitations → Imperative Apex](limitations.md#imperative-apex-salesforceapexmyclassmymethod)
+for the `sdk.fetch?.()` snippet and the `@AuraEnabled`-vs-`@RestResource` distinction.
+
+### `lightning/graphql` and the Data SDK
+
+`lightning/graphql` keeps working via the default `builtins.lds()` registry — no
+separate provider, and `@wire(graphql, …)` components port unchanged. The wire adapter
+dispatches through the MCP `graphqlQuery` tool. For imperative reads, use
+`@salesforce/platform-sdk` directly:
+
+```js
+import { createDataSDK, gql } from "@salesforce/platform-sdk";
+
+const sdk = await createDataSDK();
+const result = await sdk.graphql?.query({
+  query: gql`
+    query GetAccounts {
+      uiapi {
+        query {
+          Account(first: 10) {
+            edges {
+              node {
+                Id
+                Name {
+                  value
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `,
+});
+```
+
+`sdk.graphql?.query(...)` resolves against whatever surface the bundle runs on — a real
+MCP host's bridge, or the authenticated same-origin session on `*.salesforce.app`. Where
+each data path gets live data (and why a bundle on any other origin `401`s) is covered in
+[Limitations → Data access & auth](limitations.md#data-access-and-authentication).
+
+For **local development without a real host**, install a guarded host-bridge mock in
+your entry script (on ChatGPT that's a `window.openai.callTool` shim) so
+`@wire(graphql)` / `@wire(getRecord)` return data — see
+[Consumer Guide → Step 4: `bootstrap.js`](consumer-guide.md#step-4-create-bootstrapjs).
+(`lwcProxy()` is a separate, optional companion plugin — it forwards `/services/*` for
+_legacy_ `lightning/*` modules that call REST directly, not for the MCP-backed LDS and
+GraphQL adapters.)
+
+---
+
+## Step 5: Handle the unsupported edges
+
+Some platform capabilities have no off-platform equivalent. The repo's convention is
+a **hand-written stub** wired through the plugin's `stubs` option — the same pattern
+the [`lwc-records` example](../../../examples/lwc-axl/lwc-records) uses for
+`force/navigation`, `aura`, and `logger`.
+
+Each unsupported capability has a recommended stub or replacement documented in the
+Limitations reference — this step is about wiring them through the plugin's `stubs`
+option. The pattern is the same for each: point the specifier at a hand-written stub
+file that exports the shapes your code imports.
+
+```js
+// vite.config.js — one entry per unsupported specifier
+lwcVitePlugin({
+  stubs: {
+    "lightning/navigation": "src/stubs/navigation.js",
+    "lightning/messageService": "src/stubs/message-service.js",
+    aura: "src/stubs/aura.js",
+    "force/someModule": "src/stubs/some-module.js",
+  },
+});
+```
+
+For the actual stub contents and per-module guidance:
+
+- **Navigation** (`lightning/navigation`, `force/navigation`) — no-op `NavigationMixin`,
+  then decide per call site: [Limitations → Navigation](limitations.md#navigation-lightningnavigation-forcenavigation).
+- **Lightning Message Service** (`lightning/messageService`) — `EventTarget`-backed bus
+  for same-bundle messaging, host bridge across surfaces:
+  [Limitations → LMS](limitations.md#lightning-message-service-lightningmessageservice).
+- **`aura`, `logger`, `force/*` and other core-only modules** — export just the bindings
+  your code imports (often no-ops): [Limitations → Aura and other `force/*`](limitations.md#aura-and-other-force--core-only-modules).
+
+If the build fails with `Rollup failed to resolve import "force/someModule"` (or
+`aura`), that specifier needs a stub. The `lwc-records` example ships real stubs for
+`force/navigation`, `aura`, and `logger`.
+
+---
+
+## Step 6: Build, run, and verify
+
+```bash
+npm run build     # → dist/ (index.html + assets/*, or a single dist/index.html
+                  #   if you added vite-plugin-singlefile)
+open dist/index.html
+
+npm run dev       # dev server with live reload (+ lwcProxy for live data)
+```
+
+A migration is done when:
+
+- The bundle **builds** with no unresolved imports (unresolved = a dependency you
+  haven't yet mapped to a provider, SDK call, or stub — go back to Step 3).
+- Every `@api` the org used to set is set at mount time or read from the host/URL.
+- Data reads succeed against your target surface (mock, `lwcProxy` dev, or a
+  `*.salesforce.app`-served deployed bundle).
+- Behavior that branched on gates/access checks matches the org, given your provider
+  overrides.
+
+---
+
+## Common migration errors
+
+| Symptom                                                      | Cause                                              | Fix                                                                     |
+| ------------------------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------- |
+| `Rollup failed to resolve import "@salesforce/apex/…"`       | No Apex provider                                   | Migrate to GraphQL or Apex REST ([Step 4](#step-4-replace-data-access)) |
+| `Rollup failed to resolve import "lightning/navigation"`     | No navigation provider                             | Add a stub ([Step 5](#step-5-handle-the-unsupported-edges))             |
+| `Rollup failed to resolve import "force/…"`                  | Core-only module                                   | Add a stub via `stubs`                                                  |
+| `@wire(getRelatedListRecords)` builds but returns nothing    | Adapter not in the `lds()` registry                | Register an MCP tool or replace with GraphQL                            |
+| Wire data never refreshes                                    | `subscribe()` is a no-op off-platform              | Call `refresh()` or re-query explicitly                                 |
+| `Cannot read properties of undefined (reading 'isOpen')`     | Missing `gate()` provider (base components use it) | Add `builtins.gate()`                                                   |
+| Component mounts but is missing data it used to get for free | `@api` no longer injected by the platform          | Set the property in `bootstrap.js`                                      |
+| Deployed bundle `401`s on `/services/data/*`                 | Served from a non-`salesforce.app` origin          | Serve from `*.salesforce.app`, or use `lwcProxy` in dev                 |
+
+---
+
+## Reference
+
+- [Consumer Guide](consumer-guide.md) — baseline Vite setup and local-dev options
+- [Limitations & Unsupported Features](limitations.md) — the full constraint reference
+- [`lwc-records` example](../../../examples/lwc-axl/lwc-records) — real stubs for
+  `force/navigation`, `aura`, `logger`
+- [`@salesforce/platform-sdk`](../../sdk/platform-sdk/README.md) — GraphQL + REST data access
+  </content>
+  </invoke>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "11.13.1",
+  "version": "11.14.0",
   "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Salesforce",
@@ -49,7 +49,7 @@
     "skills"
   ],
   "scripts": {
-    "build": "vite build && vite build --mode runtime-lds && vite build --mode runtime-labels-graphql",
+    "build": "vite build && vite build --mode runtime-lds && vite build --mode runtime-labels-graphql && vite build --mode runtime-platform-graphql",
     "clean": "rm -rf dist",
     "dev": "vite build --watch",
     "test": "vitest run",
@@ -74,9 +74,9 @@
   },
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/platform-sdk": "^11.13.1",
+    "@salesforce/platform-sdk": "^11.14.0",
     "@salesforce/state-managers-uiapi": "^0.31.0",
-    "@salesforce/ui-bundle": "^11.13.1",
+    "@salesforce/ui-bundle": "^11.14.0",
     "lwc": "^9.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
@@ -100,7 +100,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.6",
     "@conduit-client/command-base": "3.19.6",
-    "@salesforce/platform-sdk": "^11.13.1",
+    "@salesforce/platform-sdk": "^11.14.0",
     "@types/ws": "^8.5.12",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",

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

@@ -157,7 +157,15 @@ Starting from the root component, trace the dependency tree:
      providers because base components use these modules internally even
      if user code doesn't
    - `@salesforce/gate/*`, `@salesforce/accessCheck/*` → handled by
-     those providers
+     those providers (accessCheck deny-defaults to `false`, no per-name
+     config required)
+   - `@salesforce/userPermission/<Name>`, `@salesforce/customPermission/<Name>`
+     → **collect every `<Name>`.** These are named per-user permissions:
+     the default `platformGraphql()` provider **fails the build** unless
+     each imported name has a first-paint value declared in
+     `userPermissionDefaults` / `customPermissionDefaults`. Record the
+     exact names so Step 7 can generate them (default them to `false`
+     unless the user says otherwise). See `known-pitfalls.md#17`.
    - `@salesforce/i18n/*` → `i18n` provider
    - `@salesforce/client/*` → `client` provider (provides `formFactor`
      based on viewport width)
@@ -227,6 +235,13 @@ Check in this order:
      present (the default registry covers all three specifiers)
    - Step 4 found any `@salesforce/i18n/*` → `builtins.i18n()` must be
      present
+   - Step 4 found any `@salesforce/userPermission/<Name>` or
+     `@salesforce/customPermission/<Name>` → the default
+     `platformGraphql()` provider must declare a first-paint value for
+     **each** name in `userPermissionDefaults` / `customPermissionDefaults`,
+     or the build throws. Use the `defaultProviders({ platformGraphql: {…} })`
+     helper so the rest of the registry stays default. See
+     `references/known-pitfalls.md#17`.
    - Step 4 found any `@salesforce/client/*` → `builtins.client()` must
      be present
    - `modules.npm` includes `lightning-base-components` (or
@@ -465,6 +480,34 @@ Adapt based on earlier findings:
 
 - Set `dirs` for the detected project structure (SFDX vs namespaced).
 - Populate `builtins.label({...})` with values from Step 6.
+- **Declare a first-paint value for every named permission Step 4 found.**
+  Each `@salesforce/userPermission/<Name>` / `@salesforce/customPermission/<Name>`
+  import needs an entry, or the build throws (`known-pitfalls.md#17`).
+  Prefer the `defaultProviders()` helper so you configure only this while
+  keeping the rest of the default registry:
+
+  ```js
+  import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+  lwcVitePlugin({
+    modules: {
+      /* ... */
+    },
+    providers: defaultProviders({
+      platformGraphql: {
+        userPermissionDefaults: { ApiEnabled: false, CustomizeApplication: false },
+        customPermissionDefaults: { My_Custom_Perm: false },
+      },
+    }),
+  });
+  ```
+
+  Default each to `false` unless the user wants a `true` first paint; note
+  the resolved org value only reaches the DOM if the component imports the
+  module's `subscribe()` export (keep a plain default import if the same
+  source also deploys on-platform). `@salesforce/accessCheck/*` needs no
+  such config — it deny-defaults to `false`.
+
 - Include `builtins.primitiveUtils()` if using `lightning-base-components`.
 - Include `builtins.lds()` if any component uses `lightning/uiRecordApi`,
   `lightning/uiObjectInfoApi`, `lightning/graphql`, or any of the

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

@@ -440,3 +440,60 @@ the plugin with `livePreview({ debug: true })` (or run with plugin debug
 logging) — it logs the underlying import error. Note the bridge is a
 local-dev convenience only; its absence never affects the compiled
 bundle.
+
+## 17. Build fails: named permission imported with no first-paint value
+
+**Symptom:** `vite build` (or `npm run dev`) fails with:
+
+```
+[platform-graphql] @salesforce/userPermission/ApiEnabled was imported but
+has no first-paint value configured. A permission is per-user runtime
+state, so the plugin refuses to silently render a fabricated `false`. …
+```
+
+**Cause:** A component imports `@salesforce/userPermission/<Name>` or
+`@salesforce/customPermission/<Name>`, but no value was declared for that
+name. A named permission is an assertion about **per-user runtime state**;
+a plain default import binds the value **once** at module-eval time and
+never updates on its own (only the module's `subscribe()` export does).
+So a silently-defaulted `false` would render a permanent, wrong answer —
+even when the GraphQL fetch **succeeds**. Rather than guess, the plugin
+requires you to state the value shown before the org responds. (This is
+**not** the same as `@salesforce/accessCheck/*`, which is a feature gate
+and safely deny-defaults to `false` — see pitfall #8.)
+
+**Fix:** Declare each imported permission's first-paint value via the
+`defaultProviders()` helper (keeps every other default in place):
+
+```js
+import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: {
+    /* ... */
+  },
+  providers: defaultProviders({
+    platformGraphql: {
+      userPermissionDefaults: { ApiEnabled: false, CustomizeApplication: false },
+      customPermissionDefaults: { My_Custom_Perm: false },
+    },
+  }),
+});
+```
+
+Use `false` unless you have a specific reason to render `true` before the
+fetch resolves. To reflect the **resolved** org value in the DOM, import
+the module's `subscribe(callback)` export and assign to a reactive field:
+
+```js
+import apiEnabled, { subscribe } from "@salesforce/userPermission/ApiEnabled";
+// this.apiEnabled = apiEnabled;                    // first paint (configured)
+// connectedCallback() { subscribe(v => this.apiEnabled = v); }  // corrects in DOM
+```
+
+If the same component must also deploy on-platform (where the scoped
+module has no `subscribe` export), keep the plain default import.
+
+**Prevention:** SKILL.md Step 4 flags every `@salesforce/userPermission/*`
+and `@salesforce/customPermission/*` import so the generated config
+declares its first-paint value up front.