@liquidcommerce/elements-sdk

Elements SDK

Add product, cart, and checkout experiences to any website with a few lines of code

📋 Table of Contents

Click to expand

• Overview
  • Latest Features
  • Key Features
• Architecture
  • System Architecture
  • Component Architecture
  • Event Flow
• Features
• Installation
  • CDN Usage
  • NPM Installation
• Browser Support
• Quick Start
  • Auto-initialization
  • Product Mapping
  • Programmatic Control
• SDK Methods & API
  • Core Client Methods
  • UI Methods
  • Builder Methods
• Actions
  • Product Actions
  • Address Actions
  • Cart Actions
  • Checkout Actions
• Events
  • Event Listening
  • Available Events
• Configuration
  • Module Options
  • Environment Options
  • Auto-init Attributes
• Themes & Customization
  • Theme Configuration
  • Dynamic Updates
• Proxy Configuration
• Demo Pages
  • Simple Demo
  • Advanced Demo
• Development Scripts
  • Build Commands
  • Code Quality
  • Maintenance
• Documentation
• Versioning
• Support

🎯 Overview

The LiquidCommerce Elements SDK is a production-ready JavaScript library that enables partners to seamlessly integrate product displays, shopping carts, and checkout flows into any website. Built with performance and developer experience in mind.

🆕 Latest Features

• Builder Mode: Dynamic theme customization for development environments
• Action Feedback Events: All actions now emit success/failure events for better UX
• Proxy Support: Route API requests through your server to avoid ad blockers
• Enhanced CLI: Improved development scripts with parallel builds and better error handling
• TypeScript Support: Full TypeScript definitions for better IDE experience

✨ Key Features

🚀 Quick Integration Auto-initialization with data attributes Zero configuration setup CDN or NPM installation Works with any framework or vanilla JS	🛍️ Complete E-commerce Product display components Shopping cart with real-time updates Full checkout flow Address management
🎨 Customizable UI Comprehensive theme system Component-level styling Responsive design Modern, accessible components	⚡ Performance First ~150KB bundle size Zero runtime dependencies Lazy loading support Optimized for Core Web Vitals

🏗️ Architecture

System Architecture

graph TB
    subgraph "Your Website"
        HTML[HTML Page]
        JS[JavaScript]
        INIT[Elements SDK]
    end
    
    subgraph "Elements SDK Core"
        CLIENT[Elements Client]
        
        subgraph "Components"
            PROD[Product Component]
            CART[Cart Component]
            CHECK[Checkout Component]
            ADDR[Address Component]
        end
        
        subgraph "Services"
            ACT[Actions Service]
            EVT[Events Service]
            API[API Client]
            THEME[Theme Provider]
        end
        
        subgraph "UI Layer"
            BTN[Cart Button]
            FLOAT[Floating Cart]
            DISP[Live Displays]
        end
    end
    
    subgraph "LiquidCommerce API"
        PAPI[Products API]
        CAPI[Cart API]
        OAPI[Orders API]
        AAPI[Address API]
    end
    
    HTML --> INIT
    JS --> CLIENT
    
    CLIENT --> PROD
    CLIENT --> CART
    CLIENT --> CHECK
    CLIENT --> ADDR
    
    PROD --> API
    CART --> API
    CHECK --> API
    ADDR --> API
    
    API --> PAPI
    API --> CAPI
    API --> OAPI
    API --> AAPI
    
    ACT --> EVT
    CLIENT --> ACT
    CLIENT --> THEME

Component Architecture

graph LR
    subgraph "Product Component"
        PD[Product Display]
        PS[Size Selector]
        PQ[Quantity Control]
        PA[Add to Cart]
    end
    
    subgraph "Cart Component"
        CI[Cart Items]
        CQ[Quantity Update]
        CP[Promo Code]
        CT[Cart Total]
    end
    
    subgraph "Checkout Component"
        CS[Shipping Info]
        CB[Billing Info]
        PM[Payment Method]
        OS[Order Summary]
    end
    
    PD --> PS
    PS --> PQ
    PQ --> PA
    
    CI --> CQ
    CQ --> CT
    CP --> CT
    
    CS --> CB
    CB --> PM
    PM --> OS

