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

``bash
npm install @bluvo/widget-vanjs
`

Or with yarn:

`bash
yarn add @bluvo/widget-vanjs
`

Or with pnpm:

`bash
pnpm add @bluvo/widget-vanjs
`

Basic Usage

$3

`javascript
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();
`

$3

`html




`

$3

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

`html














`

Configuration Options

The widget accepts various configuration options:

`typescript
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;
tag?: Record;
amount?: Record;
};
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:

`css
.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:

`javascript
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

`bash


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:

$3

- 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

$3

- 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

$3

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

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

$3

- 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