Skip to main content
Get up and running with TAC development quickly by building your first hybrid dApp. This guide will take you from zero to a working application that connects TON wallets with EVM smart contracts in just a few minutes.

Install create-tac-app

The fastest way to bootstrap a TAC project is using our CLI tool:
npx create-tac-app my-tac-project
This creates a new directory with a fully configured TAC project including:
  • Smart contracts with proxy implementation
  • Frontend with TAC SDK integration
  • TON wallet connection setup
  • Cross-chain messaging examples

Configure your environment

Make sure you have the required tools and accounts:
  • Node.js v18.0.0 or higher
  • Blockchain Accounts:
    • TON wallet (like Tonkeeper or Wallet)
    • (Optional) EVM wallet (like Metamask) with TAC Testnet network added (Use button Add TAC SPB in upper right corner over here)

Get testnet tokens

(Optional) Deploy smart contracts

You can skip this step and use already deployed and pre-set contracts within my-tac-project or deploy fresh ones and yours truly.Create .env file out of .env.example.For the deployment navigate to the contracts directory and deploy to TAC Testnet:
cd my-tac-project/contracts
npm install
npx hardhat compile
npx hardhat run scripts/deploy.ts --network tacTestnet
Take note of the deployed addresses:
  • SimpleMessage contract address
  • MessageProxy contract address
  • MockToken contract address
These will be displayed in your console after successful deployment. Also saved to addresses.json file.

(Optional) Update frontend configuration

To use the specific addresses from the previous step open lib/contract_addresses.ts and update with your deployed contract addresses:
export const CONTRACT_ADDRESSES = {
  SIMPLE_MESSAGE: "0xYourSimpleMessageAddress",
  MESSAGE_PROXY: "0xYourMessageProxyAddress"
};
This connects your frontend to the smart contracts you just deployed.

Start the development server

Return to the project root and start the Next.js development server:
cd ..
npm install
npm run dev
Your TAC application is now running at http://localhost:3000.
You should see a clean interface with TON Connect integration and example messaging functionality.

Connect your TON wallet

Open your application in the browser and:
  1. Click the “Connect Wallet” button
  2. Choose your TON wallet (Wallet, Tonkeeper, etc.)
  3. Approve the connection in your wallet
  4. Verify your wallet address appeared in the interface
The starter app includes a messaging example that demonstrates cross-chain communication from TON to your EVM smart contracts.

Test cross-chain functionality (TON->TAC)

Try the example functionality:
  1. Send a Message: Click ‘Send Cross-Chain Message’ and approve it in you TON wallet to send a data from TON to your EVM contract
  2. Track Status: Watch the transaction progress through cross-chain stages
  3. View Results: See the message stored on the EVM side
This demonstrates the complete flow of hybrid dApp interaction the TON->TAC way. TON->TAC->TON and TAC->TON are also possible with different dApp architectures.

(Optional) Test cross-chain functionality (TON->TAC->TON)

Select different CONTRACT_ADDRESS.MESSAGE_PROXY in lib/contracts.ts, you’ll see the related comment.Or do it in a more advanced way:
  1. Navigate to contracts/MessageProxy.sol and uncomment the related code block.
  2. Deploy a set of contracts with npx hardhat run scripts/deploy.ts --network tacTestnet
  3. Update lib/contracts.ts with the new contract addresses.
Open the UI and repeat the previous step.

(Optional) Customize your dApp

Now you can start customizing dApp logic for your specific use case.Smart Contracts (contracts/ directory):
  • Modify SimpleMessage.sol for your business logic
  • Update MessageProxy.sol for custom cross-chain handling
  • Add new contracts as needed
Frontend (components/ directory):
  • Customize the UI components
  • Add new pages and functionality
Cross-Chain Features:Integrate additional TAC SDK features like:
  • Asset (FT, NFT) bridging between TON and EVM
  • Multi-step cross-chain workflows
  • Advanced transaction tracking

​
Next Steps

More Use Cases

Take a closer look into existing hybrid dApp implementations

Build TAC Proxy

Create custom proxy contracts for advanced cross-chain operations

TAC SDK Deep Dive

Master the TAC SDK for powerful frontend integrations

Development Tools

Set up Hardhat, Foundry, and other development tools

​
Common Issues & Solutions

Check your setup:
Troubleshooting steps:
  • Sometimes Tonconnect may not show you the send transaction popup. Try several times until success
  • Make sure you’re using a supported TON wallet in the pop-up TON Connect menu in the UI
  • Check that your wallet is set to TON testnet
  • Clear your browser cache and try again
  • Verify the my-tac-project TON Connect manifest is accessible
Common causes:
  • Insufficient TON balance for gas fees
  • Invalid contract addresses in configuration
  • Network connectivity issues
Solutions:
  • Check balances in both TON and TAC wallets
  • Verify contract addresses are correct
  • Use the transaction tracking to identify where failures occur