Event Flow

sequenceDiagram
    participant User
    participant SDK
    participant Actions
    participant Events
    participant API
    participant Website
    
    User->>SDK: Add to Cart
    SDK->>Actions: cart.addProduct()
    Actions->>API: POST /cart/items
    API-->>Actions: Response
    Actions->>Events: Emit Success/Failure
    Events->>Website: lce:actions.cart_product_add_success
    Website->>User: Show Feedback

🚀 Features

• 🎯 Auto-initialization: Single script tag with data attributes
• 📦 Zero Dependencies: Everything bundled, no peer dependencies
• 🌐 CDN Ready: No build step required for basic usage
• ⚡ Lightweight: ~150KB minified bundle size
• 🔧 Framework Agnostic: Works with React, Vue, Angular, or vanilla JS
• 📱 Responsive: Mobile-first design approach
• ♿ Accessible: WCAG 2.1 AA compliant components
• 🎨 Themeable: Comprehensive customization system
• 🔐 Secure: PCI compliant checkout flow
• 📊 Analytics Ready: Built-in event system for tracking
• 🌍 Multi-environment: Support for dev, staging, and production
• 🧪 Well Tested: Comprehensive test coverage

📦 Installation

Choose how to include the SDK

• Use our CDN (no build step required)
• Install from NPM (for bundlers like Vite, Webpack, etc.)

Option A — Use the CDN

Include the script on your page. Use the production or beta URL:

<!-- Production (latest) -->
<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>

<!-- Beta (latest) -->
<script src="https://assets-elements.liquidcommerce.us/all/beta/elements.js"></script>

You can also pin to a specific version:

<script src="https://assets-elements.liquidcommerce.us/all/1.2.3/elements.js"></script>

Option B — Install from NPM

npm install @liquidcommerceteam/elements-sdk
# or
pnpm add @liquidcommerceteam/elements-sdk

Then import and initialize in your app code:

import { Elements } from '@liquidcommerceteam/elements-sdk';

const client = await Elements('YOUR_API_KEY', {
  env: 'production',
});

🌐 Browser Support

⚠️ Important: This SDK is designed for browser environments only. It will not work in server-side rendering, Node.js, or other non-browser environments. The SDK includes built-in safety measures to prevent errors when accidentally imported in these environments.

Supported Browsers

The SDK supports 2018+ browsers with comprehensive polyfills:

Browser	Minimum Version	Released
Chrome	66+	April 2018
Firefox	60+	May 2018
Safari	12+	September 2018
Edge	79+ (Chromium)	January 2020
Samsung Internet	7.2+	June 2018

📖 See docs/BROWSER_SUPPORT.md for detailed version compatibility and polyfill information.

🚀 Quick Start

Step 1 — Auto-initialization (Easiest)

This single script both loads the SDK and initializes it automatically. Place it:

• At the end of the <body> (recommended), or
• In the <head> with defer so it doesn't block rendering.

<!-- Body footer (recommended) -->
<script
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-cart-id="buttons-container"
  data-show-cart-items
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

<!-- OR: Head with defer -->
<script
  defer
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-cart-id="buttons-container"
  data-show-cart-items
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

Available data attributes:

• data-token="YOUR_API_KEY" - Your API key (required)
• data-env="production|development" - Environment (default: production)
• data-cart-id="container-id" - ID for cart button container (optional, creates floating button if omitted)
• data-show-cart-items - Show items count badge on cart button (optional)
• data-enable-debugging - Enable debug logging in development (optional)

Add containers where you want elements to render:

