Migrating to @layerswap/widget-react

​

1. Swap the packages

npm uninstall @layerswap/widget @layerswap/wallets zustand
# plus any @layerswap/wallet-* packages you installed
npm install @layerswap/widget-react

​

2. Replace the provider tree with one component

// Before
import { LayerswapProvider, Swap } from '@layerswap/widget';
import '@layerswap/widget/index.css';
import { createEVMProvider } from '@layerswap/wallet-evm';
import { createSVMProvider } from '@layerswap/wallet-svm';

<LayerswapProvider
  config={{ apiKey: 'YOUR_API_KEY', version: 'mainnet' }}
  walletProviders={[createEVMProvider(), createSVMProvider()]}
  callbacks={callbacks}
>
  <Swap />
</LayerswapProvider>

// After
import { LayerswapWidget } from '@layerswap/widget-react';

<LayerswapWidget
  config={{ apiKey: 'YOUR_API_KEY', version: 'mainnet' }}
  walletProvidersConfig={{ include: ['evm', 'solana'] }}
  callbacks={callbacks}
  fallback={<div>Loading widget…</div>}
/>

• config — apiKey, version, theme, initialValues keep working as-is.
• callbacks — the same eight callback names and payloads remain available, including onSwapStatusChange and onMenuNavigationChange.

• The CSS import (@layerswap/widget/index.css) — styles inject at runtime.
• The walletProviders array and all create*Provider() factories.

​

3. Map your wallet provider setup

​

4. Delete your bundler workarounds

• transpilePackages entries for @layerswap/* in next.config.ts
• webpack resolve.fallback / externals tweaks for fs, net, tls, pino-pretty, etc.
• vite-plugin-node-polyfills, stream-browserify, Buffer/process globals
• ssr.noExternal / optimizeDeps.include lists for @layerswap/*
• next/dynamic wrappers with ssr: false — the component is SSR-safe by itself

​

5. Migrate the Deposit Widget

// Before
import { Deposit } from '@layerswap/widget/deposit';
import '@layerswap/widget/index.css';

<Deposit
  config={{ apiKey: 'YOUR_API_KEY', version: 'mainnet' }}
  walletProviders={[createEVMProvider()]}
  destination={{ network: 'BASE_MAINNET', tokens: ['USDC'] }}
  destinationAddress="0x…"
/>

// After
import { LayerswapDepositWidget } from '@layerswap/widget-react';

<LayerswapDepositWidget
  config={{ apiKey: 'YOUR_API_KEY', version: 'mainnet' }}
  destination={{ network: 'BASE_MAINNET', tokens: ['USDC'] }}
  destinationAddress="0x…"
/>

​

6. Review the behavioral differences

• Widget updates roll forward automatically on the CDN channel—you no longer pin the remote implementation through npm. Verify the final 2.x release-channel policy on release day. See Widget delivery and security.
• One widget per page (of either kind) — the widget keeps process-global state.
• Object props are compared by reference—hoist config, callbacks, walletDefaults, and walletProvidersConfig to module scope or memoize them to avoid provider rebuilds and extra renders.
• Loader-level props are new: fallback (loading state), onReady, and onError for load failures — distinct from callbacks.onError.
• If you serve a CSP, allowlist the widget CDN origin — see the recommended CSP.