@wheelx-widget/widget 0.1.18 → 0.1.19

package/README.md

@@ -8,7 +8,7 @@ An open-source, framework-agnostic React widget for cross-chain token swaps and
 - 👛 **Built-in Wallet Connection** — Dynamic SDK + Wagmi v2 supporting EVM (MetaMask, OKX, etc.) and Solana (Phantom)
 - 🎨 **Configurable Theme** — 14 color tokens for custom skinning
 - ⚛️ **Framework Agnostic** — Works with any React framework (Next.js, Vite, Create React App, etc.)
-- 📦 **Tree-shakeable** — ESM + CJS builds with TypeScript declarations
+- 📦 **ESM + CJS** — Dual-format builds with full TypeScript declarations
 - 🔌 **Configurable Default Tokens** — Set default from/to chains and tokens
 - 📱 **Deep Link Support** — Wallet app launch support in WebView (React Native) — see [Deep Link Guide](./DEEP_LINK_GUIDE.md)
 
@@ -22,6 +22,19 @@ Note: `@chakra-ui/react` and `@emotion/react` are required peer dependencies.
 
 ## Quick Start
 
+If you don't have a project yet, scaffold one first:
+
+```bash
+npm create vite@latest my-swap-page -- --template react-ts
+cd my-swap-page
+```
+
+Then install the widget and required peer dependencies:
+
+```bash
+npm install @wheelx-widget/widget @chakra-ui/react @emotion/react
+```
+
 ```tsx
 // main.tsx — wrap with ChakraProvider
 import { ChakraProvider, defaultSystem } from '@chakra-ui/react'
@@ -38,7 +51,7 @@ createRoot(document.getElementById('root')!).render(
 ```tsx
 // App.tsx
 // Import the CSS for animations (required!)
-import '@wheelx-widget/widget/dist/index.css'
+import '@wheelx-widget/widget/styles.css'
 import { WheelXProvider, WheelXWidget } from '@wheelx-widget/widget'
 
 function App() {
@@ -106,18 +119,6 @@ Customize 14 visual tokens:
 </WheelXProvider>
 ```
 
-### API Base URL
-
-Override the default WheelX API endpoint. Useful for testing against a staging or development environment.
-
-```tsx
-<WheelXProvider config={{
-  apiBaseUrl: 'https://dev-api.wheelx.fi'  // Default: 'https://api.wheelx.fi'
-}}>
-  <WheelXWidget />
-</WheelXProvider>
-```
-
 ### Fixed Recipient Address (Different Address)
 
 Configure fixed recipient addresses for EVM or Solana chains. When set, the widget will:
@@ -170,9 +171,6 @@ The main trading widget component.
 interface WidgetConfig {
   theme?: Partial<WidgetTheme>
 
-  /** API base URL. Default 'https://api.wheelx.fi' */
-  apiBaseUrl?: string
-
   from?: {
     chains?: number[]
     defaultChainId?: number
@@ -242,6 +240,16 @@ In short, three things are required:
 2. Configure `<queries>` declaration in Android's `AndroidManifest.xml`
 3. Configure `LSApplicationQueriesSchemes` in iOS's `Info.plist`
 
+## Troubleshooting
+
+| Problem | Symptom | Solution |
+|----------|---------|----------|
+| **Missing ChakraProvider** | White screen or unstyled component | Wrap your app in `<ChakraProvider value={defaultSystem}>` — the widget depends on Chakra's context |
+| **Forgot to import CSS** | Component works but has no styling/animations | Add `import '@wheelx-widget/widget/styles.css'` in your entry file |
+| **Vite dev server starts slow** | `vite dev` takes 30+ seconds | Normal — Vite pre-bundles large wallet dependencies (wagmi, viem, ethers, etc.). Subsequent starts with cache are faster |
+| **Build output is large** | dist/ folder tens of MB, main bundle ~7.5MB (1.9MB gzipped) | Expected — the widget bundles all wallet SDKs. Use code-splitting or lazy-loading in your host app if needed |
+| **React hooks errors** | "Invalid hook call" or context mismatch | You may have duplicate React instances. Ensure `react` and `react-dom` are peer dependencies in your project, and use a single version (18 or 19) |
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -36,8 +36,6 @@ interface WidgetTheme {
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
-    /** API base URL. Default 'https://api.wheelx.fi' */
-    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;

package/dist/index.d.ts

@@ -36,8 +36,6 @@ interface WidgetTheme {
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
-    /** API base URL. Default 'https://api.wheelx.fi' */
-    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;

package/dist/index.js

@@ -43737,12 +43737,9 @@ var WidgetThemeProvider = ({
 };
 
 // src/api/consts.ts
-var _baseApiUrl = "https://api.wheelx.fi";
+var BASE_API_URL = "https://api.wheelx.fi";
 function getBaseApiUrl() {
-  return _baseApiUrl;
-}
-function setBaseApiUrl(url) {
-  _baseApiUrl = url;
+  return BASE_API_URL;
 }
 async function getChainsAndTokens() {
   const url = `${getBaseApiUrl()}/v1/chain-info`;
@@ -44787,9 +44784,6 @@ function ChainsAndTokensLoader({ children, config }) {
 var DEFAULT_ENVIRONMENT_ID = "f217660e-2cec-470b-a8f4-ac655b16f802";
 var solanaRpcUrl = "https://mainnet.helius-rpc.com/?api-key=7337bed2-6c3a-472f-b06f-9b2be0e1392f";
 var WheelXProvider = ({ config, children }) => {
-  if (config?.apiBaseUrl) {
-    setBaseApiUrl(config.apiBaseUrl);
-  }
   const queryClient = React5.useMemo(() => new reactQuery.QueryClient(), []);
   const evmNetworks = React5.useMemo(() => supportedChains.map((chain) => ({
     chainId: chain.id,