<div id="buttons-container"></div>
<div id="pdp-1"></div>
<div id="pdp-2"></div>

Step 2 — Map products to containers

Choose one or combine multiple methods:

1) Attribute pairs on the main script

<script
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="production"
  data-container-1="pdp-1"
  data-product-1="00619947000020"
  data-container-2="pdp-2"
  data-product-2="00832889005513"
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
></script>

2) JSON configuration script

<script data-liquid-commerce-elements-products type="application/json">
  [
    { "containerId": "pdp-1", "identifier": "00619947000020" },
    { "containerId": "pdp-2", "identifier": "00832889005513" }
  ]
</script>

3) Annotated elements

<div data-lce-product="00619947000020"></div>
<div data-lce-product="00832889005513"></div>

Step 3 — Programmatic Control (Advanced)

Initialize the SDK yourself for full control:

<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
<script>
  (async () => {
    const client = await window.Elements('YOUR_API_KEY', {
      env: 'production',
      enableDebugging: false, // only for development
      customTheme: { /* optional theming overrides */ }
    });

    // Your implementation here...
  })();
</script>

📖 SDK Methods & API

Core Client Methods

Once initialized, the client provides these core methods:

Product Injection

injectProductElement(params: IInjectProductElement[]): Promise<void>

Inject product components into containers:

await client.injectProductElement([
  { containerId: 'pdp-1', identifier: '00619947000020' },
  { containerId: 'pdp-2', identifier: '00832889005513' }
]);

Cart Injection

injectCartElement(containerId: string): Promise<void>

Inject a cart component:

await client.injectCartElement('cart-container');

Checkout Injection

injectCheckoutElement(containerId: string): Promise<void>

Inject a checkout component:

await client.injectCheckoutElement('checkout-container');

Address Injection

injectAddressElement(containerId: string): Promise<void>

Inject an address form component:

await client.injectAddressElement('address-container');

UI Methods

Cart Buttons

ui.cartButton(containerId: string, showItemsCount?: boolean): void

Create an "open cart" button in a specific container:

client.ui.cartButton('buttons-container');

// With items count badge
client.ui.cartButton('buttons-container', true);

ui.floatingCartButton(showItemsCount?: boolean): void

Automatically inject a floating cart button:

client.ui.floatingCartButton();

// With items count badge
client.ui.floatingCartButton(true);

Live Cart Display

ui.cartTotal(elementId: string): void

Bind an element to display the live cart total (automatically updates when cart changes):

client.ui.cartTotal('cart-total-display');

ui.cartItemsCount(elementId: string): void

Bind an element to display the live cart items count (automatically updates when cart changes):

client.ui.cartItemsCount('cart-items-badge');

Builder Methods (Development Mode)

When isBuilder: true is set, additional methods are available for theme customization:

const client = await Elements('YOUR_API_KEY', {
  env: 'development',
  isBuilder: true
});

// Update component themes
await client.builder.updateComponentGlobalConfigs(globalTheme);
await client.builder.updateProductComponent(productTheme);
client.builder.updateCartComponent(cartTheme);
client.builder.updateCheckoutComponent(checkoutTheme);
client.builder.updateAddressComponent(addressTheme);

// Builder injection methods (same as regular methods)
await client.builder.injectProductElement(params);
await client.builder.injectCartElement(containerId);
await client.builder.injectCheckoutElement(containerId);
await client.builder.injectAddressElement(containerId);

🎬 Actions

Actions provide programmatic control over SDK components. Access them via client.actions or window.elements.actions:

// Available after client initialization
const actions = client.actions;
// OR globally
const actions = window.elements.actions;

Product Actions

// Get product details
const product = actions.product.getDetails('product-123');
console.log(product.productName, product.price, product.isAvailable);

Address Actions

// Set address using Google Places ID
await actions.address.setAddressByPlacesId('ChIJ0SRjyK5ZwokRp1TwT8dJSv8');

