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-web-components-sdk

2. Use Components (No initialization required!)

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

📚 Examples

Explore real-world integration examples:

• React Integration - Complete React app with TypeScript, multiple configurations, and external submit control
• HTML Examples - Basic HTML integration examples
• Embedded Examples - SDK embedded in external platforms

React Example Features:

• ✅ TypeScript integration
• ✅ Multiple display configurations
• ✅ External submit control
• ✅ Transaction data examples
• ✅ Responsive design
• ✅ Error handling

cd examples/react
pnpm install
pnpm run dev

📘 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-web-components-sdk/config';
// or
import { defineCustomElements } from 'rebill-web-components-sdk/loader';

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

See the TypeScript JSX Setup Guide for more details and alternative solutions.

// Or programmatically
import { defineCustomElements } from 'rebill-web-components-sdk/loader';
defineCustomElements(window);

3. Optional: Configure for Different Environments

import { initializeRebillSDK } from 'rebill-web-components-sdk';

// 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-web-components-sdk';

// 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-web-components-sdk';

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

🚀 Publishing

Prerequisites

• Access: write permissions to the repository and the NPM package.
• Secrets: NPM_TOKEN configured in the repository Secrets (used to publish). GITHUB_TOKEN is provided by Actions by default.

GitHub Actions Workflow

Publish Package to NPM

Use the "Publish package to NPM" workflow for both staging and production releases.

1. In GitHub, go to Actions → "Publish package to NPM" → Run workflow.
2. Fill in the inputs:
   • release_type: staging or production.
   • version_strategy: patch, minor, major, or prerelease (only for staging).

Examples:

• staging + patch → 1.1.14-beta.0 (new patch prerelease)
• staging + prerelease → 1.1.14-beta.1 (increment prerelease)
• production + patch → 1.1.14 (stable release)

3. The workflow will automatically:
   • Build the SDK (environment-agnostic)
   • Run tests
   • Bump version (prerelease for staging, stable for production)
   • Publish with appropriate tag (stage or latest)
   • Create git tag and GitHub release

Installation from NPM

# Staging (prerelease channel)
pnpm install rebill-web-components-sdk@stage

# Production (stable channel)
pnpm install rebill-web-components-sdk@latest

Manual Publishing (Alternative)

# Install dependencies
pnpm install --frozen-lockfile

# Build (environment-agnostic)
pnpm run build

# Test
pnpm test

# Pack and verify (optional but recommended)
pnpm pack

# Publish staging
pnpm version prepatch --preid beta
pnpm publish --tag stage

# Publish staging (new prerelease)
pnpm version prepatch --preid beta
pnpm publish --tag stage

# Publish staging (increment prerelease)
pnpm version prerelease --preid beta
pnpm publish --tag stage

# Publish production
pnpm version patch
pnpm publish

Note: The GitHub Actions workflow follows these exact same steps automatically.

Key Changes

• Single build for all environments (environment-agnostic)
• Runtime configuration instead of compile-time
• Simplified workflows with fewer inputs
• Consistent versioning across environments

🚀 Assets Configuration (CDN vs Local)

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

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

Basic Usage (CDN - No Configuration)

import { initializeRebillSDK } from 'rebill-web-components-sdk';
import { defineCustomElements } from 'rebill-web-components-sdk/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-web-components-sdk';
import { defineCustomElements } from 'rebill-web-components-sdk/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-web-components-sdk/dist/assets/ to your public folder.

Option 2: Using setAssetsURL (Alternative)

import { defineCustomElements } from 'rebill-web-components-sdk/loader';
import { setAssetsURL } from 'rebill-web-components-sdk';

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

Complete Example - React with Local Assets

import { useEffect } from 'react';
import { initializeRebillSDK } from 'rebill-web-components-sdk';
import { defineCustomElements } from 'rebill-web-components-sdk/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