Installation

Choose the installation method that best fits your project setup.

CDN (Recommended for Quick Start)

The simplest way to get started. Add the script tag to your HTML:

<!-- Development (with source maps) -->
<script src="https://js.qariyb.com/v1/qariyb.js"></script>

<!-- Production (minified) -->
<script src="https://js.qariyb.com/v1/qariyb.min.js"></script>

With Configuration

<script>
  window.QariybConfig = {
    publishableKey: 'pk_live_...',
    theme: 'light',
  };
</script>
<script src="https://js.qariyb.com/v1/qariyb.js"></script>

Always load your configuration before the SDK script.

npm / yarn / pnpm

For modern JavaScript projects with bundlers:

Install

npm install @qariyb/js

ESM Import

// Import registers all web components automatically
import '@qariyb/js';

// Optional: import specific exports
import { VERSION, QariybCheckout } from '@qariyb/js';

CommonJS

// Registers all web components
require('@qariyb/js');

TypeScript Support

The package includes TypeScript definitions. Import types directly:

import type {
  QariybConfig,
  QariybEvent,
  TicketType,
  Cart,
  Order,
  OrderTicket,
  CheckoutSuccessDetail,
} from '@qariyb/js';

Typed Event Listeners

import type { QariybCustomEvent, CheckoutSuccessDetail } from '@qariyb/js';

document.addEventListener('qariyb:checkout:success', ((
  e: QariybCustomEvent<CheckoutSuccessDetail>
) => {
  const { order, tickets } = e.detail.data;
  console.log(order.id, tickets.length);
}) as EventListener);

Bundler Configuration

Vite

Works out of the box. No configuration needed.

// vite.config.js
export default {
  // @qariyb/js works with default settings
};

Webpack

Add to your entry file:

// index.js
import '@qariyb/js';

Rollup

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';

export default {
  plugins: [resolve()],
};

Package Exports

The package provides multiple build formats:

Export	Path	Use Case
ESM	`dist/qariyb.esm.js`	Modern bundlers (Vite, Webpack 5)
UMD	`dist/qariyb.umd.js`	Legacy bundlers, script tags
Types	`dist/index.d.ts`	TypeScript support

Direct Imports

// ESM (default for import)
import '@qariyb/js';

// Specific build
import '@qariyb/js/qariyb.js';
import '@qariyb/js/qariyb.min.js';

Version Information

Check the loaded SDK version:

import { VERSION } from '@qariyb/js';
console.log('Qariyb Embed version:', VERSION);

Or from the global:

// After loading via CDN
console.log('Loaded version:', window.Qariyb?.VERSION);

Content Security Policy (CSP)

If your site uses CSP, add these directives:

script-src 'self' https://js.qariyb.com https://js.stripe.com;
frame-src https://js.stripe.com;
connect-src https://api.qariyb.com https://api.stripe.com;

Subresource Integrity (SRI)

For additional security with CDN usage:

<script
  src="https://js.qariyb.com/v1/qariyb.min.js"
  integrity="sha384-HASH_HERE"
  crossorigin="anonymous"
></script>

SRI hashes are published with each release in the changelog.

Verifying Installation

Test that the SDK loaded correctly:

<script>
  // Check if web component is registered
  if (customElements.get('qariyb-checkout')) {
    console.log('Qariyb Embed loaded successfully!');
  }

  // Listen for SDK initialization
  window.addEventListener('qariyb:initialized', (e) => {
    console.log('SDK initialized:', e.detail.data.version);
  });
</script>

Next Steps

Basic Integration - Add your first checkout widget
React Integration - Framework-specific setup
Customization - Style widgets to match your brand