How to Reuse an Existing TON Connect Instance with Omniston Widget Integrated Mode

When integrating the Omniston Widget with an existing TON Connect instance, it is recommended to configure the widget in integrated mode and pass it the same initialized instance that the rest of your application already uses. This approach creates a shared wallet session across your interface, avoiding the creation of multiple TON Connect instances.

Imagine a TON dashboard with a wallet button in its header. If a visitor connects Tonkeeper or another compatible wallet, your application can use that connection to display the wallet address, account state, or transaction controls. Later, when adding token swaps through the Omniston Widget, it is more efficient to reuse the existing TON Connect connection rather than creating a new one.

This approach aligns with the STON.fi widget integration architecture, which advises against running multiple TON Connect instances within the same application.

To reuse an existing TON Connect instance with the Omniston Widget, follow these steps. First, ensure your application already uses the headless @tonconnect/sdk to own the wallet connectivity and transaction signing responsibilities. Next, install the Omniston widget loader package. You do not need a separate TON Connect installation specifically for the widget in this case.

Create the existing TON Connect connector once and export or provide access to that object wherever wallet functionality is needed. Then, install the Omniston widget loader, load the widget constructor, and pass the existing TON Connect instance to it. Finally, mount the widget into a real DOM element.

By following this pattern, you ensure that the TON Connect instance remains the single owner of wallet connectivity and transaction signing within your application. This approach simplifies wallet management and avoids potential conflicts or failures caused by multiple TON Connect instances.