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

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

@@ -0,0 +1,242 @@
+---
+name: setup-lwc-vite-plugin
+description: >
+  Set up @salesforce/vite-plugin-lwc-ui-bundle in an LWC project so components
+  compile and run off-platform in a browser. Use this skill whenever someone wants
+  to: run LWC components outside Salesforce, build a static LWC bundle, add Vite
+  to an SFDX or LWC project, compile LWC for a browser, create a standalone LWC
+  app, set up an LWC dev server, or use vite-plugin-lwc-ui-bundle. Also use it
+  when the user mentions "off-platform LWC", "LWC bundle", "LWC without Salesforce",
+  "LWC without an org", "Vite + LWC", or "compile LWC off-core".
+---
+
+# Setup @salesforce/vite-plugin-lwc-ui-bundle
+
+This skill adds `@salesforce/vite-plugin-lwc-ui-bundle` to an existing LWC project,
+producing a single `dist/index.html` that runs in any browser without a Salesforce org.
+
+## What the plugin does
+
+It wraps the full LWC compilation pipeline behind a single Vite plugin: scoped module
+providers (labels, i18n, gates, etc.), Lightning npm resolution, missing CSS handling,
+and the Vite/LWC bridge. The output is a self-contained HTML file with all JS and CSS
+inlined.
+
+## Reference material
+
+The `references/consumer-guide.md` file contains exact file templates, dependency
+versions, and config snippets. Read it when you need to generate `vite.config.js`,
+`index.html`, `bootstrap.js`, or `package.json` updates. This skill tells you
+_when and why_ to use each piece; the consumer guide gives you the exact _what_.
+
+## Interactive Setup Flow
+
+Walk the user through these steps in order. Ask questions — don't assume.
+
+### Step 1: Detect the project
+
+LWC projects come in two layouts, and the directory structure determines how
+`modules.dirs` must be configured. Detecting the layout first avoids misconfigured
+imports that silently fail at build time.
+
+Check in order:
+
+1. `sfdx-project.json` in the project root → **SFDX project**. Components live at
+   `force-app/main/default/lwc/` in a flat structure where every component shares
+   the `c` namespace. Configure as `dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }]`.
+2. Directories matching `src/lwc/` or `modules/` → **off-core project**. Sub-directories
+   are namespaces (e.g., `src/lwc/myNs/myComponent/`). Configure as `dirs: ["src/lwc"]`.
+3. If neither found, ask the user where their LWC components live.
+
+Read `package.json` to understand what's already installed — avoid adding duplicate
+dependencies later.
+
+### Step 2: Ask for the root component
+
+The plugin compiles a tree starting from one root component that gets mounted in the
+HTML page. The user needs to tell you which one, since there's no reliable way to
+auto-detect the "main" component.
+
+List the discovered components and ask:
+
+> "Which component should be the root of your app? This is the one that gets
+> mounted in the HTML page."
+
+Present the component names as a numbered list for easy selection.
+
+### Step 3: Inspect the component tree
+
+This step drives every downstream decision: which providers to include, whether
+`lightning-base-components` is needed, and whether to offer Tier 2 (live org). Getting
+this right prevents cryptic build errors.
+
+Starting from the root component, trace the dependency tree:
+
+1. Read the root component's `.html` file — find all `c-*` tags (or other
+   namespace tags) to identify child components
+2. Recursively read each child component's `.js` and `.html`
+3. Collect all imports across the tree:
+   - `@salesforce/label/*` → label keys (need `builtins.label()`)
+   - `lightning/graphql` or `@wire(graphql` → needs GraphQL support
+   - `lightning/*` base components → needs `lightning-base-components` npm package,
+     plus `gate()`, `accessCheck()`, and `primitiveUtils()` providers because
+     base components use these modules internally even if user code doesn't
+   - `@salesforce/gate/*`, `@salesforce/accessCheck/*` → handled by providers
+   - `@salesforce/i18n/*` → i18n provider
+   - `@salesforce/client/*` → client provider (provides `formFactor` based on viewport width)
+   - `lightning/primitiveUtils` → primitiveUtils provider
+
+Report what you found:
+
+> "I traced your component tree from `c/app`. Here's what I found:
+>
+> - 5 components total
+> - 3 label imports: `c.appTitle`, `c.greeting`, `c.save`
+> - Uses `lightning-card` (needs lightning-base-components)
+> - Uses `lightning/graphql` (needs lwcProxy for live data)
+> - No gate/accessCheck imports in your code, but lightning-base-components
+>   uses them internally — I'll include those providers automatically."
+
+### Step 4: Decide the tier
+
+The plugin supports two tiers. This determines which dependencies and bootstrap
+code to generate.
+
+| 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 via `lwcProxy()`      | Yes (via `sf` CLI) |
+
+If GraphQL usage was detected in Step 3, ask:
+
+> "Your components use `lightning/graphql`. Do you want to connect to a real
+> Salesforce org for live data during development?
+>
+> A) Yes — I have an org connected via `sf` CLI (adds lwcProxy + Data SDK)
+> B) No — use mock data for now (GraphQL wire adapter returns empty results)"
+
+If no GraphQL detected, default to Tier 1 — there's no benefit to Tier 2 without
+GraphQL or live data needs.
+
+### Step 5: Resolve label values
+
+Labels need explicit values because the plugin can't read them from an org at build
+time. Getting them right here means the user sees realistic text immediately instead
+of placeholder keys.
+
+1. **SFDX project**: Check for `force-app/main/default/labels/CustomLabels.labels-meta.xml`.
+   If found, parse it and extract `<fullName>` → `<value>` pairs for the label
+   keys discovered in Step 3.
+2. **Off-core project or no labels XML**: For each label key found, use a
+   placeholder value derived from the key (e.g., `c.appTitle` → `"App Title"`).
+
+Tell the user what labels you found and the values you'll use:
+
+> "I found 3 label imports. Here are the values I'll configure:
+>
+> - `c.appTitle` → "My LWC App" (from CustomLabels.labels-meta.xml)
+> - `c.greeting` → "Welcome!" (from CustomLabels.labels-meta.xml)
+> - `c.save` → "Save" (fallback — not found in labels XML)
+>
+> You can change these in `vite.config.js` later."
+
+If no labels were found at all, still include `builtins.label()` with no overrides.
+The plugin returns a human-readable fallback for unknown keys, and
+`lightning-base-components` may use labels internally.
+
+### Step 6: Generate files
+
+Read `references/consumer-guide.md` for the exact file templates. Generate these
+files, adapting the templates based on what you learned in Steps 1-5:
+
+#### Files to create or update
+
+1. **`package.json`** — merge in dependencies and scripts (don't overwrite existing).
+   See "Step 1: Install Dependencies" in the consumer guide for the full dep list.
+   - Add `"type": "module"` if not present
+   - Only add `lightning-base-components` and `@salesforce-ux/design-system` if
+     the component tree uses `lightning/*` base components
+   - For Tier 2, also add `@salesforce/sdk-data` and `@salesforce/ui-bundle`
+
+2. **`vite.config.js`** — see "Step 2" in the consumer guide for the template.
+   Adapt based on your findings:
+   - Set `dirs` for the detected project structure (SFDX vs namespaced)
+   - Populate `builtins.label({...})` with values from Step 5
+   - Include `builtins.primitiveUtils()` if using `lightning-base-components`
+   - Include `builtins.lightningGraphql()` only if GraphQL was detected
+   - Remove `npm: ["lightning-base-components"]` if no base components used
+   - For Tier 2, add `lwcProxy()` before `lwcVitePlugin()` in the plugins array
+
+3. **`index.html`** — see "Step 3" in the consumer guide.
+
+4. **`bootstrap.js`** (project root) — see "Step 4" (Tier 1) or "Step 3" (Tier 2)
+   in the consumer guide. Replace the component name with the actual root from
+   Step 2. Remove the SLDS CSS import if `lightning-base-components` is not used.
+
+#### Advanced options (use only when needed)
+
+The plugin accepts additional options for complex projects. Only add these if the
+component tree inspection reveals a need:
+
+- **`stubs`**: Map bare module specifiers to stub files for core-only modules
+  not available off-platform (e.g., `{ "force/someModule": "./stubs/someModule.js" }`).
+  Needed when components import platform modules like `aura`, `logger`, or
+  `force/*` that don't exist outside Salesforce.
+- **`lwcOptions`**: Pass-through options for `@lwc/rollup-plugin` to configure
+  LWC compiler behavior (e.g., `{ enableDynamicComponents: true }`). Only needed
+  for projects using advanced LWC features like dynamic component creation.
+- **`passthroughRules`**: Let specific imports bypass the provider system. Each
+  rule has a `specifierPrefix` and `importerPattern` — when both match, the import
+  resolves normally. Useful when an npm package (like `lightning-base-components`)
+  has its own label definitions that shouldn't be intercepted by your label provider.
+- **`ignorePatterns`**: Specifier prefixes that providers should never intercept.
+  Defaults include `@salesforce/sdk-*` and `@salesforce/core`. Extend this if
+  you have imports that look like provider-handled patterns but should resolve
+  through normal Node module resolution.
+
+### Step 7: Install and build
+
+Run:
+
+```bash
+npm install
+npm run build
+```
+
+If the build succeeds, report the output file size and open it:
+
+```bash
+open dist/index.html
+```
+
+If the build fails, diagnose and fix. See the "Common Errors" section in
+`references/consumer-guide.md` for the full troubleshooting guide. The most
+frequent issues:
+
+- **`Cannot read properties of undefined (reading 'isOpen')`**: Missing `gate()`
+  or `accessCheck()` provider — `lightning-base-components` use gates internally.
+- **`Rollup failed to resolve import "lightning/button"`**: Missing
+  `npm: ["lightning-base-components"]` in modules config.
+- **`Unhandled import: @salesforce/label/...`**: Expected warning — the plugin
+  returns the key as display text. Add overrides to `builtins.label()` to customize.
+- **`Top-level await is not available`**: Missing `target: "esnext"` in build config.
+- **`Rollup failed to resolve import "force/someModule"`**: Core-only module. Add
+  a stub via the `stubs` option.
+- **Component renders but looks unstyled**: Missing SLDS CSS import in bootstrap.js.
+
+### Step 8: Test dev server (Tier 2 only)
+
+If lwcProxy was configured:
+
+```bash
+npm run dev
+```
+
+Confirm the terminal shows `[lwc-proxy] Connected to https://...`. Open
+`http://localhost:5173` and verify GraphQL queries return real data.
+
+## Reference
+
+- npm: https://www.npmjs.com/package/@salesforce/vite-plugin-lwc-ui-bundle
+- README: https://github.com/salesforce-experience-platform-emu/webapps/tree/main/packages/vite-plugin-lwc-ui-bundle
+- Consumer Guide: https://github.com/salesforce-experience-platform-emu/webapps/blob/main/packages/vite-plugin-lwc-ui-bundle/docs/consumer-guide.md

package/dist/providers/lightning-graphql.d.ts

@@ -1,17 +0,0 @@
-import { Provider } from '../types';
-export interface LightningGraphqlOptions {
-    /**
-     * Name of the MCP tool to call for GraphQL query execution.
-     * Defaults to `'graphqlQuery'`.
-     *
-     * The tool must accept `{ query: string; variables?: Record<string, unknown> }`
-     * and return a GraphQL-shaped response: `{ data: unknown; errors?: unknown[] }`.
-     *
-     * The result is normalised across surfaces:
-     * - OpenAI surface: `sdk.callTool()` resolves with `{ result: "<JSON string>" }`
-     * - MCP Apps surface: `sdk.callTool()` resolves with `{ structuredContent, content }`
-     */
-    toolName?: string;
-}
-export declare function lightningGraphql(options?: LightningGraphqlOptions): Provider;
-//# sourceMappingURL=lightning-graphql.d.ts.map

package/dist/providers/lightning-graphql.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"lightning-graphql.d.ts","sourceRoot":"","sources":["../../src/providers/lightning-graphql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACvC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AA0KD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,QAAQ,CAShF"}

package/docs/user-guide.md

@@ -1,377 +0,0 @@
-# User Guide: Compiling LWC Components into a Static Bundle
-
-This guide walks through using `@salesforce/vite-plugin-lwc-ui-bundle` to compile
-your existing LWC components into a single self-contained `dist/index.html` —
-no server required, opens directly in a browser.
-
----
-
-## Prerequisites
-
-- Node.js >= 20.0.0
-- Your LWC components already exist in a Salesforce DX project
-
----
-
-## Project Structure
-
-The example project `my-lwc-app` uses the standard Salesforce DX flat structure:
-
-```
-my-lwc-app/
-├── force-app/main/default/lwc/
-│   ├── helloApp/                   ← component directly, no namespace folder
-│   │   ├── helloApp.js
-│   │   ├── helloApp.html
-│   │   └── helloApp.js-meta.xml
-│   └── helloMessage/
-│       ├── helloMessage.js
-│       ├── helloMessage.html
-│       └── helloMessage.js-meta.xml
-├── src/
-│   └── bootstrap.js                ← mounts root component
-├── index.html                      ← entry point
-├── vite.config.js                  ← plugin config
-└── package.json
-```
-
-Use `namespace: 'c'` in `vite.config.js` to tell the plugin to treat this flat
-structure as namespace `c` — components are then importable as `'c/helloApp'`.
-
----
-
-## Step 1: Add Files
-
-### `package.json`
-
-```json
-{
-  "name": "my-lwc-app",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "build": "vite build",
-    "dev": "vite",
-    "preview": "vite preview"
-  },
-  "devDependencies": {
-    "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/vite-plugin-lwc-ui-bundle": "^1.0.0",
-    "vite": "^7.0.0",
-    "vite-plugin-singlefile": "^2.3.0"
-  },
-  "dependencies": {
-    "@salesforce-ux/design-system": "^2.29.1",
-    "lightning-base-components": "^1.28.17-alpha",
-    "lwc": "^9.0.0"
-  }
-}
-```
-
-### `vite.config.js`
-
-```js
-import { defineConfig } from "vite";
-import lwcVitePlugin from "@salesforce/vite-plugin-lwc-ui-bundle";
-import { viteSingleFile } from "vite-plugin-singlefile";
-
-export default defineConfig({
-  build: {
-    target: "esnext", // required for top-level await in bootstrap.js
-  },
-  plugins: [
-    lwcVitePlugin({
-      modules: {
-        // Flat DX structure: specify { path, namespace } per directory
-        // Use a plain string if your dir already has namespace sub-folders
-        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
-
-        // Include if your components use lightning/* base components
-        npm: ["lightning-base-components"],
-      },
-    }),
-    viteSingleFile(), // inlines everything into a single index.html
-  ],
-});
-```
-
-### `index.html`
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>My LWC App</title>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script>
-      globalThis.lwcRuntimeFlags = { DISABLE_SYNTHETIC_SHADOW: true };
-    </script>
-    <script type="module" src="/src/bootstrap.js"></script>
-  </body>
-</html>
-```
-
-### `src/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/helloApp";
-
-// Mount it — tag name is the kebab-case version of the specifier
-const el = createElement("c-hello-app", { is: App });
-document.getElementById("app").appendChild(el);
-```
-
----
-
-## Step 2: Install Dependencies
-
-```bash
-npm install
-```
-
----
-
-## Step 3: Build
-
-```bash
-npm run build
-```
-
-Output: `dist/index.html` — a single file with all JS and CSS inlined.
-
----
-
-## Step 4: Test
-
-**Option A — Open directly in browser:**
-
-```bash
-open dist/index.html
-```
-
-**Option B — Dev server with live reload:**
-
-```bash
-npm run dev
-# Open http://localhost:5173
-```
-
-**Option C — Preview the production build:**
-
-```bash
-npm run preview
-# Open http://localhost:4173
-```
-
----
-
-## Component Namespace Convention
-
-The plugin supports two directory structures:
-
-### Flat DX structure (standard Salesforce DX)
-
-```
-force-app/main/default/lwc/
-  helloApp/
-    helloApp.js
-```
-
-Use `{ path, namespace }` per directory to specify the namespace:
-
-```js
-modules: {
-  dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }];
-}
-```
-
-| Directory           | LWC Specifier      | HTML Tag          |
-| ------------------- | ------------------ | ----------------- |
-| `lwc/helloApp/`     | `'c/helloApp'`     | `c-hello-app`     |
-| `lwc/helloMessage/` | `'c/helloMessage'` | `c-hello-message` |
-
-### Namespaced structure
-
-```
-modules/
-  records/
-    accountOutputName/
-      accountOutputName.js
-```
-
-Omit `namespace` — the sub-directory name is used as the namespace:
-
-```js
-modules: {
-  dirs: ["modules"];
-}
-```
-
-| Directory                            | LWC Specifier                 | HTML Tag                      |
-| ------------------------------------ | ----------------------------- | ----------------------------- |
-| `modules/records/accountOutputName/` | `'records/accountOutputName'` | `records-account-output-name` |
-
----
-
-## Common Errors
-
-### `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"];
-}
-```
-
-### `[scoped-module-providers] Unhandled import: @salesforce/label/...`
-
-Expected — the plugin returns the label key as display text by default.
-To provide real label values:
-
-```js
-import { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
-
-lwcVitePlugin({
-  providers: [builtins.label({ "c.Save": "Save", "c.Cancel": "Cancel" })],
-});
-```
-
-### Component renders but looks unstyled
-
-Add SLDS import to `src/bootstrap.js`:
-
-```js
-import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
-```
-
-### `[scoped-module-providers] Unhandled import: @salesforce/user/Id`
-
-Expected warning — `@salesforce/user/*` imports return `undefined` by default.
-To provide real values (e.g. current user ID), add the user provider:
-
-```js
-import { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
-
-lwcVitePlugin({
-  providers: [
-    builtins.user({ Id: "005xx000001X8AAAA" }), // optional: override user fields
-  ],
-});
-```
-
-### `Top-level await is not available in the configured target environment`
-
-Your `bootstrap.js` uses top-level `await` (required when initialising the Data
-SDK). Add `target: 'esnext'` to the build config:
-
-```js
-export default defineConfig({
-  build: { target: "esnext" },
-  plugins: [...],
-});
-```
-
-### `Rollup failed to resolve import "force/someModule"`
-
-Core-only module — add a stub:
-
-```js
-// stubs/someModule.js
-export const someExport = () => {};
-```
-
-```js
-// vite.config.js
-lwcVitePlugin({ stubs: { "force/someModule": "./stubs/someModule.js" } });
-```
-
----
-
-## Connecting to a Real Salesforce Org (lwcProxy)
-
-By default the plugin runs fully off-platform with mock data. To connect your
-components to a real Salesforce org in local dev — enabling `lightning/graphql`
-to execute real queries — add `lwcProxy()` alongside `lwcVitePlugin()`.
-
-### Prerequisites
-
-- Salesforce CLI installed and an org connected: `sf org display`
-- Additional packages: `@salesforce/sdk-data` and `@salesforce/ui-bundle`
-
-```bash
-npm install @salesforce/sdk-data @salesforce/ui-bundle
-```
-
-### 1. Add lwcProxy to vite.config.js
-
-```js
-import { defineConfig } from "vite";
-import lwcVitePlugin, { lwcProxy } from "@salesforce/vite-plugin-lwc-ui-bundle";
-import { viteSingleFile } from "vite-plugin-singlefile";
-
-export default defineConfig({
-  build: {
-    target: "esnext", // required for top-level await in bootstrap.js
-  },
-  plugins: [
-    lwcProxy(), // auto-reads sf CLI default org credentials
-    // lwcProxy({ orgAlias: "my-org", debug: true })  // explicit org + verbose logging
-    lwcVitePlugin({
-      modules: {
-        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
-      },
-    }),
-    viteSingleFile(),
-  ],
-});
-```
-
-### 2. Initialise the Data SDK in bootstrap.js
-
-The SDK must be initialised before any component that uses `lightning/graphql`
-mounts. Use a top-level `await` import to guarantee ordering:
-
-```js
-import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
-import "@lwc/synthetic-shadow";
-import { createElement } from "lwc";
-
-// Initialise the Data SDK — lwcProxy() handles /services/* on the Vite dev server
-import { createDataSDK } from "@salesforce/sdk-data";
-try {
-  globalThis.__sfdc_sdk__ = await createDataSDK({
-    uiBundle: { basePath: "/" },
-  });
-} catch (_err) {
-  globalThis.__sfdc_sdk__ = {};
-}
-
-import App from "c/helloApp";
-const el = createElement("c-hello-app", { is: App });
-document.getElementById("app").appendChild(el);
-```
-
-### 3. Run the dev server
-
-```bash
-npm run dev
-# Terminal shows: [lwc-proxy] Connected to https://your-org.my.salesforce.com
-# Open http://localhost:5173
-```
-
-Components using `lightning/graphql` will now execute real GraphQL queries
-against your org. The proxy intercepts `/services/*` calls inside the Vite dev
-server — no separate proxy process needed.
-
-> **Note:** The `basePath: '/'` setting works for `npm run dev` only. For
-> production builds (`dist/index.html`), a standalone proxy server is required.