@bluvo/widget-vanjs

v0.1.34

Published

6 days ago

Bluvo widget implemented with VanJS for embedding in vanilla JavaScript applications

Downloads

200

0High
0Medium
0Low

fl0wo

bluvo widget vanjs cryptocurrency exchange crypto vanilla-js

Bluvo Widget for VanJS

A lightweight, fast implementation of the Bluvo widget using VanJS for vanilla JavaScript applications. This library provides a simple way to embed crypto exchange integration in your web application.

Features

Connect to various crypto exchanges
Perform transactions
Customizable theme
Lightweight VanJS implementation
No framework dependencies
TypeScript support

Installation

npm install @bluvo/widget-vanjs

Or with yarn:

yarn add @bluvo/widget-vanjs

Or with pnpm:

pnpm add @bluvo/widget-vanjs

Basic Usage

ES Modules

import { initBluvoWidget } from '@bluvo/widget-vanjs';

// Initialize the widget
const widget = initBluvoWidget({
  container: '#widget-container',
  auth: {
    projectId: 'your-project-id',
    orgId: 'your-org-id'
  },
  mode: 'connect',
  theme: {
    dark: true,
    accentColor: '#3B82F6'
  }
});

// To destroy the widget when needed
// widget.destroy();

UMD (Script Tag)

<!-- Include the UMD build in your HTML -->
<script src="https://unpkg.com/@bluvo/widget-vanjs/dist/bluvo-widget.umd.js"></script>

<script>
  // The widget is available as the global BluvoWidget object
  const widget = BluvoWidget.initBluvoWidget({
    container: '#widget-container',
    auth: {
      projectId: 'your-project-id',
      orgId: 'your-org-id'
    },
    mode: 'connect',
    theme: {
      dark: true,
      accentColor: '#3B82F6'
    }
  });

  // To destroy the widget when needed
  // widget.destroy();
</script>

Embedding Example

Here's a complete example showing how to embed the widget in a webpage:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Bluvo Widget Example</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      margin: 0;
      padding: 20px;
      display: flex;
      justify-content: center;
      background: #f5f5f5;
    }
    
    .container {
      max-width: 800px;
      width: 100%;
    }
    
    .heading {
      text-align: center;
      margin-bottom: 20px;
    }
    
    #widget-container {
      display: flex;
      justify-content: center;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1 class="heading">Bluvo Widget Demo</h1>
    <div id="widget-container"></div>
  </div>

  <script type="module">
    import { initBluvoWidget } from 'https://unpkg.com/@bluvo/widget-vanjs/dist/bluvo-widget.es.js';
    
    // Initialize widget with your configuration
    const widget = initBluvoWidget({
      container: '#widget-container',
      auth: {
        projectId: 'your-project-id',
        orgId: 'your-org-id'
      },
      mode: 'connect',
      theme: {
        dark: true,
        accentColor: '#3B82F6'
      }
    });
  </script>
</body>
</html>

Configuration Options

The widget accepts various configuration options:

interface BluvoWidgetConfig {
  // Required
  container: string | HTMLElement;
  
  // Authentication
  auth?: {
    projectId: string;
    orgId: string;
  };
  projectId?: string; // Legacy option
  orgId?: string;     // Legacy option
  
  // Core settings
  mode?: 'connect' | 'transact';  // Default: 'connect'
  exchanges?: string[];           // Default: ['binance', 'coinbase', 'kraken']
  width?: string | number;        // Default: 360
  
  // Visual customization
  theme?: {
    dark?: boolean;               // Default: true
    accentColor?: string;         // Default: '#3B82F6'
    secondaryColor?: string;
    // ... other theme options
  };
  
  // Token storage options
  storage?: 'localStorage' | 'sessionStorage' | 'none';  // Default: 'localStorage'
  
  // Debug mode
  debug?: boolean;                // Default: false
  
  // Mode-specific configurations
  connect?: {
    showSearch?: boolean;
    showBranding?: boolean;
    showSuccessDetails?: boolean;
    exchangeList?: {
      logoSize?: number;
    };
    onSuccess?: (walletId: string) => void;
    onComplete?: (walletId: string) => void;
  };
  
  transaction?: {
    defaultCoin?: string;
    coins?: string[];
    showSuccessDetails?: boolean;
    display?: {
      address?: 'input' | 'label' | 'none';
      tag?: 'input' | 'label' | 'none';
      amount?: 'input' | 'label' | 'none';
    };
    prefill?: {
      address?: Record<string, string>;
      tag?: Record<string, string>;
      amount?: Record<string, number>;
    };
    onSuccess?: (tx: any) => void;
    onComplete?: (tx: any) => void;
  };
}

Styling

The widget includes all necessary styling. The base font is inherited from your application, but you can override styles if needed:

.bluvo-widget, .bluvo-widget * {
  font-family: your-custom-font, sans-serif;
}

Advanced Usage

You can also directly import the Widget component for more advanced use cases:

import { Widget } from '@bluvo/widget-vanjs';
import van from 'vanjs-core';

// Create a widget manually
const widgetElement = Widget({
  mode: 'connect',
  // ... other options
});

// Mount it yourself
van.add(document.getElementById('container'), widgetElement);

Architecture

The widget is built using VanJS, a minimalist reactive UI framework. The main components include:

Widget - Main container component
WidgetHeader - Header with title and navigation controls
WidgetFooter - Footer with branding and terms
ExchangeList - List of available exchanges
CredentialForm - Form for API key authentication
ConnectionProgress - Connection status progress
ConnectionSuccess - Successful connection view
ConnectionError - Error handling view
Transact - Transaction flow components

Development

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview

Continuous Integration and Deployment

This package uses GitHub Actions for continuous integration and deployment. The workflow is organized into two separate jobs:

1. publish-connect job

Builds and publishes the @bluvo/connect package (dependency)
Only publishes if the package doesn't already exist on npm
Runs first to ensure the dependency is available

2. publish-widget job

Depends on the publish-connect job completing successfully
Updates the widget's package.json to use the npm version of @bluvo/connect
Installs dependencies, builds, and publishes the widget
Automatically bumps the version (patch)
Only publishes if changes are detected in the package

The workflow triggers on:

Pushes to the main branch that include changes to either package
Manual workflow dispatch

Monorepo Dependency Handling

Since this package is part of a monorepo and depends on the internal @bluvo/connect package, the CI/CD workflow:

Checks if @bluvo/connect is already published to npm
If not, it builds and publishes it first in a separate job
Then updates the widget's package.json to use the npm version instead of the workspace reference (workspace:*)
This ensures proper dependency resolution when building outside the monorepo context

The workflow file is located at .github/workflows/publish-widget-vanjs.yml.

Requirements for deployment:

An NPM_TOKEN secret must be set in the GitHub repository settings
The package must have a valid package.json with a name, version, and required fields

License

MIT