Get started with the TAC SDK by installing the package and configuring your development environment. The SDK works in both browser and Node.js environments with full TypeScript support.
Installation
Install the TAC SDK using your preferred package manager:
npm install @tonappchain/sdk
Basic Import and Setup
Import the core SDK components you’ll need for your application:
import {
TacSdk ,
SenderFactory ,
OperationTracker ,
Network ,
AssetType ,
} from "@tonappchain/sdk" ;
Environment Configuration
Network Selection
The SDK supports both testnet and mainnet environments. Always start development on testnet:
// For development and testing
const tacSdk = await TacSdk . create ({
network: Network . TESTNET ,
});
// For production
const tacSdk = await TacSdk . create ({
network: Network . MAINNET ,
});
Always test your integration thoroughly on testnet before deploying to
mainnet. Cross-chain operations are irreversible once confirmed.
Environment Variables
For security, store sensitive configuration in environment variables:
# .env file
TVM_MNEMONICS = your_wallet_mnemonic_here
TAC_NETWORK = testnet
TON_CONNECT_MANIFEST_URL = https://yourapp.com/tonconnect-manifest.json
Access these in your application:
const network =
process . env . TAC_NETWORK === "mainnet" ? Network . MAINNET : Network . TESTNET ;
const tacSdk = await TacSdk . create ({ network });
Framework Integration
React Integration
For React applications, wrap the SDK in a context provider:
// contexts/TacSdkContext.js
import React , { createContext , useContext , useEffect , useState } from "react" ;
import { TacSdk , Network } from "@tonappchain/sdk" ;
const TacSdkContext = createContext ( null );
export const TacSdkProvider = ({ children }) => {
const [ tacSdk , setTacSdk ] = useState ( null );
const [ loading , setLoading ] = useState ( true );
useEffect (() => {
const initializeSdk = async () => {
try {
const sdk = await TacSdk . create ({
network: Network . TESTNET ,
delay: 1 ,
});
setTacSdk ( sdk );
} catch ( error ) {
console . error ( "Failed to initialize TAC SDK:" , error );
} finally {
setLoading ( false );
}
};
initializeSdk ();
return () => {
if ( tacSdk ) {
tacSdk . closeConnections ();
}
};
}, []);
return (
< TacSdkContext.Provider value = { { tacSdk , loading } } >
{ children }
</ TacSdkContext.Provider >
);
};
export const useTacSdk = () => {
const context = useContext ( TacSdkContext );
if ( ! context ) {
throw new Error ( "useTacSdk must be used within a TacSdkProvider" );
}
return context ;
};
Use the context in your components:
// components/CrossChainTransaction.js
import { useTacSdk } from "../contexts/TacSdkContext" ;
export const CrossChainTransaction = () => {
const { tacSdk , loading } = useTacSdk ();
if ( loading ) return < div > Initializing TAC SDK... </ div > ;
const handleTransaction = async () => {
// Use tacSdk for cross-chain operations
const result = await tacSdk . sendCrossChainTransaction ( /* ... */ );
};
return (
< button onClick = { handleTransaction } > Send Cross-Chain Transaction </ button >
);
};
Next.js Integration
For Next.js applications, handle client-side initialization:
// hooks/useTacSdk.js
import { useEffect , useState } from "react" ;
import { TacSdk , Network } from "@tonappchain/sdk" ;
export const useTacSdk = () => {
const [ tacSdk , setTacSdk ] = useState ( null );
const [ loading , setLoading ] = useState ( true );
useEffect (() => {
// Only initialize on client side
if ( typeof window !== "undefined" ) {
const initializeSdk = async () => {
try {
const sdk = await TacSdk . create ({
network: Network . TESTNET ,
});
setTacSdk ( sdk );
} catch ( error ) {
console . error ( "SDK initialization failed:" , error );
} finally {
setLoading ( false );
}
};
initializeSdk ();
}
}, []);
return { tacSdk , loading };
};
Vue.js Integration
For Vue applications, create a composable:
// composables/useTacSdk.js
import { ref , onMounted , onUnmounted } from "vue" ;
import { TacSdk , Network } from "@tonappchain/sdk" ;
export function useTacSdk () {
const tacSdk = ref ( null );
const loading = ref ( true );
onMounted ( async () => {
try {
tacSdk . value = await TacSdk . create ({
network: Network . TESTNET ,
});
} catch ( error ) {
console . error ( "TAC SDK initialization failed:" , error );
} finally {
loading . value = false ;
}
});
onUnmounted (() => {
if ( tacSdk . value ) {
tacSdk . value . closeConnections ();
}
});
return { tacSdk , loading };
}
TON Connect Integration
For browser applications, integrate with TON Connect for wallet connectivity:
Install TON Connect
npm install @tonconnect/ui
import { TonConnectUI } from "@tonconnect/ui" ;
// Initialize TON Connect
const tonConnectUI = new TonConnectUI ({
manifestUrl: "https://yourapp.com/tonconnect-manifest.json" ,
buttonRootId: "ton-connect-button" ,
});
// Create sender from TON Connect
import { SenderFactory } from "@tonappchain/sdk" ;
const sender = await SenderFactory . getSender ({
tonConnect: tonConnectUI ,
});
TON Connect Manifest
Create a manifest file for your application:
{
"url" : "https://yourapp.com" ,
"name" : "Your dApp Name" ,
"iconUrl" : "https://yourapp.com/icon.png" ,
"termsOfUseUrl" : "https://yourapp.com/terms" ,
"privacyPolicyUrl" : "https://yourapp.com/privacy"
}
TypeScript Configuration
If using TypeScript, ensure your tsconfig.json
includes proper module resolution:
{
"compilerOptions" : {
"target" : "ES2020" ,
"module" : "ESNext" ,
"moduleResolution" : "node" ,
"esModuleInterop" : true ,
"allowSyntheticDefaultImports" : true ,
"strict" : true ,
"skipLibCheck" : true ,
"forceConsistentCasingInFileNames" : true
}
}
SDK Configuration Options
The SDK accepts several configuration options during initialization:
const tacSdk = await TacSdk . create ({
network: Network . TESTNET , // Network selection
delay: 1000 , // Delay between operations (milliseconds)
TONParams: {
// TON-specific configuration
contractOpener: tonClient , // Custom TonClient instance
settingsAddress: "custom-address" , // Custom settings contract address
},
TACParams: {
// TAC-specific configuration
provider: customProvider , // Custom provider
settingsAddress: "custom-address" , // Custom settings contract address
},
});
Configuration Options Reference
Network Options:
Network.TESTNET
- For development and testing
Network.MAINNET
- For production applications
Timing Options:
delay
- Delay between operations in milliseconds (default: 1000)
TON Parameters:
contractOpener
- Custom TonClient instance for TON operations
settingsAddress
- Custom settings contract address
TAC Parameters:
provider
- Custom provider for TAC operations
settingsAddress
- Custom settings contract address
Verification
Test your installation with a simple initialization:
import { TacSdk , Network } from "@tonappchain/sdk" ;
async function testInstallation () {
try {
const tacSdk = await TacSdk . create ({
network: Network . TESTNET ,
});
console . log ( "✅ TAC SDK initialized successfully" );
console . log ( "Network:" , tacSdk . network );
// Clean up
tacSdk . closeConnections ();
} catch ( error ) {
console . error ( "❌ Installation test failed:" , error );
}
}
testInstallation ();
Common Issues and Solutions
If you encounter module resolution errors, ensure you’re using a modern bundler that supports ES modules:
Webpack 5:
// webpack.config.js
module . exports = {
resolve: {
fallback: {
crypto: require . resolve ( "crypto-browserify" ),
stream: require . resolve ( "stream-browserify" ),
buffer: require . resolve ( "buffer" ),
},
},
};
Vite:
// vite.config.js
export default {
define: {
global: "globalThis" ,
} ,
resolve: {
alias: {
crypto: "crypto-browserify" ,
stream: "stream-browserify" ,
buffer: "buffer" ,
},
} ,
} ;
Network Connection Issues
If you experience network connection issues:
Check your network configuration:
const tacSdk = await TacSdk . create ({
network: Network . TESTNET ,
tonParams: {
endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC" ,
},
});
Verify firewall settings - Ensure your environment can access TON and TAC endpoints
Use environment-specific configuration - Different environments may require different endpoints
For TypeScript type errors:
Install type definitions:
npm install --save-dev @types/node
Update your tsconfig.json:
{
"compilerOptions" : {
"moduleResolution" : "node" ,
"allowSyntheticDefaultImports" : true ,
"esModuleInterop" : true
}
}
Use explicit imports:
import type { TacSdk , Network } from "@tonappchain/sdk" ;
Next Steps
With the SDK installed and configured, you’re ready to start building hybrid dApps:
Start with the Quick Start guide to send your first
cross-chain transaction and see the SDK in action.