Installation & Setup

Installation

Include the Komerza client library via CDN. Add this script tag to your HTML:

<script src="https://cdn.komerza.com/komerza.min.js"></script>

The library is available globally as globalThis.komerza after the script loads.

CDN Benefits

No build step required - Works with plain HTML/CSS/JS
Always up-to-date - Latest version automatically delivered
Fast loading - Cached globally via CDN
Lightweight - Minimal impact on page load time

Initialization

Initialize the library with your store ID before using any other functions:

komerza.init("your-store-id");

You must call init() before using any other komerza function. All other functions will fail if the library hasn’t been initialized.

Finding Your Store ID

Your store ID is available in your Komerza dashboard. It’s a unique identifier for your store, typically in UUID format.

Example

<!DOCTYPE html>
<html>
  <head>
    <title>My Store</title>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
  </head>
  <body>
    <div id="store-name"></div>

    <script>
      // Initialize with your store ID
      komerza.init("550e8400-e29b-41d4-a716-446655440000");

      // Now you can use other komerza functions
      komerza.getStore().then((response) => {
        if (response.success) {
          document.getElementById("store-name").textContent =
            response.data.name;
        }
      });
    </script>
  </body>
</html>

When to Initialize

Call init() once when your page loads, before using any other komerza methods: ✅ Good - Initialize on page load:

<script>
  // Initialize immediately komerza.init('your-store-id'); // Then use other
  functions displayProducts();
</script>

❌ Bad - Using methods before init:

<script>
  // This will fail - init not called yet komerza.getStore(); // Error!
  komerza.init('your-store-id');
</script>

Framework Integration

Vanilla JavaScript

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
  </head>
  <body>
    <script>
      komerza.init("your-store-id");
    </script>
  </body>
</html>

React

import { useEffect } from "react";

function App() {
  useEffect(() => {
    // Initialize when component mounts
    if (globalThis.komerza) {
      globalThis.komerza.init("your-store-id");
    }
  }, []);

  return <div>My Store</div>;
}

Vue

<script>
export default {
  mounted() {
    // Initialize when component mounts
    if (globalThis.komerza) {
      globalThis.komerza.init("your-store-id");
    }
  },
};
</script>

Svelte

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    // Initialize when component mounts
    if (globalThis.komerza) {
      globalThis.komerza.init('your-store-id');
    }
  });
</script>

Build Process

The Komerza client library works with any framework or build process-the script runs in the browser regardless of how you build your site. Use any framework:

Plain HTML/CSS/JS (no build needed)
React, Vue, Svelte, Angular
Next.js, Nuxt, SvelteKit, Astro
Webpack, Vite, Rollup, Parcel

Hosting requirement: To host your storefront on Komerza infrastructure or list it on the theme marketplace, your project must compile to static HTML/CSS/JS files. Server-side rendering at runtime is not supported.

TypeScript Support

If you’re using TypeScript, you can add type definitions:

declare global {
  var komerza: {
    init(storeId: string): void;
    getStore(): Promise<ApiResponse<Store>>;
    getBasket(): BasketItem[];
    checkout(email: string, coupon?: string): Promise<ApiResponse<Order>>;
    // ... other methods
  };
}

// Use with types
globalThis.komerza.init("your-store-id");

Type definitions are available in the script.json file for reference.

Verification

Verify the library is loaded and initialized correctly:

// Check if library is loaded
if (typeof komerza === "undefined") {
  console.error("Komerza library not loaded");
} else {
  console.log("Komerza library loaded successfully");

  // Initialize
  komerza.init("your-store-id");

  // Verify initialization by fetching store
  komerza.getStore().then((response) => {
    if (response.success) {
      console.log("Store loaded:", response.data.name);
    } else {
      console.error("Failed to load store:", response.message);
    }
  });
}

Troubleshooting

“komerza is not defined”

Make sure the script tag is loaded before your code runs
Check browser console for script loading errors
Verify the CDN URL is correct

“Komerza.init must be called before using this method”

Call komerza.init() before using other functions
Ensure init is called only once per page load

Store not loading

Verify your store ID is correct (check dashboard)
Check browser console for API errors
Ensure you’re connected to the internet

Next Steps

Now that you’ve initialized the library, learn how to use it:

Store Information

Fetch store details, logo, and banner

Products

Display and manage product listings

Basket Management

Handle shopping cart operations

Checkout

Process orders and payments

Getting Started

Client Library

Installation

CDN Benefits

Initialization

Finding Your Store ID

Example

When to Initialize

Framework Integration

Vanilla JavaScript

React

Vue

Svelte

Build Process

TypeScript Support

Verification

Troubleshooting

Next Steps

Store Information

Products

Basket Management

Checkout

​Installation

​CDN Benefits

​Initialization

​Finding Your Store ID

​Example

​When to Initialize

​Framework Integration

​Vanilla JavaScript

​React

​Vue

​Svelte

​Build Process

​TypeScript Support

​Verification

​Troubleshooting

​Next Steps

Store Information

Products

Basket Management

Checkout

Installation

CDN Benefits

Initialization

Finding Your Store ID

Example

When to Initialize

Framework Integration

Vanilla JavaScript

React

Vue

Svelte

Build Process

TypeScript Support

Verification

Troubleshooting

Next Steps