// Set address manually without Google Places (perfect for custom address forms)
await actions.address.setAddressManually(
  {
    one: '123 Main St',
    two: 'Apt 4B',          // Optional apartment/suite
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'United States' // Optional, will be included in formatted address
  },
  {
    lat: 40.7505045,
    long: -73.9934387
  }
);

// Listen for success/failure via events
window.addEventListener('lce:actions.address_updated', function(event) {
  const address = event.detail.data;
  console.log('✅ Address set!', address.formattedAddress);
  updateShippingOptions(address.coordinates);
});

window.addEventListener('lce:actions.address_failed', function(event) {
  const error = event.detail.data;
  console.log('❌ Address failed:', error.message);
  showAddressForm();
});

// Get current address
const address = actions.address.getDetails();

// Clear saved address
actions.address.clear();

Notes:

• To find Google Places IDs for the setAddressByPlacesId action, use the Google Places ID Finder
• The setAddressManually action automatically generates a Google Places API-formatted address string from the provided components
• Manual addresses have an empty Places ID (as they don't come from Google Places API)

Action Feedback: All actions provide feedback through events. Listen for success/failure events to handle results and provide user feedback.

Cart Actions

// Control cart visibility
actions.cart.openCart();
actions.cart.closeCart();
actions.cart.toggleCart();

// Add products to cart
await actions.cart.addProduct([{
  identifier: 'product-123',
  fulfillmentType: 'shipping', // or 'onDemand'
  quantity: 2
}]);

// Listen for add product feedback
window.addEventListener('lce:actions.cart_product_add_success', function(event) {
  const { itemsAdded, identifiers } = event.detail.data;
  console.log(`✅ Added ${itemsAdded} products to cart:`, identifiers);
  showSuccessMessage('Products added to cart!');
});

window.addEventListener('lce:actions.cart_product_add_failed', function(event) {
  const { identifiers, error } = event.detail.data;
  console.log(`❌ Failed to add products:`, error);
  showErrorMessage('Could not add products. Please try again.');
});

// Apply promo codes
await actions.cart.applyPromoCode('WELCOME10');

// Listen for promo code feedback
window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
  const { applied, discountAmount, newTotal } = event.detail.data;
  console.log(`✅ Promo applied! Discount: $${discountAmount}, New total: $${newTotal}`);
  showSavingsMessage(discountAmount);
});

window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
  const { attempted, error } = event.detail.data;
  console.log(`❌ Promo failed:`, error);
  showErrorMessage('Promo code could not be applied');
});

// Remove promo codes
await actions.cart.removePromoCode();

// Get cart details
const cart = actions.cart.getDetails();
console.log(cart.total, cart.items.length);

// Reset cart
await actions.cart.resetCart();

Checkout Actions

// Control checkout visibility
actions.checkout.openCheckout();
actions.checkout.closeCheckout();
actions.checkout.toggleCheckout();

// Pre-fill customer information
actions.checkout.updateCustomerInfo({
  firstName: 'John',
  lastName: 'Doe',
  email: '[e-mail]',
  phone: '[phone]'
});

// Pre-fill billing information
actions.checkout.updateBillingInfo({
  firstName: 'John',
  lastName: 'Doe',
  street1: '123 Main St',
  city: 'Anytown',
  state: 'CA',
  zipCode: '12345'
});

// Manage gift options
await actions.checkout.toggleIsGift(true);
actions.checkout.updateGiftInfo({
  giftMessage: 'Happy Birthday!',
  giftFrom: 'Your Friend'
});

// Apply discounts and gift cards
await actions.checkout.applyPromoCode('SAVE20');
await actions.checkout.applyGiftCard('GIFT123');

// Listen for checkout promo code feedback
window.addEventListener('lce:actions.checkout_promo_code_applied', function(event) {
  const { applied, discountAmount, newTotal } = event.detail.data;
  console.log(`✅ Checkout promo applied! Saved: $${discountAmount}`);
  updateCheckoutTotal(newTotal);
});

