🚀 WidgetFlow SDK

Official Client SDK for WidgetFlow SaaS - Embed visual components built with WidgetFlow into any web application

✨ Features

• 🎯 Shadow DOM Isolation - No style conflicts with your existing app
• 🔧 Framework Agnostic - Works with React, Vue, Angular, or vanilla JavaScript
• ⚡ Zero Configuration - Auto-initialize with data attributes
• 📦 Lightweight - Minimal bundle size, maximum performance
• 🎨 WidgetFlow Integration - Seamlessly embed components built with WidgetFlow SaaS
• 🔒 Type Safe - Full TypeScript support with IntelliSense

🚀 Quick Start

1. Installation

npm install @widgetflow/sdk
# or
yarn add @widgetflow/sdk
# or
pnpm add @widgetflow/sdk

2. Basic Usage

Method 1: Programmatic Initialization

import { WidgetFlow } from '@widgetflow/sdk'

// Initialize widget
const widget = new WidgetFlow({
  selector: '#my-widget',
  theme: 'light'
})

Method 2: Auto-initialization with Data Attributes

<!-- No JavaScript required! -->
<div id="my-widget" data-widgetflow></div>

Method 3: CDN Usage

<script src="https://unpkg.com/@widgetflow/sdk@latest/dist/widgetflow-sdk.umd.js"></script>
<script>
  const widget = new WidgetFlow({
    selector: '#my-widget'
  })
</script>

📖 API Reference

WidgetFlow Class

Constructor

new WidgetFlow(config: WidgetFlowConfig)

Configuration Options

interface WidgetFlowConfig {
  selector: string        // CSS selector for target element
  theme?: 'light' | 'dark' | 'auto'  // Theme preference
  apiKey?: string         // Your WidgetFlow API key (required for production)
  widgetId?: string       // Specific widget ID from WidgetFlow platform
}

Methods

| Method | Description | Returns | |--------|-------------|---------| | destroy() | Remove widget and clean up resources | void | | updateContent(html: string) | Update widget content | void | | getVersion() | Get SDK version | string |

Global Functions

// Alternative initialization method
initWidgetFlow(config: WidgetFlowConfig): WidgetFlow

🎨 Integration with WidgetFlow SaaS

API Key Setup

To embed widgets created in WidgetFlow platform:

const widget = new WidgetFlow({
  selector: '#my-widget',
  apiKey: 'your-widgetflow-api-key',  // Get this from WidgetFlow dashboard
  widgetId: 'widget-123',             // Widget ID from WidgetFlow platform
  theme: 'light'
})

Theme Support

const widget = new WidgetFlow({
  selector: '#my-widget',
  theme: 'dark'  // 'light', 'dark', or 'auto'
})

Note: This is currently a demo version showing "Hello World". Full WidgetFlow SaaS integration coming soon.

🔧 Framework Integration

React

import { useEffect, useRef } from 'react'
import { WidgetFlow } from '@widgetflow/sdk'

function MyComponent() {
  const widgetRef = useRef(null)

  useEffect(() => {
    const widget = new WidgetFlow({
      selector: '#widget-container'
    })

    return () => widget.destroy()
  }, [])

  return <div id="widget-container" ref={widgetRef} />
}

Vue 3

<template>
  <div ref="widgetContainer" />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { WidgetFlow } from '@widgetflow/sdk'

const widgetContainer = ref(null)
let widget = null

onMounted(() => {
  widget = new WidgetFlow({
    selector: widgetContainer.value
  })
})

onUnmounted(() => {
  widget?.destroy()
})
</script>

Angular

import { Component, ElementRef, OnDestroy, OnInit, ViewChild } from '@angular/core'
import { WidgetFlow } from '@widgetflow/sdk'

@Component({
  selector: 'app-widget',
  template: '<div #widgetContainer></div>'
})
export class WidgetComponent implements OnInit, OnDestroy {
  @ViewChild('widgetContainer') widgetContainer!: ElementRef
  private widget?: WidgetFlow

  ngOnInit() {
    this.widget = new WidgetFlow({
      selector: this.widgetContainer.nativeElement
    })
  }

  ngOnDestroy() {
    this.widget?.destroy()
  }
}

🛠️ Development

Build the SDK

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build for production
pnpm build

# Preview built version
pnpm preview

Testing

Open index.html in your browser or run the dev server:

pnpm dev

Then visit http://localhost:3001 to see the interactive demo.

🏗️ Architecture

┌─────────────────────────────────────┐
│           Your Web App              │
│  ┌─────────────────────────────────┐│
│  │      WidgetFlow SDK             ││
│  │  ┌─────────────────────────────┐││
│  │  │      Shadow DOM             │││
│  │  │   (Isolated Styles)         │││
│  │  │                             │││
│  │  │   [Your Widget Content]     │││
│  │  │                             │││
│  │  └─────────────────────────────┘││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘

📝 License

This SDK is proprietary software owned by WidgetFlow. The SDK is free to use for integrating with WidgetFlow SaaS platform.

Built by the WidgetFlow Team