Rebill Web Components SDK (v3.1)

A framework‑agnostic Web Components SDK (built with Stencil) to embed Rebill checkout, payments, and renewal flows in any website or app.

This SDK provides production‑ready components (checkout form, payment method selector, card iframe, OTP, discounts, summary, renewal), dynamic runtime configuration, i18n support, and a lightweight loader for easy integration.

🚀 Quick Start

Prerequisites

• Node.js: >= 16.0.0
• pnpm: >= 8.0.0 (required)

Install pnpm globally if you haven't already:

npm install -g pnpm

1. Install the SDK

pnpm install rebill

2. Use Components (No initialization required!)

<!-- Your HTML - works out of the box with production settings -->
<rebill-checkout></rebill-checkout>

📘 TypeScript / JSX Support

TypeScript support is now automatic! 🎉

If you were experiencing this error:

Property 'rebill-checkout' does not exist on type 'JSX.IntrinsicElements'.

Just update to the latest version and import from the SDK:

import { initializeRebillSDK } from 'rebill/config';
// or
import { defineCustomElements } from 'rebill/loader';

The JSX types will load automatically. No tsconfig.json configuration needed!

// Or programmatically
import { defineCustomElements } from 'rebill/loader';
defineCustomElements(window);

3. Optional: Configure for Different Environments

import { initializeRebillSDK } from 'rebill';

// Only needed if you want to use staging or development
initializeRebillSDK({
  environment: 'staging', // 'development' | 'staging' | 'production'
  debug: true,
});

🔧 Configuration

The SDK works out of the box with production settings. Configuration is optional and only needed for staging or development environments.

Default Behavior

• Production environment by default
• No initialization required for client applications
• Production API endpoints automatically used

Optional Environment Configuration

import { initializeRebillSDK } from 'rebill';

// For staging with CDN assets (optional)
initializeRebillSDK({
  environment: 'staging',
  debug: true,
});

// For staging with local assets
initializeRebillSDK({
  environment: 'staging',
  debug: true,
  assetsUrl: '/sdk/', // Serve assets from local path
});

// For development (optional)
initializeRebillSDK({
  environment: 'development',
  debug: true,
});

// For production (optional - this is the default)
initializeRebillSDK({
  environment: 'production',
  debug: false,
});

Quick Helpers

import { RebillSDK } from 'rebill';

// Quick setup (all optional)
RebillSDK.forProduction(); // Default behavior
RebillSDK.forStaging(); // For testing
RebillSDK.forDevelopment(); // For local development

🚀 Assets Configuration (CDN vs Local)

By default, assets are loaded automatically from CDN. No configuration needed.

The SDK automatically uses https://unpkg.com/rebill@[version]/assets/ to load icons and animations.

Basic Usage (CDN - No Configuration)

import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

// Assets load automatically from CDN
initializeRebillSDK({
  environment: 'staging',
  debug: true,
});

defineCustomElements(window);

Using Local Assets

Option 1: Configure via initializeRebillSDK (Recommended)

import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

// Configure local assets
initializeRebillSDK({
  environment: 'staging',
  debug: true,
  assetsUrl: '/sdk/', // Use local assets from /sdk/ path
});

defineCustomElements(window);

Important: When using assetsUrl, you must ensure the assets are available at that path. Copy the assets folder from node_modules/rebill/dist/assets/ to your public folder.

Option 2: Using setAssetsURL (Alternative)

import { defineCustomElements } from 'rebill/loader';
import { setAssetsURL } from 'rebill';

// Configure assets before defining elements
setAssetsURL('/sdk/');
defineCustomElements(window);

Complete Example - React with Local Assets

import { useEffect } from 'react';
import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

export function useRebillSDK() {
  useEffect(() => {
    const environment = process.env.NEXT_PUBLIC_NODE_ENV as
      | 'development'
      | 'staging'
      | 'production';

    if (environment === 'development' || environment === 'staging') {
      // Use local assets in development/staging
      initializeRebillSDK({
        environment: 'staging',
        debug: true,
        assetsUrl: '/sdk/', // Serve from /public/sdk/ folder
      });
    } else {
      // Use CDN in production
      initializeRebillSDK({
        environment: 'production',
        debug: false,
      });
    }

    defineCustomElements(window);
  }, []);
}

CDN Benefits

• ✅ Zero configuration - Works immediately
• ✅ Global cache - Faster asset loading
• ✅ Automatic versioning - Always uses the correct version
• ✅ No manual copies - No need to copy files
• ✅ Flexible - Can override URL when needed

Local Assets Benefits

• ✅ Full control - Assets served from your domain
• ✅ Offline support - Works without external CDN
• ✅ Custom builds - Can modify assets if needed
• ✅ Privacy - No external requests