window.addEventListener('lce:actions.checkout_promo_code_failed', function(event) {
  const { attempted, error } = event.detail.data;
  console.log(`❌ Checkout promo failed:`, error);
  showCheckoutError('Promo code could not be applied');
});

// Listen for gift card feedback
window.addEventListener('lce:actions.checkout_gift_card_applied', function(event) {
  const { applied, newTotal } = event.detail.data;
  console.log('✅ Gift card applied successfully!');
  updateCheckoutTotal(newTotal);
  showSuccessMessage('Gift card applied to your order');
});

window.addEventListener('lce:actions.checkout_gift_card_failed', function(event) {
  const { attempted, error } = event.detail.data;
  console.log(`❌ Gift card failed:`, error);
  showCheckoutError('Gift card could not be applied');
});

// Get checkout details (safe, non-sensitive data only)
const checkout = actions.checkout.getDetails();
console.log('Total:', checkout.amounts.total);
console.log('Items:', checkout.itemCount);
console.log('Is gift:', checkout.isGift);
console.log('Has age verification:', checkout.hasAgeVerify);
console.log('Has promo code:', checkout.hasPromoCode);
console.log('Has gift cards:', checkout.hasGiftCards);

// Configure checkout options
await actions.checkout.toggleBillingSameAsShipping(true);
actions.checkout.toggleMarketingPreferences('canEmail', true);

See docs/ACTIONS.md for complete action reference with business use cases.

📡 Events

The SDK emits real-time events for all user interactions. Listen to these events to trigger custom behavior:

// Listen for specific events
window.addEventListener('lce:actions.product_add_to_cart', function(event) {
  const product = event.detail.data;
  console.log('Added to cart:', product.productName);
  
  // Your custom logic here
  analytics.track('Product Added', {
    product: product.productName,
    price: product.price
  });
});

// Or use the helper methods (available after initialization)
window.elements.onAllForms((data, metadata) => {
  console.log('Form Event', { data, metadata });
});

window.elements.onAllActions((data, metadata) => {
  console.log('Action Event', { data, metadata });
});

Available Events

Product Events

• lce:actions.product_loaded - Product component loaded
• lce:actions.product_add_to_cart - Item added to cart
• lce:actions.product_quantity_increase - Quantity increased
• lce:actions.product_quantity_decrease - Quantity decreased
• lce:actions.product_size_changed - Product size/variant changed
• lce:actions.product_fulfillment_type_changed - Delivery method changed

Cart Events

• lce:actions.cart_opened - Cart displayed
• lce:actions.cart_closed - Cart hidden
• lce:actions.cart_updated - Cart contents changed
• lce:actions.cart_item_added - Item added
• lce:actions.cart_item_removed - Item removed
• lce:actions.cart_reset - Cart cleared

Checkout Events

• lce:actions.checkout_opened - Checkout started
• lce:actions.checkout_closed - Checkout abandoned
• lce:actions.checkout_submit_started - Order submission began
• lce:actions.checkout_submit_completed - Order completed successfully
• lce:actions.checkout_submit_failed - Order failed
• lce:actions.checkout_customer_information_updated - Customer info entered
• lce:actions.checkout_billing_information_updated - Billing info entered

Address Events

• lce:actions.address_updated - Address information changed
• lce:actions.address_cleared - Address removed

See docs/EVENTS.md for complete event reference with implementation examples.

⚙️ Configuration

Configure the SDK when initializing:

const client = await Elements('YOUR_API_KEY', {
  env: 'production', // 'local' | 'development' | 'staging' | 'production'
  enableDebugging: false, // Enable console logging (development only)
  isBuilder: false, // Enable builder methods (development only)
  customTheme: { /* theme overrides */ },
  proxy: { /* proxy configuration */ }
});

Environment Options

