Installation
Before initializing the TON Connect’s AppKit, install it with the necessary peer dependencies:Buffer polyfill. Extend the module bundle configuration according to the bundler in use:
Initialization
Jump to a complete and exhaustive setup.
Connectors
The basic setup allows for direct API requests but is insufficient for connecting TON wallets via the TON Connect protocol. For that, configure a connector and host a public app manifest file adjusted to the needs of a given dApp. For local development and testing, use the manifest file from this demo dApp.Providers
The setup with connectors connects to TON wallets via services such as Tonkeeper. To enable advanced DeFi operations like asset swaps, configure DeFi providers. Omniston is the primary swap provider. To set it up:Queries and mutations
TanStack Query is an opinionated library that simplifies fetching, caching, synchronizing and updating server state in web applications. To enable it for React, wrap the application insideAppKitProvider in the QueryClientProvider from @tanstack/react-query:
Complete setup
The following initialization example sets up everything at once:Dynamic configuration
AppKit instance can be dynamically extended with new connectors and providers.Add new connectors
To add a new connector, call the.addConnector() method on the initialized AppKit object:
Add new providers
To add a new provider, call the.registerProvider() method on the initialized AppKit object:
kit.swapManager:
Configuration parameters
For one or more TON networks, configure their respective API or RPC providers to interact with.It is also possible to provide an entirely custom provider with its own
TypeScript
ApiClient interface implementation.TypeScript
Array of connectors that enable wallet connections. The primary connector is
TonConnectConnector.Each connector must expose the following methods:initialize()— creates the connector, restores connections, sets up event listeners.destroy()— cleans up connector resources.connectWallet()— connects a wallet through the UI.disconnectWallet()— disconnects a wallet.getConnectedWallets()— lists connected wallets.
Array of DeFi providers that enable additional functionality, such as asset swaps via Omniston.
Relation to TON Connect libraries
Lower-level TON Connect libraries, such as@tonconnect/ui-react and @tonconnect/ui, only give access to wallet services via the TON Connect protocol and basic facilities to query connected TON wallets with direct API calls.
AppKit builds on the foundation provided by these libraries and extends functionality with convenient components, hooks, and functions. It enables balance tracking and asset management, gives ready-made React UI components for common cases, handles API-related state management, and even registers DeFi integrations for advanced use cases.
If there is an existing dApp that uses either @tonconnect/ui-react or @tonconnect/ui, consider migrating to AppKit to simplify development and reduce boilerplate.
Migrate from @tonconnect/ui-react
Before migrating, install AppKit and peer packages and add necessary polyfills.
Ensure the TON Connect UI package is of the latest version
Ensure that TON Connect packages are of the latest version:
Initialize AppKit and replace TonConnectUIProvider
Use Refer to the complete initialization setup for all the possible AppKit configuration options.
AppKitProvider in place of the TonConnectUIProvider:Migrate from @tonconnect/ui
Before migrating, install AppKit and peer packages and add necessary polyfills.
Initialize AppKit and reuse TonConnectUI object
It is possible to reuse the existing One can also extend the existing AppKit instance dynamically:Refer to the complete initialization setup for all the possible AppKit configuration options.
TonConnectUI object when configuring AppKit connectors:Replace method calls with exported functions
Instead of consolidating everything within the instantiated
TonConnectUI object, AppKit offers several tree-shakable functions that enhance and expand the capabilities of the existing TonConnectUI functionality. Refer to relevant how-to pages for concrete examples.