npm package: @silentswap/widget
Description: Embeddable cross-chain swap widget powered by the SilentSwap SDK. Works in any web app — React, Vue, Svelte, plain HTML.
Latest version: 0.1.2

# @silentswap/widget

Embeddable cross-chain swap widget powered by the SilentSwap SDK. Works in any web app — React, Vue, Svelte, plain HTML.

## Install

```bash
bun add @silentswap/widget
# or
npm install @silentswap/widget
```

## Usage

### React — Inline

```tsx
import { SilentSwapWidget } from '@silentswap/widget';
import '@silentswap/widget/style.css';

function App() {
  return (
    <SilentSwapWidget
      config={{
        walletConnectProjectId: 'YOUR_PROJECT_ID',
        environment: 'MAINNET',
      }}
      theme={{
        primaryColor: '#F0B90B',
        borderRadius: 12,
      }}
    />
  );
}
```

### React — Modal

```tsx
import { SilentSwapModal } from '@silentswap/widget';
import '@silentswap/widget/style.css';

function App() {
  return (
    <SilentSwapModal config={{ walletConnectProjectId: 'YOUR_PROJECT_ID' }} trigger={<button>Open Swap</button>} />
  );
}
```

### Vanilla JS (ESM)

```html
<link rel="stylesheet" href="silentswap-widget.css" />
<div id="swap"></div>

<script type="module">
  import { mount } from '@silentswap/widget';

  mount('#swap', {
    config: { walletConnectProjectId: 'YOUR_PROJECT_ID' },
  });
</script>
```

### Vanilla JS — Modal

```html
<script type="module">
  import { open } from '@silentswap/widget';

  const modal = open({
    config: { walletConnectProjectId: 'YOUR_PROJECT_ID' },
  });

  // modal.close() to dismiss
</script>
```

## Config

| Property                  | Type                     | Default                        | Description                                           |
| ------------------------- | ------------------------ | ------------------------------ | ----------------------------------------------------- |
| `walletConnectProjectId`  | `string`                 | **required**                   | Reown / WalletConnect project ID                      |
| `environment`             | `'STAGING' \| 'MAINNET'` | `'STAGING'`                    | SDK environment                                       |
| `integratorId`            | `string`                 | —                              | Integrator identifier for attribution                 |
| `solanaRpcUrl`            | `string`                 | SDK default                    | Custom Solana RPC endpoint                            |
| `bitcoinRpcUrl`           | `string`                 | SDK default                    | Custom Bitcoin RPC endpoint                           |
| `evmRpcOverrides`         | `Record<number, string>` | —                              | Custom EVM RPC overrides per chain ID                 |
| `assetBaseUrl`            | `string`                 | `'https://app.silentswap.com'` | Base URL for asset images                             |
| `defaultSourceAsset`      | `string`                 | —                              | Default source asset (CAIP-19)                        |
| `defaultDestinationAsset` | `string`                 | —                              | Default destination asset (CAIP-19)                   |
| `defaultRecipientAddress` | `string`                 | —                              | Pre-fill recipient address                            |
| `defaultInputAmount`      | `string`                 | —                              | Pre-fill input amount                                 |
| `privacyEnabled`          | `boolean`                | `true`                         | Enable hidden/privacy swap mode                       |
| `maxTransactionUsd`       | `number`                 | `30000`                        | Max transaction amount in USD                         |
| `appMetadata`             | `object`                 | —                              | Reown AppKit metadata (name, description, url, icons) |

## Theme

| Property          | Type     | Default     |
| ----------------- | -------- | ----------- |
| `primaryColor`    | `string` | `'#F0B90B'` |
| `backgroundColor` | `string` | `'#111111'` |
| `containerColor`  | `string` | `'#171717'` |
| `textColor`       | `string` | `'#FFFFFF'` |
| `borderColor`     | `string` | `'#333333'` |
| `borderRadius`    | `number` | `8`         |
| `fontFamily`      | `string` | —           |
| `mode`            | `'dark'` | `'dark'`    |

## Development

```bash
cd widget

# Install deps
bun install

# Build
bun run build

# Local test server (serves test/test-esm.html)
bun run test:serve
# then open http://localhost:5174/test/test-esm.html
```

## Architecture

The widget reuses the dapp source (`../src/`) directly via Vite aliases — no copied files. Only 15 widget-specific files exist:

- `components/` — SilentSwapWidget, SilentSwapModal, WidgetShell
- `providers/` — WidgetProvider (provider chain), WidgetConfigContext
- `shims/` — Next.js module replacements (next/image, next/dynamic, next/navigation, next/link, noop)
- `styles/` — Scoped globals + Tailwind theme
- `index.ts` — React entry, `vanilla.ts` — mount/open API, `types.ts` — config/theme types