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

package/docs/consumer-guide.md

@@ -259,6 +259,21 @@ export default defineConfig({
 });
 ```
 
+**What is the `providers` array?** It is the list of resolvers for `@salesforce/*`
+scoped-module imports (`@salesforce/label/*`, `@salesforce/i18n/*`,
+`@salesforce/userPermission/*`, `@salesforce/gate/*`, …) that don't exist as
+real npm packages. Each `builtins.*()` returns a Vite plugin that intercepts one
+family of specifiers and generates the module the platform LWC compiler would
+otherwise provide.
+
+**You usually don't need it.** When you **omit** `providers` entirely, the plugin
+installs a default set that resolves labels, i18n, permissions, and access checks
+at runtime via GraphQL (see [GraphQL-backed scoped modules](#graphql-backed-scoped-modules-default)
+below). Pass `providers` only to opt a family **out** of the runtime fetch (e.g.
+`builtins.i18n()` for browser/`Intl`-derived locale identity, `builtins.label()`
+for static build-time labels) or to add extra config — the explicit list above
+shows the opt-out shape, not a required one.
+
 #### Component Directory Configuration
 
 The plugin supports two directory structures:
@@ -298,8 +313,22 @@ Components are importable as `myNamespace/myComponent`.
 
 #### Configuring Labels
 
-The `builtins.label()` provider handles `@salesforce/label/*` imports. How you
-configure it depends on your project:
+There are two providers for `@salesforce/label/*`:
+
+- **`builtins.labelsGraphql()` — the default.** Resolves labels at runtime via UI
+  API GraphQL through the Platform Data SDK (`createDataSDK()`), so labels reflect
+  the current user's translation. The SDK picks the transport per surface: a
+  direct session-authenticated GraphQL request in a full-page web app, or the
+  `window.openai` bridge in an MCP/ChatGPT host. Build-time values (or the
+  key-derived fallback) render until the runtime fetch resolves. Included
+  automatically when you omit the `providers` array.
+- **`builtins.label()` — static.** Resolves to a fixed build-time string. Use it
+  to opt out of runtime fetching (e.g. a pure off-core demo with no org).
+
+Both accept the same overrides object; `labelsGraphql` uses the overrides as the
+static fallback shown before/instead of a successful GraphQL fetch.
+
+How you configure labels depends on your project:
 
 **SFDX project with `CustomLabels.labels-meta.xml`:**
 
@@ -340,8 +369,95 @@ you'll get runtime errors like:
 Uncaught TypeError: Cannot read properties of undefined (reading 'isOpen')
 ```
 
-Always include `builtins.gate()` and `builtins.accessCheck()` when using
-`lightning-base-components`.
+Include `builtins.gate()` when using `lightning-base-components`. (When you omit
+the `providers` array entirely, the default set already covers these.)
+
+#### GraphQL-backed scoped modules (default)
+
+When you **omit** the `providers` array, these scoped modules resolve at runtime
+via UI API GraphQL through the Platform Data SDK (with build-time first-paint
+values):
+
+| Scoped module                          | GraphQL source (`uiapi.platform.*`) | Provider            | First-paint value                    |
+| -------------------------------------- | ----------------------------------- | ------------------- | ------------------------------------ |
+| `@salesforce/label/*`                  | `labels`                            | `labelsGraphql()`   | override or key-derived text         |
+| `@salesforce/i18n/*` (locale identity) | `i18n`                              | `platformGraphql()` | CLDR placeholder                     |
+| `@salesforce/userPermission/*`         | `userPermissions`                   | `platformGraphql()` | **required — you must configure it** |
+| `@salesforce/accessCheck/*`            | `userPermissions`                   | `platformGraphql()` | `false` (deny-by-default)            |
+| `@salesforce/customPermission/*`       | `customPermissions`                 | `platformGraphql()` | **required — you must configure it** |
+
+The generated modules export the first-paint value as `default` and an opt-in
+`subscribe(callback)` that fires with the resolved org value.
+
+##### Named permissions must be configured (no silent guess)
+
+A `@salesforce/userPermission/<Name>` or `@salesforce/customPermission/<Name>`
+import is an assertion about **per-user runtime state**. A plain default import
+binds the module's value **once** at module-eval time and never updates on its
+own — so if the plugin silently defaulted an unconfigured permission to `false`,
+your UI would render a permanent, wrong answer about what the current user can do
+(and it would be wrong even on the GraphQL **success** path, because a default
+import never re-reads the resolved value).
+
+Rather than guess, **the build fails** if you import a named permission without
+declaring the value it should show before the org responds:
+
+```
+[platform-graphql] @salesforce/userPermission/ApiEnabled was imported but has no
+first-paint value configured. …
+```
+
+Declare it with the `defaultProviders()` helper — which lets you configure this
+one provider while keeping every other default in place:
+
+```js
+import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: { dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }] },
+  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. `@salesforce/accessCheck/*` is exempt: it's a feature **gate**, so an
+unconfigured check safely deny-defaults to `false` (base components rely on this),
+though you can still override it.
+
+##### Reflecting the resolved value reactively (`subscribe`)
+
+The configured value is only the **first paint**. To show the real org value once
+the GraphQL fetch lands, import the module's `subscribe(callback)` export and
+assign to a reactive field — the callback fires immediately with the current value
+and again when the resolved value differs:
+
+```js
+import apiEnabled, { subscribe } from "@salesforce/userPermission/ApiEnabled";
+
+export default class extends LightningElement {
+  apiEnabled = apiEnabled; // first paint (your configured value)
+  connectedCallback() {
+    subscribe((v) => (this.apiEnabled = v)); // corrects in the DOM when the org responds
+  }
+}
+```
+
+> **Dual-deploy note:** the `subscribe` export exists only when the module is
+> served by this plugin. If the **same** component source must also deploy as
+> on-platform LWC metadata (where `@salesforce/userPermission/*` has no `subscribe`
+> export), keep a plain default import — it will render the configured first-paint
+> value off-core and the platform-resolved value on-core.
+
+i18n number/date **format** patterns and calendar data stay static (CLDR reference
+data, no org source). `@salesforce/gate/*` also stays static — its GraphQL field is
+UiTier-context-only and not reachable off-core. The static `builtins.i18n()` /
+`builtins.accessCheck()` / `builtins.label()` providers remain available for
+explicit opt-out.
 
 ### Step 3: Create `index.html`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "11.13.2",
+  "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.2",
+    "@salesforce/platform-sdk": "^11.14.0",
     "@salesforce/state-managers-uiapi": "^0.31.0",
-    "@salesforce/ui-bundle": "^11.13.2",
+    "@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.2",
+    "@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.