@salesforce/vite-plugin-lwc-ui-bundle 1.130.0

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,222 @@
+# @salesforce/vite-plugin-lwc-ui-bundle
+
+Vite plugin for compiling and running LWC components off-platform. Bundles the full compilation pipeline — scoped module providers, Lightning npm resolution, missing CSS handling, and the Vite/LWC bridge — behind a single configurable entry point.
+
+## Installation
+
+```bash
+npm install @salesforce/vite-plugin-lwc-ui-bundle @lwc/rollup-plugin --save-dev
+```
+
+`@lwc/rollup-plugin` is a required peer dependency.
+
+## Quick Start
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+export default defineConfig({
+  plugins: [
+    lwcVitePlugin({
+      modules: {
+        dirs: ["sf/lwc"],
+        npm: ["lwc-components-lightning"],
+      },
+      providers: [
+        builtins.label(),
+        builtins.i18n(),
+        builtins.accessCheck(),
+        builtins.client(),
+        builtins.gate(),
+        builtins.primitiveUtils(),
+      ],
+    }),
+  ],
+});
+```
+
+## Configuration
+
+### `modules`
+
+Controls where LWC component sources are discovered.
+
+| Property | Type                          | Description                                                                                                                     |
+| -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `dirs`   | `string[]`                    | Directories to scan for `{namespace}/{component}/{component}.js` entries. Each subdirectory of a dir is treated as a namespace. |
+| `npm`    | `(string \| {npm: string})[]` | NPM packages that supply LWC modules. Passed through to `@lwc/rollup-plugin`.                                                   |
+
+```js
+modules: {
+  dirs: ['sf/lwc', 'src/components'],
+  npm: ['lwc-components-lightning'],
+}
+```
+
+### `providers`
+
+Ordered array of scoped module providers. Each provider intercepts imports matching its prefix and returns generated JavaScript source. Providers are evaluated in order; the first to return a non-null result wins.
+
+```js
+providers: [
+  builtins.label({ "Custom.MyLabel": "Hello World" }),
+  builtins.i18n(),
+  builtins.gate({ myFeature: false }),
+  builtins.accessCheck(),
+  builtins.client(),
+  builtins.primitiveUtils(),
+];
+```
+
+### `stubs`
+
+Map of bare module specifiers to stub file paths. These are injected as Vite `resolve.alias` entries.
+
+```js
+stubs: {
+  aura: 'src/stubs/aura-off-platform.js',
+  logger: 'src/stubs/logger-stub.js',
+}
+```
+
+### `lwcOptions`
+
+Pass-through options for `@lwc/rollup-plugin`. See the [@lwc/rollup-plugin docs](https://github.com/nicknisi/lwc/tree/master/packages/%40lwc/rollup-plugin) for available options.
+
+```js
+lwcOptions: {
+  enableDynamicComponents: true,
+  enableSyntheticElementInternals: true,
+}
+```
+
+### `ignorePatterns`
+
+Specifier prefixes that should never be intercepted by providers, even if they match a provider or intercept prefix. Defaults to `['@salesforce/sdk-', '@salesforce/core']`.
+
+### `passthroughRules`
+
+Rules for selectively letting specific imports resolve normally. Each rule has a `specifierPrefix` and `importerPattern`; when an import matches both, it bypasses the provider system.
+
+```js
+passthroughRules: [
+  {
+    specifierPrefix: "@salesforce/label/",
+    importerPattern: "/lwc-components-lightning/",
+  },
+];
+```
+
+## Built-in Providers
+
+All built-in providers are factory functions exported from `vite-plugin-lwc-ui-bundle` as `builtins.*` (or individually from `@salesforce/vite-plugin-lwc-ui-bundle/providers`).
+
+### `label(overrides?)`
+
+Handles `@salesforce/label/*`. Returns label strings from a defaults map; unknown labels get a camelCase-to-words fallback. Pass `overrides` to add or replace defaults.
+
+### `i18n(options?)`
+
+Handles `@salesforce/i18n/*`. Browser-derived values (lang, locale, currency, etc.) use the Intl API at runtime. Format patterns use en-US defaults. Accepts `staticOverrides` and `objectOverrides`.
+
+### `gate(overrides?)`
+
+Handles `@salesforce/gate/*`. All gates default to open. Pass a map of gate names to `false` to close specific gates.
+
+### `accessCheck(overrides?)`
+
+Handles `@salesforce/accessCheck/*`. All checks default to `false`. Pass overrides to change individual checks.
+
+### `client()`
+
+Handles `@salesforce/client/*`. Supports `formFactor` (Small/Medium/Large via CSS media queries at runtime).
+
+### `primitiveUtils()`
+
+Handles `lightning/primitiveUtils`. Stubs `normalizeBoolean` and `reflectAttribute`.
+
+## Custom Providers
+
+Create custom providers by implementing the provider interface:
+
+```js
+function myProvider() {
+  return {
+    // prefix: imports starting with this string will be routed to this provider.
+    // The parent @scope/ prefix is auto-derived and used as a catch-all intercept.
+    prefix: "@myorg/config/",
+
+    // resolve: given a full import specifier, return JavaScript source or null to pass.
+    resolve(specifier) {
+      if (!specifier.startsWith("@myorg/config/")) return null;
+      const key = specifier.slice("@myorg/config/".length);
+      return `export default ${JSON.stringify(myConfigMap[key])};`;
+    },
+  };
+}
+```
+
+For providers that don't use a prefix-based match (like `lightning/primitiveUtils`), add a `match` function:
+
+```js
+{
+  match(id) { return id === 'lightning/primitiveUtils'; },
+  resolve(specifier) { /* ... */ },
+}
+```
+
+## Internal Plugins
+
+The plugin factory returns an array of coordinated Vite plugins:
+
+| Plugin                                | Purpose                                              |
+| ------------------------------------- | ---------------------------------------------------- |
+| `vite-plugin-scoped-module-providers` | Virtual module orchestrator for providers            |
+| `vite-plugin-resolve-lightning-npm`   | Resolves `lightning/*` from npm with local overrides |
+| `vite-plugin-lwc-missing-css`         | Empty CSS for HTML-only templates                    |
+| `vite-plugin-lwc-bridge`              | Bridges Vite/LWC HTML and CSS conflicts              |
+| `rollup-plugin-lwc-compiler`          | `@lwc/rollup-plugin` with Vite guard rails           |
+| `vite-plugin-lwc-stubs`               | Alias stubs (only present if `stubs` is non-empty)   |
+
+## Local Salesforce Dev (lwcProxy)
+
+`lwcProxy()` is an optional companion plugin that proxies Salesforce API calls to a connected org, enabling `lightning/graphql` to work in local dev without an MCP server.
+
+### Setup
+
+```bash
+npm install @salesforce/vite-plugin-lwc-ui-bundle @salesforce/sdk-data @salesforce/ui-bundle
+```
+
+```js
+// vite.config.js
+import lwcVitePlugin, { lwcProxy } from '@salesforce/vite-plugin-lwc-ui-bundle';
+
+export default defineConfig({
+  plugins: [
+    lwcProxy(),        // reads sf CLI default org; pass { orgAlias: 'myOrg' } to specify
+    lwcVitePlugin({ ... }),
+  ],
+});
+```
+
+```js
+// src/bootstrap.js — initialise before the app mounts
+import { createDataSDK } from "@salesforce/sdk-data";
+globalThis.__sfdc_sdk__ = await createDataSDK({ uiBundle: { basePath: "/" } });
+```
+
+### How it works
+
+- `lwcProxy()` intercepts `/services/*` and `/lwr/*` requests in the Vite dev server and forwards them to Salesforce with the org's access token
+- Credentials are read automatically from the `sf` CLI (uses `@salesforce/ui-bundle/app`, an optional peer dep)
+- `lightning/graphql` checks `globalThis.__sfdc_sdk__` first; if not set, falls back to the MCP surface (`getChatSDK().callTool`)
+
+### Options
+
+| Option     | Type      | Default            | Description                          |
+| ---------- | --------- | ------------------ | ------------------------------------ |
+| `orgAlias` | `string`  | sf CLI default org | Salesforce org alias                 |
+| `debug`    | `boolean` | `false`            | Log each proxied request to terminal |

package/dist/discovery.d.ts

@@ -0,0 +1,3 @@
+import { DirConfig, DiscoveredModule } from './types';
+export declare function discoverModules(dirs?: (string | DirConfig)[]): DiscoveredModule[];
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3D,wBAAgB,eAAe,CAAC,IAAI,GAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAO,GAAG,gBAAgB,EAAE,CAiDrF"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from 'vite';
+import { LwcVitePluginOptions } from './types';
+import * as builtinProviders from "./providers/index";
+export type { Provider, LwcVitePluginOptions, PassthroughRule, DiscoveredModule, DirConfig, } from './types';
+export { builtinProviders as builtins };
+export { discoverModules } from './discovery';
+export { lwcProxy } from './plugins/proxy';
+export type { LwcProxyOptions } from './plugins/proxy';
+export default function lwcVitePlugin(options?: LwcVitePluginOptions): Plugin[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAOnC,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAA8B,MAAM,SAAS,CAAC;AAEhF,YAAY,EACX,QAAQ,EACR,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,SAAS,GACT,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA6BvD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,EAAE,CAgJlF"}