@liquidcommerce/elements-sdk 2.6.0-beta.12 → 2.6.0-beta.121

package/docs/v1/getting-started/installation.md

@@ -0,0 +1,351 @@
+# Installation
+
+The LiquidCommerce Elements SDK can be integrated into your website using either a CDN script tag or as an NPM package.
+
+## Browser Requirements
+
+The SDK requires:
+- Modern browser with Web Components support (Chrome 66+, Firefox 60+, Safari 12+, Edge 79+)
+- Shadow DOM support
+- JavaScript enabled
+
+For older browsers, you'll need to include Web Components and Shadow DOM polyfills.
+
+## CDN Installation (Recommended)
+
+The simplest way to get started is by adding the SDK script tag to your HTML.
+
+### Basic Setup
+
+Add the following script tag to your page's `<head>` section:
+
+```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>
+```
+
+> **Note:** The host `elements.reservebar-worker.workers.dev` shown above is an example, partner-specific endpoint. Use the CDN URL provided by your LiquidCommerce representative in place of this host.
+
+The path segment selects which bundle is served:
+
+| Path | Bundle |
+|------|--------|
+| `/all/elements.js` | Full SDK bundle (product, cart, checkout, and all other elements) |
+| `/checkout/checkout.js` | Checkout-only bundle (tree-shaken, smaller) |
+| `/all/beta/elements.js` | Beta channel of the full SDK bundle |
+
+### Script Attributes
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-liquid-commerce-elements` | Yes | Identifies this as the Elements SDK script |
+| `data-token` | Yes | Your LiquidCommerce API key |
+| `data-env` | No | Environment: `staging` or `production`. Defaults to `production` if omitted. |
+| `data-gtm-gateway-url` | No | Google tag gateway path your own GTM container is served from (e.g. `/metrics/`). See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway). |
+| `defer` | Recommended | Allows non-blocking script loading |
+
+### Where to Place the Script
+
+While the `<head>` section is recommended, the script can be placed anywhere on your page:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Store</title>
+  <!-- SDK script in head (recommended) -->
+  <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>
+</head>
+<body>
+  <!-- Your content -->
+</body>
+</html>
+```
+
+The `defer` attribute ensures the script loads asynchronously without blocking page content, keeping your site fast regardless of placement.
+
+### Checkout-Only Build
+
+If you only need checkout functionality (without product displays or cart), use the lighter checkout-only build:
+
+```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/checkout/checkout.js"
+></script>
+```
+
+This build is tree-shaken and significantly smaller, ideal for dedicated checkout pages.
+
+## NPM Installation
+
+For JavaScript/TypeScript projects using a bundler (Webpack, Rollup, Vite, etc.), install via NPM:
+
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+### Basic Usage
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+// Initialize the client
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production'
+});
+
+// Client is ready to use
+console.log('Elements SDK initialized');
+```
+
+### Checkout-Only Import
+
+For tree-shaking benefits in checkout-only scenarios:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+
+### TypeScript Support
+
+The SDK includes full TypeScript definitions. Import types as needed:
+
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement
+} from '@liquidcommerce/elements-sdk';
+
+const config: ILiquidCommerceElementsConfig = {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff'
+      }
+    }
+  }
+};
+
+// Elements() returns `null` in SSR / non-browser environments, so the
+// client is typed as `ILiquidCommerceElementsClient | null`.
+const client: ILiquidCommerceElementsClient | null = await Elements('YOUR_API_KEY', config);
+
+if (client) {
+  // Safe to use the client here
+  client.injectProductElement([
+    { containerId: 'product-1', identifier: '00619947000020' }
+  ]);
+}
+```
+
+## Framework Integration
+
+### React
+
+```jsx
+import { Elements } from '@liquidcommerce/elements-sdk';
+import { useEffect, useState } from 'react';
+
+function App() {
+  const [elementsClient, setElementsClient] = useState(null);
+
+  useEffect(() => {
+    async function initElements() {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production'
+      });
+      setElementsClient(client);
+    }
+    
+    initElements();
+  }, []);
+
+  useEffect(() => {
+    if (elementsClient) {
+      elementsClient.injectProductElement([
+        { containerId: 'product-1', identifier: '00619947000020' }
+      ]);
+    }
+  }, [elementsClient]);
+
+  return (
+    <div>
+      <div id="product-1"></div>
+    </div>
+  );
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <div id="product-1"></div>
+</template>
+
+<script>
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+export default {
+  async mounted() {
+    const client = await Elements('YOUR_API_KEY', {
+      env: 'production'
+    });
+    
+    await client.injectProductElement([
+      { containerId: 'product-1', identifier: '00619947000020' }
+    ]);
+  }
+}
+</script>
+```
+
+### Next.js
+
+In Next.js, initialize the SDK in a client component:
+
+```jsx
+'use client';
+
+import { Elements } from '@liquidcommerce/elements-sdk';
+import { useEffect } from 'react';
+
+export default function ProductPage() {
+  useEffect(() => {
+    async function init() {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: {
+          baseUrl: '/api/elements-proxy'
+        }
+      });
+      
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    }
+    
+    init();
+  }, []);
+
+  return <div id="product"></div>;
+}
+```
+
+> **Note:** The SDK is SSR-safe. When imported in a Node.js / SSR environment, a lightweight stub is resolved automatically — factory functions return `null` and no browser APIs are accessed. Initialize on the client (e.g., `useEffect`, `onMounted`) to get the real client.
+
+## Configuration Options
+
+The SDK accepts a configuration object during initialization:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',           // Optional (defaults to 'production'): 'staging' | 'production'
+  debugMode: 'console',         // Optional: 'none' | 'console' | 'panel'
+  customTheme: { /* ... */ },   // Optional: Theme customization
+  promoTicker: [ /* ... */ ],   // Optional: Promo ticker configuration
+  proxy: { /* ... */ },         // Optional: Proxy configuration
+  gtm: { /* ... */ },           // Optional: Google tag gateway URL of your own GTM container
+  checkout: { /* ... */ },      // Optional: Checkout configuration
+  development: { /* ... */ }    // Optional: Development/testing options
+});
+```
+
+> **Note:** `debugMode` is ignored when `env` is `'production'`. Debug logging and the debug panel are only activated outside production (`staging`).
+
+See [Configuration Reference](../api/configuration.md) for complete configuration options.
+
+## Verification
+
+After installation, verify the SDK is loaded correctly:
+
+### CDN Verification
+
+Open your browser's console and check for:
+
+```javascript
+// The client is available globally
+console.log(window.LiquidCommerce.elements);
+// Should output: { injectProductElement: ƒ, ui: {...}, actions: {...}, ... }
+```
+
+### NPM Verification
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+console.log(client); // Should output the client object
+```
+
+## Troubleshooting Installation
+
+### Script Not Loading
+
+If the SDK script fails to load:
+
+1. **Check the network tab** in browser DevTools for 404 or CORS errors
+2. **Verify the script URL** is correct and accessible
+3. **Check ad blockers** - they may block scripts with "commerce" in the name (see [Proxy Setup](../integration/proxy-setup.md))
+
+### Web Components Not Supported
+
+If you see an error about Web Components:
+
+```
+[LiquidCommerce Elements] SDK requires support for Web Components. Please include a Web Components polyfill for older browsers.
+```
+
+Include a Web Components polyfill before the SDK script:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+### TypeScript Errors
+
+If you encounter TypeScript errors:
+
+1. Ensure TypeScript version is 4.5 or higher
+2. Check that `@liquidcommerce/elements-sdk` is in your `dependencies` (not `devDependencies`)
+3. Verify your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
+```
+
+## Next Steps
+
+- **Quick Start**: [Build your first product page in 5 minutes](./quick-start.md)
+- **Core Concepts**: [Understand how the SDK works](./concepts.md)
+- **Component Guides**: [Product](../guides/product-component.md), [Cart](../guides/cart-component.md), [Checkout](../guides/checkout-component.md)
+- **API Reference**: [Full API documentation](../api/client.md)