VeloraDEX Widget Documentation

Welcome to the VeloraDEX Widget documentation! This directory contains comprehensive guides for integrating and using the VeloraDEX trading widget in your React applications.

📚 Documentation Overview

Quick Start Guide

Get up and running in under 5 minutes with basic installation and setup instructions.

Perfect for: Developers who want to quickly integrate the widget with minimal configuration.

User Guide

Comprehensive documentation covering all features, configuration options, and integration patterns.

Perfect for: Developers who need detailed information about customization and advanced features.

API Reference

Complete API documentation with type definitions, component props, and configuration interfaces.

Perfect for: Developers who need detailed technical specifications.

Server-Side Rendering Guide

How to server-render the widget so the first paint shows the right tokens — the @velora-dex/widget/ssr entry, resolveWidgetInitState, the token-list cache, setup, and caveats. Opens with a decision tree for which pieces you actually need.

Perfect for: Developers integrating the widget into an SSR framework (Next.js, Astro, Remix, …).

Static Generation Guide

Shipping the widget on a statically generated site with no server at request time — prerendering pages whose URLs you can enumerate, serving one shell for URLs you can't, and when to prefer this over SSR.

Perfect for: Developers embedding the widget in a static site (Astro, Next.js export, Gatsby, plain SPA hosting).

🚀 What is the VeloraDEX Widget?

The VeloraDEX Widget is a comprehensive React component that provides a complete decentralized exchange (DEX) trading interface. It enables users to:

• Swap tokens across multiple blockchain networks
• Bridge assets between different chains
• Connect wallets with multiple provider support
• Execute trades with optimal routing and best prices
• Manage cross-chain transactions seamlessly

⚡ Quick Example

import { Widget } from "@velora-dex/widget";

function App() {
  return (
    <Widget
      config={{
        theme: "light",
        enableDelta: true,
        partner: "your-partner-id",
        widgetMode: "dapp",
      }}
      provider={window.ethereum}
    />
  );
}

🎯 Key Features

• 🔄 Multi-chain Support - Trade across Ethereum, Polygon, Arbitrum, and more
• 🎨 Customizable Themes - Light/dark mode with automatic system detection
• 🔐 Wallet Integration - Support for 100+ wallets via Privy
• ⚡ Optimal Routing - Best price execution through Velora's routing engine
• 📱 Responsive Design - Works perfectly on desktop and mobile
• 🛡️ Type Safety - Full TypeScript support with comprehensive type definitions
• 🔧 Easy Integration - Drop-in component for any React application

📖 Documentation Structure

For Beginners

1. Start with Quick Start Guide
2. Follow the basic examples
3. Customize with simple configuration options

For Advanced Users

1. Read the User Guide for comprehensive features
2. Check API Reference for detailed specifications
3. Server-rendering your app? See the SSR Guide; on a static site, the SSG Guide
4. Explore advanced integration patterns and customization

🛠️ Installation

# NPM
npm install @velora-dex/widget @tanstack/react-query wagmi viem

# Yarn
yarn add @velora-dex/widget @tanstack/react-query wagmi viem

# PNPM
pnpm add @velora-dex/widget @tanstack/react-query wagmi viem

Note: your bundle must end up with a single copy of @tanstack/react-query (^5.90.0), or the widget crashes on mount with No QueryClient set. Your bundle also needs a single copy of wagmi (^3.7.6) and viem (^2.55.19); a duplicate there does not throw, it just stops widgetMode: "dapp" adopting your wallet. See Peer Dependencies.

🔗 Useful Links

• GitHub Repository: VeloraDEX/widget
• NPM Package: @velora-dex/widget
• Website: velora.xyz

💬 Community & Support

• Discord: Join our community
• Twitter: @VeloraDEX
• GitHub Issues: Report bugs or request features
• Documentation: velora.xyz/docs

Ready to get started? Jump into the Quick Start Guide and have your widget running in minutes! 🚀