@bluvo/widget-vanjs
Version:
Bluvo widget implemented with VanJS for embedding in vanilla JavaScript applications
309 lines (246 loc) • 7.55 kB
Markdown
# 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
### ES Modules
```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();
```
### UMD (Script Tag)
```html
<!-- 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:
```html
<!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:
```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<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:
```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:
### 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:
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`.
### 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