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';
const widget = initBluvoWidget({
container: '#widget-container',
auth: {
projectId: 'your-project-id',
orgId: 'your-org-id'
},
mode: 'connect',
theme: {
dark: true,
accentColor: '#3B82F6'
}
});
UMD (Script Tag)
<script src="https://unpkg.com/@bluvo/widget-vanjs/dist/bluvo-widget.umd.js"></script>
<script>
const widget = BluvoWidget.initBluvoWidget({
container: '#widget-container',
auth: {
projectId: 'your-project-id',
orgId: 'your-org-id'
},
mode: 'connect',
theme: {
dark: true,
accentColor: '#3B82F6'
}
});
</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';
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 {
container: string | HTMLElement;
auth?: {
projectId: string;
orgId: string;
};
projectId?: string;
orgId?: string;
mode?: 'connect' | 'transact';
exchanges?: string[];
width?: string | number;
theme?: {
dark?: boolean;
accentColor?: string;
secondaryColor?: string;
};
storage?: 'localStorage' | 'sessionStorage' | 'none';
debug?: boolean;
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';
const widgetElement = Widget({
mode: 'connect',
});
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
pnpm install
pnpm dev
pnpm 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