• production: Live environment for customer-facing sites
• staging: Pre-production testing environment
• development: Development environment with additional debugging
• local: Local development environment

Auto-init Data Attributes

When using auto-initialization, configure via data attributes:

• data-liquid-commerce-elements: Required flag to enable auto-init
• data-token: Your API key (required)
• data-env: Environment (defaults to production)
• data-cart-id: Container ID for cart button
• data-enable-debugging: Enable debugging mode
• data-container-X / data-product-X: Product mapping pairs

🎨 Themes & Customization

Customize the appearance of SDK components using the theme system:

const client = await Elements('YOUR_API_KEY', {
  env: 'production',
  customTheme: {
    global: {
      colors: {
        primary: '#007bff',
        secondary: '#6c757d'
      },
      typography: {
        fontFamily: 'Roboto, sans-serif',
        fontSize: '16px'
      }
    },
    product: {
      layout: {
        imagePosition: 'left',
        showDescription: true
      },
      colors: {
        price: '#28a745',
        sale: '#dc3545'
      }
    },
    cart: {
      layout: {
        showRetailerLogos: true,
        compactMode: false
      }
    },
    checkout: {
      layout: {
        singlePage: true,
        showOrderSummary: true
      }
    }
  }
});

In builder mode, themes can be updated dynamically:

// Update themes in real-time (builder mode only)
await client.builder.updateComponentGlobalConfigs({
  colors: { primary: '#ff6b6b' }
});

await client.builder.updateProductComponent({
  layout: { imagePosition: 'right' }
});

🔒 Proxy Configuration

Route API requests through your server to avoid ad blockers:

const client = await Elements('YOUR_API_KEY', {
  env: 'production',
  proxy: {
    baseUrl: 'https://yourdomain.com/api/liquidcommerce',
    headers: {
      'X-Custom-Header': 'value'
    }
  }
});

The SDK automatically handles routing and required headers. See docs/PROXY.md for complete proxy setup guide with Next.js examples.

📚 Documentation

For detailed guides and advanced usage:

• docs/ACTIONS.md - Complete actions reference with business use cases
• docs/EVENTS.md - Events guide with implementation examples
• docs/BROWSER_SUPPORT.md - Detailed browser compatibility
• docs/PROXY.md - Proxy configuration for ad blocker avoidance

🏷️ Versioning

This project uses Semantic Versioning. The SDK is available in two environments:

Beta Environment

• Branch: beta
• Base URL: https://assets-elements.liquidcommerce.us/all/beta/
• Purpose: Testing and pre-release features

Production Environment

• Branch: main
• Base URL: https://assets-elements.liquidcommerce.us/all/
• Purpose: Stable releases for production use

CDN Path Structure

elements-sdk/
└── all/
    ├── beta/
    │   ├── 1.2.3/elements.js
    │   ├── 1.2.4/elements.js
    │   └── elements.js  (beta latest)
    ├── 1.2.2/elements.js  (production)
    ├── 1.2.3/elements.js  (production)
    └── elements.js  (production latest)

🎭 Demo Pages

The SDK includes ready-to-use demo pages in the demo/ folder that showcase different implementation approaches:

Simple Demo (demo/simple.html)

Demonstrates auto-initialization using data attributes - the easiest way to get started:

<!-- Auto-init with data attributes -->
<script
  data-liquid-commerce-elements
  data-token="YOUR_API_KEY"
  data-env="development"
  data-enable-debugging
  src="../umd/elements.js"
></script>

Features shown:

• Auto-initialization with data attributes
• Multiple product mapping methods (data attributes, JSON script, annotated elements)
• Event listening for actions and forms
• Basic container setup for products, cart, and checkout

Best for: Quick prototyping, simple integrations, getting familiar with the SDK

Advanced Demo (demo/advanced.html)

Demonstrates programmatic initialization for full control:

const client = await window.Elements(API_KEY, {
  env: "development",
  enableDebugging: true,
  customTheme: { /* theme config */ }
});

// Programmatic component injection
client.buttons.openCart("buttons-container");
await client.injectProductElement([
  { containerId: "pdp-container", identifier: '00619947000020' }
]);
await client.injectCheckoutElement("checkout-container");

Features shown:

• Manual client initialization with full configuration
• Programmatic component injection
• Builder methods for theme updates (commented examples)
• Advanced event handling
• Dynamic theme updates

Best for: Complex integrations, custom workflows, theme customization, production implementations

Running the Demos

• Clone the repository
• Open demo files in your browser
• Update API keys with your own credentials
• Modify environment settings as needed (development, staging, production)

The demos use local UMD builds (../umd/elements.js) but can be easily switched to CDN URLs for testing.

🛠️ Development Scripts

For SDK development and maintenance, the following npm/pnpm scripts are available:

Build Commands

build - Production build

pnpm run build

• Creates optimized ESM and UMD bundles for production
• Generates TypeScript declarations
• Enables minification and compression
• Removes console logs and debugging code
• Output: dist/index.esm.js (ESM) + umd/elements.js (UMD)

build:dev - Development build

pnpm run build:dev

• Creates unminified bundles with source maps
• Preserves console logs and debugging code
• Faster build times for development
• Output: Same as build but with debugging enabled

dev - Development with watch mode

pnpm run dev

• Same as build:dev but watches for file changes
• Automatically rebuilds on source code changes
• Best for: Active development

Code Quality Commands

lint - Lint and auto-fix code

pnpm run lint

• Uses Biome to lint TypeScript/JavaScript files
• Automatically fixes fixable issues
• Enforces code style and catches common errors

format - Format code

pnpm run format

• Uses Biome to format all source files
• Ensures consistent code formatting
• Applies formatting rules defined in biome.json

check - Combined linting and formatting

pnpm run check

• Runs both linting and formatting in one command
• Auto-fixes issues and formats code
• Recommended before commits

fl - Format, lint, and build (Fast Loop)

pnpm run fl

• Combines check + build:dev
• Complete code quality check + development build
• Perfect for: Pre-commit workflow

Maintenance Commands

clean - Clean build outputs

pnpm run clean

• Removes dist/ and umd/ directories
• Use when: Build artifacts are corrupted

clean:hard - Complete reset

pnpm run clean:hard

• Removes build outputs AND node_modules/
• Reinstalls all dependencies with pnpm install
• Runs a fresh production build
• Use when: Dependency issues or major updates

changelog - Generate changelog

pnpm run changelog

• Generates CHANGELOG.md from conventional commits
• Uses Angular commit convention
• Use when: Preparing releases

Build Configuration

The build system uses Rollup with different configurations:

ESM Build (dist/index.esm.js)

• Target: Modern bundlers (Vite, Webpack, etc.)
• Format: ES Modules
• Optimizations: Tree shaking, modern syntax
• Use case: NPM package imports

UMD Build (umd/elements.js)

• Target: Direct browser usage
• Format: Universal Module Definition
• Global: window.LiquidCommerceElements
• Optimizations: Maximum browser compatibility
• Use case: CDN distribution, <script> tags

Development vs Production

• Development: Source maps, preserved logging, faster builds
• Production: Minified, compressed, optimized for size

Recommended Workflows

Development Workflow:

# Start development
pnpm run dev

# Before committing
pnpm run fl

Release Workflow:

# Clean and build for release
pnpm run clean:hard

# Generate changelog
pnpm run changelog

# Build is run automatically on publish

Troubleshooting:

# If builds are failing
pnpm run clean:hard

# For code quality issues
pnpm run check

💬 Support

If you need help with your API key, environment selection, or implementation, contact your LiquidCommerce representative.

Built with ❤️ by the LiquidCommerce Team

Actions Reference • Events Guide • Browser Support • Proxy Setup