@salesforce/vite-plugin-lwc-ui-bundle 1.131.2 → 1.132.0

package/docs/consumer-guide.md

@@ -0,0 +1,429 @@
+# Compiling LWC Components Off-Platform with @salesforce/vite-plugin-lwc-ui-bundle
+
+This guide walks you through adding `@salesforce/vite-plugin-lwc-ui-bundle` to an
+existing LWC project so you can compile your components into a single self-contained
+`dist/index.html` that runs in any browser — no Salesforce org required.
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 20.0.0
+- **LWC components** in a project directory (standard SFDX project or custom layout)
+- **Salesforce CLI** (`sf`) — only needed if connecting to a real org (Tier 2)
+
+---
+
+## Overview
+
+The plugin supports two tiers of usage:
+
+| Tier                            | What You Get                               | Org Required?      |
+| ------------------------------- | ------------------------------------------ | ------------------ |
+| **Tier 1: Off-Platform Build**  | Static bundle with mock data, labels, i18n | No                 |
+| **Tier 2: Live Org Connection** | Real GraphQL queries, live Salesforce data | Yes (via `sf` CLI) |
+
+Start with Tier 1. Add Tier 2 later if your components use `lightning/graphql` or
+need live data.
+
+---
+
+## Tier 1: Off-Platform Build
+
+### Project Structure
+
+You need to add **3 files** to your project and update `package.json`:
+
+```
+my-lwc-project/
+├── force-app/main/default/lwc/    ← your existing LWC components
+│   ├── myApp/
+│   │   ├── myApp.js
+│   │   ├── myApp.html
+│   │   └── myApp.js-meta.xml
+│   └── myComponent/
+│       ├── myComponent.js
+│       ├── myComponent.html
+│       └── myComponent.js-meta.xml
+├── bootstrap.js                    ← NEW: mounts your root component
+├── index.html                      ← NEW: entry point
+├── vite.config.js                  ← NEW: plugin configuration
+└── package.json                    ← UPDATED: add deps and scripts
+```
+
+### Step 1: Install Dependencies
+
+**Option A — Quick install command:**
+
+```bash
+npm install @salesforce/vite-plugin-lwc-ui-bundle @lwc/rollup-plugin vite vite-plugin-singlefile --save-dev
+npm install lwc @salesforce-ux/design-system lightning-base-components
+```
+
+**Option B — Add to `package.json` manually, then `npm install`:**
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@salesforce-ux/design-system": "^2.29.1",
+    "lightning-base-components": "^1.28.17-alpha",
+    "lwc": "^9.0.0"
+  },
+  "devDependencies": {
+    "@lwc/rollup-plugin": "^9.0.0",
+    "@salesforce/vite-plugin-lwc-ui-bundle": "^1.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}
+```
+
+> **Important:** Add `"type": "module"` to your `package.json` if it is not already
+> present. This is required for Vite's ESM-based config.
+
+> **Note:** `@lwc/rollup-plugin` is a required peer dependency of the plugin.
+> `lightning-base-components` is only needed if your components use `lightning/*`
+> base components (e.g., `lightning-card`, `lightning-button`).
+
+### Step 2: Create `vite.config.js`
+
+```js
+import { defineConfig } from "vite";
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  build: {
+    target: "esnext",
+    minify: false,
+  },
+  plugins: [
+    lwcVitePlugin({
+      modules: {
+        // Flat SFDX structure: specify { path, namespace }
+        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+
+        // Include if your components use lightning/* base components
+        npm: ["lightning-base-components"],
+      },
+      providers: [
+        builtins.label(),
+        builtins.i18n(),
+        builtins.client(),
+        builtins.gate(),
+        builtins.accessCheck(),
+      ],
+    }),
+    viteSingleFile(),
+  ],
+});
+```
+
+#### Component Directory Configuration
+
+The plugin supports two directory structures:
+
+**Flat SFDX structure** (standard Salesforce DX — most common):
+
+```
+force-app/main/default/lwc/
+  myApp/
+    myApp.js
+```
+
+Use `{ path, namespace }` to assign a namespace:
+
+```js
+dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }];
+```
+
+Components are importable as `c/myApp` and rendered as `<c-my-app>`.
+
+**Namespaced structure** (off-core projects):
+
+```
+src/lwc/
+  myNamespace/
+    myComponent/
+      myComponent.js
+```
+
+Omit `namespace` — the sub-directory name becomes the namespace:
+
+```js
+dirs: ["src/lwc"];
+```
+
+Components are importable as `myNamespace/myComponent`.
+
+#### Configuring Labels
+
+The `builtins.label()` provider handles `@salesforce/label/*` imports. How you
+configure it depends on your project:
+
+**SFDX project with `CustomLabels.labels-meta.xml`:**
+
+Copy label values from your XML into the label provider config:
+
+```js
+builtins.label({
+    "c.appTitle": "My LWC App",
+    "c.saveButton": "Save",
+    "c.cancelButton": "Cancel",
+}),
+```
+
+**Off-core project (no labels XML):**
+
+Pass label key-value pairs directly. If no override is provided for a key, the
+plugin returns a human-readable fallback derived from the key name (e.g.,
+`c.appTitle` renders as "App Title").
+
+```js
+// Minimal — uses fallback display for all labels
+builtins.label(),
+
+// With explicit overrides
+builtins.label({
+    "c.appTitle": "My App Title",
+    "c.greeting": "Welcome!",
+}),
+```
+
+#### Why `gate()` and `accessCheck()` Are Needed
+
+Even if your components don't use `@salesforce/gate/*` or `@salesforce/accessCheck/*`
+directly, **`lightning-base-components` does internally**. Without these providers,
+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`.
+
+### Step 3: Create `index.html`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My LWC App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      globalThis.lwcRuntimeFlags = { DISABLE_SYNTHETIC_SHADOW: true };
+    </script>
+    <script type="module" src="/bootstrap.js"></script>
+  </body>
+</html>
+```
+
+### Step 4: Create `bootstrap.js`
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+
+// Import your root component using its LWC specifier: <namespace>/<componentName>
+import App from "c/myApp";
+
+// Mount it — tag name is the kebab-case version of the specifier
+const el = createElement("c-my-app", { is: App });
+document.getElementById("app").appendChild(el);
+```
+
+Replace `c/myApp` and `c-my-app` with your actual root component name.
+
+### Step 5: Build and Test
+
+```bash
+# Production build — outputs dist/index.html (single-file bundle)
+npm run build
+
+# Open directly in browser
+open dist/index.html
+
+# Or use dev server with live reload
+npm run dev
+# Open http://localhost:5173
+
+# Or preview the production build
+npm run preview
+# Open http://localhost:4173
+```
+
+---
+
+## Tier 2: Live Org Connection (lwcProxy)
+
+If your components use `lightning/graphql` or need live Salesforce data, add
+`lwcProxy()` to connect to a real org during development.
+
+### Prerequisites
+
+- Salesforce CLI installed and an org connected: `sf org display`
+- Additional packages: `@salesforce/sdk-data` and `@salesforce/ui-bundle`
+
+### Step 1: Install Additional Dependencies
+
+```bash
+npm install @salesforce/sdk-data @salesforce/ui-bundle
+```
+
+### Step 2: Update `vite.config.js`
+
+Add `lwcProxy()` before `lwcVitePlugin()` and add `builtins.lightningGraphql()`
+to providers:
+
+```js
+import { defineConfig } from "vite";
+import lwcVitePlugin, { builtins, lwcProxy } from "@salesforce/vite-plugin-lwc-ui-bundle";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  build: {
+    target: "esnext",
+    minify: false,
+  },
+  plugins: [
+    lwcProxy({ debug: true }),
+    // lwcProxy({ orgAlias: "my-org", debug: true }),  // explicit org
+    lwcVitePlugin({
+      modules: {
+        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+        npm: ["lightning-base-components"],
+      },
+      providers: [
+        builtins.label(),
+        builtins.i18n(),
+        builtins.client(),
+        builtins.gate(),
+        builtins.accessCheck(),
+        builtins.lightningGraphql(),
+      ],
+    }),
+    viteSingleFile(),
+  ],
+});
+```
+
+### Step 3: Update `bootstrap.js`
+
+Initialize the Data SDK before mounting your app. This requires top-level `await`
+(hence `target: "esnext"` in the vite config):
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+
+// Initialize SDK — lwcProxy() handles /services/* in the Vite dev server
+import { createDataSDK } from "@salesforce/sdk-data";
+try {
+  globalThis.__sfdc_sdk__ = await createDataSDK({ uiBundle: { basePath: "/" } });
+} catch (_err) {
+  globalThis.__sfdc_sdk__ = {};
+}
+
+// Import your root component
+import App from "c/myApp";
+
+const el = createElement("c-my-app", { is: App });
+document.getElementById("app").appendChild(el);
+```
+
+### Step 4: Run Dev Server
+
+```bash
+npm run dev
+# Terminal shows: [lwc-proxy] Connected to https://your-org.my.salesforce.com
+# Open http://localhost:5173
+```
+
+Components using `@wire(graphql, ...)` will now execute real GraphQL queries
+against your connected org. The proxy intercepts `/services/*` calls inside
+the Vite dev server — no separate proxy process needed.
+
+> **Note:** `lwcProxy()` works with `npm run dev` only. The production build
+> (`dist/index.html`) does not include the proxy — it's a static file. For
+> production use with live data, you need a separate API proxy or MCP server.
+
+---
+
+## Common Errors
+
+### `Cannot read properties of undefined (reading 'isOpen')`
+
+Missing `gate()` provider. `lightning-base-components` use gates internally.
+Add `builtins.gate()` to your providers array.
+
+### `Rollup failed to resolve import "lightning/button"`
+
+Your component uses a Lightning Base Component. Add to `vite.config.js`:
+
+```js
+modules: {
+    npm: ["lightning-base-components"],
+}
+```
+
+### `Top-level await is not available in the configured target environment`
+
+Your `bootstrap.js` uses top-level `await` (required for Data SDK). Add
+`target: "esnext"` to the build config:
+
+```js
+build: { target: "esnext" },
+```
+
+### `[scoped-module-providers] Unhandled import: @salesforce/label/...`
+
+Expected — the plugin returns the label key as display text by default.
+To provide specific label values:
+
+```js
+builtins.label({ "c.Save": "Save", "c.Cancel": "Cancel" }),
+```
+
+### `Rollup failed to resolve import "force/someModule"`
+
+Core-only module not available off-platform. Add a stub:
+
+```js
+// stubs/someModule.js
+export const someExport = () => {};
+```
+
+```js
+// vite.config.js
+lwcVitePlugin({ stubs: { "force/someModule": "./stubs/someModule.js" } });
+```
+
+### Component renders but looks unstyled
+
+Add SLDS import to `bootstrap.js`:
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+```
+
+---
+
+## Reference
+
+- **npm:** https://www.npmjs.com/package/@salesforce/vite-plugin-lwc-ui-bundle
+- **Source:** https://github.com/salesforce-experience-platform-emu/webapps/tree/main/packages/vite-plugin-lwc-ui-bundle
+- **User Guide:** https://github.com/salesforce-experience-platform-emu/webapps/blob/main/packages/vite-plugin-lwc-ui-bundle/docs/user-guide.md
+- **Example project:** https://git.soma.salesforce.com/sisi-zhang/my-lwc-app-test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "1.131.2",
+  "version": "1.132.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",
@@ -30,6 +30,14 @@
       "types": "./dist/providers/index.d.ts",
       "import": "./dist/providers/index.js"
     },
+    "./providers/lds": {
+      "types": "./dist/providers/lds/index.d.ts",
+      "import": "./dist/providers/lds/index.js"
+    },
+    "./providers/lightning-graphql": {
+      "types": "./dist/providers/lightning-graphql/index.d.ts",
+      "import": "./dist/providers/lightning-graphql/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -37,10 +45,11 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "docs",
+    "skills"
   ],
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && vite build --mode runtime-lds && vite build --mode runtime-lightning-graphql",
     "clean": "rm -rf dist",
     "dev": "vite build --watch",
     "test": "vitest run",
@@ -51,19 +60,25 @@
     "@lwc/rollup-plugin": "^9.0.0",
     "@salesforce/sdk-chat": "^1.123.0",
     "@salesforce/ui-bundle": "^1.123.0",
-    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "zod": "^3.23.8"
   },
   "peerDependenciesMeta": {
     "@salesforce/ui-bundle": {
       "optional": true
     }
   },
+  "dependencies": {
+    "es-module-lexer": "^1.7.0",
+    "magic-string": "^0.30.17"
+  },
   "devDependencies": {
-    "@salesforce/sdk-chat": "^1.131.2",
+    "@salesforce/sdk-chat": "^1.132.0",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.6"
+    "vitest": "^4.0.6",
+    "zod": "^3.23.8"
   },
   "engines": {
     "node": ">=20.0.0"