@liquidcommerce/elements-sdk 2.6.0-beta.42 → 2.6.0-beta.43

package/docs/v1/guides/product-component.md

@@ -212,7 +212,7 @@ Programmatically interact with products:
 Retrieve product information:
 
 ```javascript
-const productData = window.elements.actions.product.getDetails('00619947000020');
+const productData = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
 
 console.log(productData);
 // {
@@ -388,10 +388,10 @@ Set address programmatically to skip prompting:
 
 ```javascript
 // Using Google Places ID
-await window.elements.actions.address.setAddressByPlacesId('ChIJ...');
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId('ChIJ...');
 
 // Or manually
-await window.elements.actions.address.setAddressManually(
+await window.LiquidCommerce.elements.actions.address.setAddressManually(
   {
     one: '123 Main St',
     two: 'Apt 4',
@@ -423,7 +423,7 @@ Presale products are handled automatically; no special configuration needed.
 Force a product to reload and rerender:
 
 ```javascript
-const components = window.elements.getInjectedComponents();
+const components = window.LiquidCommerce.elements.getInjectedComponents();
 const productComponent = components.get('product-1');
 
 if (productComponent) {
@@ -656,7 +656,7 @@ document.querySelectorAll('.product-placeholder').forEach(el => {
 1. Check browser console for errors
 2. Verify container ID exists in the DOM
 3. Confirm product identifier is valid
-4. Check that SDK is initialized (`window.elements` exists)
+4. Check that SDK is initialized (`window.LiquidCommerce.elements` exists)
 
 ### Wrong Pricing
 

package/docs/v1/integration/nextjs.md

@@ -1,6 +1,6 @@
 # Next.js Integration
 
-Use a client component (App Router) or `useEffect` in a client-only page (Pages Router). Initialize the SDK on the client.
+The SDK is SSR-safe out of the box. When imported on the server, a lightweight stub is resolved automatically via the `node` export condition — no dynamic imports or special configuration required. The real SDK activates on the client.
 
 ## App Router (Client Component)
 
@@ -48,9 +48,18 @@ export default function ProductPage() {
 }
 ```
 
+## SSR Behavior
+
+When the module is evaluated during SSR (server components, `getServerSideProps`, middleware, etc.):
+
+- All **types and enums** are available — TypeScript works identically.
+- `Elements()` and `ElementsBuilder()` return `null` and log a warning.
+- No browser APIs (`window`, `document`, `navigator`) are accessed.
+
+You do **not** need `next/dynamic`, conditional `import()`, or `typeof window` guards in your own code.
+
 ## Notes
 
-- Do not initialize server-side (Window/Document required).
 - For ad blocker mitigation, configure the proxy (see [Proxy Setup](./proxy-setup.md)).
 
 ## Related Docs

package/docs/v1/integration/react.md

@@ -44,8 +44,8 @@ import { useEffect } from 'react';
 
 export default function CartButton() {
   useEffect(() => {
-    if (!window.elements) return;
-    window.elements.ui.cartButton('header-cart', true);
+    if (!window.LiquidCommerce.elements) return;
+    window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
   }, []);
 
   return <div id="header-cart"></div>;
@@ -54,7 +54,7 @@ export default function CartButton() {
 
 ## Notes
 
-- Initialize only on the client; the SDK uses browser APIs.
+- The SDK is SSR-safe — importing it on the server resolves a no-op stub automatically. Initialize in `useEffect` to get the real client.
 - For multiple products, call `injectProductElement` with multiple entries.
 
 ## Related Docs

package/docs/v1/integration/vanilla-js.md

@@ -51,7 +51,7 @@ Use the CDN build for the fastest setup, or use NPM if you have a build step.
 
 <script>
 window.addEventListener('lce:actions.client_ready', async () => {
-  const client = window.elements;
+  const client = window.LiquidCommerce.elements;
   await client.injectProductElement([
     { containerId: 'product', identifier: '00619947000020' }
   ]);

package/docs/v1/integration/vue.md

@@ -28,6 +28,30 @@ onMounted(async () => {
 </script>
 ```
 
+## Nuxt 3
+
+The SDK is SSR-safe out of the box. When Nuxt evaluates the import on the server, a lightweight stub is resolved automatically — no `<ClientOnly>`, `process.client` checks, or dynamic imports required.
+
+```vue
+<template>
+  <div id="product"></div>
+</template>
+
+<script setup>
+import { onMounted } from 'vue';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+onMounted(async () => {
+  const client = await Elements('YOUR_API_KEY', { env: 'production' });
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+});
+</script>
+```
+
+During SSR, `Elements()` returns `null` and logs a warning. All types and enums remain available for TypeScript.
+
 ## Related Docs
 
 - [Product Component](../guides/product-component.md)

package/docs/v1/reference/error-handling.md

@@ -19,7 +19,7 @@ class SDKError extends Error {
 
 ```javascript
 try {
-  await window.elements.injectProductElement([
+  await window.LiquidCommerce.elements.injectProductElement([
     { containerId: 'product', identifier: 'invalid_id' }
   ]);
 } catch (error) {
@@ -34,7 +34,7 @@ try {
 The SDK catches and contains its own errors so your app keeps running:
 
 ```javascript
-window.elements.actions.cart.addProduct([/* invalid */]);
+window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
 console.log('App still working');
 ```
 

package/docs/v1/reference/troubleshooting.md

@@ -4,7 +4,7 @@ Common setup issues and how to resolve them.
 
 ## SDK Script Not Loading
 
-**Symptoms:** 404/CORS in Network tab, `window.elements` is undefined.
+**Symptoms:** 404/CORS in Network tab, `window.LiquidCommerce.elements` is undefined.
 
 **Fixes:**
 - Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
@@ -36,7 +36,7 @@ Common setup issues and how to resolve them.
 **Symptoms:** Add to cart works but cart stays closed.
 
 **Fixes:**
-- Ensure a cart button is configured or call `window.elements.actions.cart.openCart()`.
+- Ensure a cart button is configured or call `window.LiquidCommerce.elements.actions.cart.openCart()`.
 - Check for JavaScript errors in the console.
 
 ## Checkout Issues
@@ -56,6 +56,14 @@ Common setup issues and how to resolve them.
 - Make sure the address is set and valid.
 - Listen for `lce:actions.address_failed` to surface errors.
 
+## SSR / Server-Side Rendering
+
+**Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
+
+This is expected behavior. The SDK ships an SSR stub that is automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). The stub exports all types and enums for TypeScript compatibility and returns `null` from factory functions (`Elements`, `ElementsBuilder`, `ElementsCheckout`).
+
+**No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
+
 ## Related Docs
 
 - [Installation](../getting-started/installation.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.42",
+  "version": "2.6.0-beta.43",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -18,11 +18,15 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
+      "node": "./dist/ssr-stub.esm.js",
+      "browser": "./dist/index.esm.js",
       "import": "./dist/index.esm.js",
       "default": "./dist/index.esm.js"
     },
     "./checkout": {
       "types": "./dist/types/index.checkout.d.ts",
+      "node": "./dist/ssr-stub.checkout.esm.js",
+      "browser": "./dist/index.checkout.esm.js",
       "import": "./dist/index.checkout.esm.js",
       "default": "./dist/index.checkout.esm.js"
     },
@@ -30,7 +34,7 @@
   },
   "files": [
     "dist",
-    "docs",
+    "docs/v1",
     "README.md",
     "LICENSE"
   ],
@@ -77,9 +81,9 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.3.12",
-    "@commitlint/cli": "^20.3.1",
-    "@commitlint/config-conventional": "^20.3.1",
+    "@biomejs/biome": "2.3.13",
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
@@ -89,18 +93,18 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/github": "^12.0.3",
     "@semantic-release/npm": "^13.1.3",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^25.0.10",
+    "@types/node": "^25.2.0",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.56.0",
+    "rollup": "^4.57.1",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "^25.0.3",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },

package/dist/types/interfaces/core.interface.d.ts

@@ -1,140 +0,0 @@
-import type { PRODUCT_LIST_FILTER_TYPES } from '@/constants';
-import type { IAddressActions } from '@/core/client/actions/client-address-action.service';
-import type { ICartActions } from '@/core/client/actions/client-cart-action.service';
-import type { ICheckoutActions } from '@/core/client/actions/client-checkout-action.service';
-import type { IProductActions } from '@/core/client/actions/client-product-action.service';
-import type { IClientConfigs } from '@/core/client/client-config.service';
-import type { ComponentType, DebugMode, ElementsEnv } from '@/enums';
-import type { IAddressOptions } from '@/modules/address/address.interface';
-import type { IPromoTicker, UpdateAddressComponent, UpdateCartComponent, UpdateCheckoutComponent, UpdateComponentGlobalConfigs, UpdateProductComponent } from './configs';
-export type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-export interface IElementsProxyConfig {
-    baseUrl: string;
-    headers?: Record<string, string>;
-}
-export interface ILiquidCommerceElementsDevelopmentConfig {
-    customApiUrl?: string;
-    paymentMethodId?: string;
-    openShadowDom?: boolean;
-}
-export interface IClientCustomThemeConfig {
-    global?: UpdateComponentGlobalConfigs;
-    product?: UpdateProductComponent;
-    address?: UpdateAddressComponent;
-    cart?: UpdateCartComponent;
-    checkout?: UpdateCheckoutComponent;
-}
-export interface ILiquidCommerceElementsCheckoutConfig {
-    pageUrl: string;
-}
-export interface ILiquidCommerceElementsBaseConfig {
-    env?: ElementsEnv;
-    promoTicker?: IPromoTicker[];
-    customTheme?: IClientCustomThemeConfig;
-    debugMode?: DebugMode;
-    checkout?: ILiquidCommerceElementsCheckoutConfig;
-}
-export interface ILiquidCommerceElementsBuilderConfig extends ILiquidCommerceElementsBaseConfig {
-}
-export interface ILiquidCommerceElementsConfig extends ILiquidCommerceElementsBaseConfig {
-    proxy?: IElementsProxyConfig;
-    development?: ILiquidCommerceElementsDevelopmentConfig;
-}
-export interface ILiquidCommerceElementsCheckoutClientConfig {
-    env?: ElementsEnv;
-    customTheme?: IClientCustomThemeConfig;
-    debugMode?: DebugMode;
-    checkout?: ILiquidCommerceElementsCheckoutConfig;
-    proxy?: IElementsProxyConfig;
-    development?: ILiquidCommerceElementsDevelopmentConfig;
-}
-export interface IInjectProductElement {
-    containerId: string;
-    identifier: string;
-}
-export type ProductListFilterType = (typeof PRODUCT_LIST_FILTER_TYPES)[keyof typeof PRODUCT_LIST_FILTER_TYPES];
-export interface IInjectProductListParams {
-    containerId: string;
-    rows?: number;
-    columns?: number;
-    filters?: ProductListFilterType[];
-    productUrl?: string;
-}
-export interface IInjectProductListSearchParams {
-    containerId: string;
-}
-export interface IInjectProductListFiltersParams {
-    containerId: string;
-    filters: ProductListFilterType[];
-}
-export interface IBuilderInjectElementParams {
-    type: ComponentType;
-    containerId: string;
-    [key: string]: any;
-}
-export interface IInjectedComponent {
-    getType(): ComponentType;
-    getElement(): HTMLElement;
-    rerender(): void;
-}
-export interface IProcessInjectElementParams {
-    type: ComponentType;
-    containerId: string;
-    identifier?: string;
-    options?: IAddressOptions;
-    checkoutId?: string;
-    hideHeader?: boolean;
-}
-export interface IInjectCheckoutParams {
-    containerId: string;
-    checkoutId?: string;
-    hideHeader?: boolean;
-}
-export interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
-    simulatePresale?: boolean;
-    presaleExpiresInMinutes?: number;
-}
-export interface ILiquidCommerceElementsUIMethod {
-    cartButton(containerId: string, showItemsCount?: boolean): void;
-    floatingCartButton(showItemsCount?: boolean): void;
-    cartSubtotal(elementId: string): void;
-    cartItemsCount(elementId: string, options?: {
-        hideZero: boolean;
-    }): void;
-}
-export interface ILiquidCommerceElementsActions {
-    product: IProductActions;
-    address: IAddressActions;
-    cart: ICartActions;
-    checkout: ICheckoutActions;
-}
-export interface ILiquidCommerceElementsBuilderClient {
-    updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
-    updateProductComponent(configs: UpdateProductComponent): Promise<void>;
-    updateAddressComponent(configs: UpdateAddressComponent): void;
-    updateCartComponent(configs: UpdateCartComponent): void;
-    updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
-    injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
-    injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
-    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
-    injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
-    injectCheckoutElement(params: IInjectCheckoutBuilderParams): Promise<IInjectedComponent | null>;
-    injectProductList(params: IInjectProductListParams): Promise<void>;
-    actions: ILiquidCommerceElementsActions;
-}
-export interface ILiquidCommerceElementsClient {
-    injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
-    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
-    injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
-    injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
-    injectProductList(params: IInjectProductListParams): Promise<void>;
-    injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>;
-    injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>;
-    ui: ILiquidCommerceElementsUIMethod;
-    actions: ILiquidCommerceElementsActions;
-    getInjectedComponents(): Map<string, IInjectedComponent>;
-}
-export type LiquidCommerceElementsClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsClient;
-export type LiquidCommerceElementsBuilderClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsBuilderClient;