npm - @liquidcommerce/elements-sdk - Versions diffs - 2.6.0-beta.7 → 2.6.0-beta.71 - Mend

@liquidcommerce/elements-sdk 2.6.0-beta.7 → 2.6.0-beta.71

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (224) hide show

package/docs/v1/integration/angular.md ADDED Viewed

@@ -0,0 +1,39 @@
+# Angular Integration
+Initialize Elements in a browser-only lifecycle hook and inject the component after the view mounts.
+## Install
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+## Standalone Component Example
+```ts
+import { AfterViewInit, Component } from '@angular/core';
+import { Elements } from '@liquidcommerce/elements-sdk';
+@Component({
+  selector: 'app-product-page',
+  standalone: true,
+  template: '<div id="product"></div>'
+})
+export class ProductPageComponent implements AfterViewInit {
+  async ngAfterViewInit() {
+    const client = await Elements('YOUR_API_KEY', { env: 'production' });
+    await client.injectProductElement([
+      { containerId: 'product', identifier: '00619947000020' }
+    ]);
+  }
+}
+```
+## Notes
+- Initialize only in the browser (not during server rendering).
+## Related Docs
+- [Product Component](../guides/product-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/laravel.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Laravel Integration
+Use the CDN build in a Blade view for a quick server-rendered setup.
+## Blade Template (CDN)
+```blade
+<!-- resources/views/product.blade.php -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Product</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="{{ env('LCE_API_KEY') }}"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <div id="product"></div>
+</body>
+</html>
+```
+## Notes
+- Keep your API key in `.env` and reference it in Blade.
+- You can add a cart button with `data-cart-badge-button` on the script tag.
+## Related Docs
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)

package/docs/v1/integration/nextjs.md ADDED Viewed

@@ -0,0 +1,69 @@
+# Next.js Integration
+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)
+```jsx
+'use client';
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: { baseUrl: '/api/elements-proxy' }
+      });
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+  return <div id="product"></div>;
+}
+```
+## Pages Router
+```jsx
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', { env: 'production' });
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+  return <div id="product"></div>;
+}
+```
+## 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
+- For ad blocker mitigation, configure the proxy (see [Proxy Setup](./proxy-setup.md)).
+## Related Docs
+- [Proxy Setup](./proxy-setup.md)
+- [Product Component](../guides/product-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/proxy-setup.md ADDED Viewed

@@ -0,0 +1,89 @@
+# Proxy Setup
+If ad blockers or network policies block the SDK assets, use a proxy on your domain. The SDK supports a `proxy.baseUrl` that routes API calls through your server.
+## 1) Configure the SDK
+### NPM
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  proxy: {
+    baseUrl: 'https://yoursite.com/api/elements-proxy'
+  }
+});
+```
+### CDN (Next.js example)
+```jsx
+'use client';
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: { baseUrl: '/api/elements-proxy' }
+      });
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+  return <div id="product"></div>;
+}
+```
+## 2) Create the Proxy Endpoint
+Your endpoint should forward requests to the LiquidCommerce Elements API, preserving method, headers, and body.
+### Minimal Express Example
+```javascript
+import express from 'express';
+import fetch from 'node-fetch';
+const app = express();
+app.use(express.json());
+app.all('/api/elements-proxy/*', async (req, res) => {
+  const targetPath = req.params[0];
+  const targetUrl = `https://api.liquidcommerce.us/${targetPath}`;
+  const response = await fetch(targetUrl, {
+    method: req.method,
+    headers: {
+      ...req.headers,
+      host: 'api.liquidcommerce.us'
+    },
+    body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
+  });
+  const data = await response.text();
+  res.status(response.status).send(data);
+});
+app.listen(3000, () => {
+  console.log('Proxy listening on port 3000');
+});
+```
+## Notes
+- Keep your API key server-side whenever possible.
+- Ensure CORS allows your storefront domain to call the proxy.
+## Related Docs
+- [Installation](../getting-started/installation.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/react.md ADDED Viewed

@@ -0,0 +1,64 @@
+# React Integration
+Use the NPM package and initialize the SDK client on the client side. Then inject components after mount.
+## Install
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+## Basic Product Page
+```jsx
+import { useEffect, useState } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+export default function ProductPage() {
+  const [client, setClient] = useState(null);
+  useEffect(() => {
+    let mounted = true;
+    (async () => {
+      const instance = await Elements('YOUR_API_KEY', { env: 'production' });
+      if (mounted) setClient(instance);
+    })();
+    return () => { mounted = false; };
+  }, []);
+  useEffect(() => {
+    if (!client) return;
+    client.injectProductElement([
+      { containerId: 'product', identifier: '00619947000020' }
+    ]);
+  }, [client]);
+  return <div id="product"></div>;
+}
+```
+## Cart Button
+```jsx
+import { useEffect } from 'react';
+export default function CartButton() {
+  useEffect(() => {
+    if (!window.LiquidCommerce.elements) return;
+    window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
+  }, []);
+  return <div id="header-cart"></div>;
+}
+```
+## Notes
+- 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
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Client API](../api/client.md)

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

@@ -0,0 +1,84 @@
+# Vanilla JavaScript Integration
+Use the CDN build for the fastest setup, or use NPM if you have a build step.
+## Option A: CDN (Declarative)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Vanilla JS Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    data-cart-badge-button="header-cart"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <header>
+    <h1>Premium Spirits</h1>
+    <div id="header-cart"></div>
+  </header>
+  <main>
+    <div id="product"></div>
+  </main>
+</body>
+</html>
+```
+## Option B: CDN (Programmatic)
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.LiquidCommerce.elements;
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+});
+</script>
+<div id="product"></div>
+```
+## Option C: NPM
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+## Related Docs
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/vue.md ADDED Viewed

@@ -0,0 +1,58 @@
+# Vue Integration
+Use the NPM package and initialize Elements in `onMounted`.
+## Install
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+## Vue 3 (Single File Component)
+```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>
+```
+## 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)
+- [Client API](../api/client.md)

package/docs/v1/reference/browser-support.md ADDED Viewed

@@ -0,0 +1,44 @@
+# Browser Support
+The Elements SDK requires modern browser features (Web Components + Shadow DOM). If you need to support older browsers, include polyfills.
+## Minimum Versions
+- Chrome 66+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+## Required Features
+- Custom Elements (Web Components)
+- Shadow DOM
+- ES2018 JavaScript
+- Fetch API
+- LocalStorage
+## Server-Side Rendering (SSR)
+The SDK is browser-only, but it is safe to import in SSR frameworks (Next.js, Remix, Nuxt).
+In non-browser environments, initialization is skipped. If you call the SDK on the server,
+it returns `null` and logs a warning instead of throwing.
+Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
+to render components.
+## Polyfills (Legacy Browsers)
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+## Notes
+- Always load the SDK script with `defer` to avoid blocking page render.
+- If you see Web Components errors in the console, add the polyfill before the SDK.
+## Related Docs
+- [Installation](../getting-started/installation.md)
+- [Troubleshooting](./troubleshooting.md)

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

@@ -0,0 +1,70 @@
+# Error Handling
+The SDK emits errors as events and (when applicable) throws a custom `SDKError`. Your app should handle both.
+## SDKError
+All SDK errors use a custom error class:
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+## Catching Errors
+```javascript
+try {
+  await window.LiquidCommerce.elements.injectProductElement([
+    { containerId: 'product', identifier: 'invalid_id' }
+  ]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+## Error Isolation
+The SDK catches and contains its own errors so your app keeps running:
+```javascript
+window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+console.log('App still working');
+```
+## Error Events
+Listen for failure events to show user-friendly messages or trigger retries:
+```javascript
+// Cart add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data.error);
+});
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+// Checkout submit failed
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.error);
+});
+```
+## UI Errors
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+## Related Docs
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md ADDED Viewed

@@ -0,0 +1,54 @@
+# Performance Guide
+The SDK is optimized out of the box. These tweaks help reduce load time and layout shift.
+## 1) Load Non-Blocking
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+## 2) Use the Checkout-Only Build When Appropriate
+If you only need checkout, use the tree-shaken build:
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+## 3) Inject Components When Needed
+Inject above-the-fold products first, then load the rest:
+```javascript
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+## 4) Reserve Space to Prevent Layout Shift
+```css
+#product {
+  min-height: 600px;
+}
+```
+## 5) Let the SDK Handle Media Optimization
+The SDK automatically:
+- Lazy loads images
+- Uses responsive image sizes
+- Virtualizes carousel images
+## Related Docs
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)