TronBox

4.6.0 · active · verified Tue Apr 21

TronBox is an open-source development framework and testing environment designed for smart contracts built on the TRON Virtual Machine (TVM). Currently stable at version 4.6.0, it follows a periodic release cadence, incorporating updates for Solidity compiler support, underlying dependency upgrades like `tronweb` and `ethers`, and framework enhancements. As a direct fork of the popular Ethereum development suite Truffle, TronBox provides a familiar and robust toolkit for TRON developers, offering features such as built-in contract compilation, linking, deployment, binary management, an external script runner, an interactive console, automated contract testing, and a scriptable migration framework. Its key differentiator is its specialized focus on the TRON ecosystem, adapting Truffle's established workflows and tools to the specifics of TRON blockchain development, including seamless integration with `tronweb` and support for TRON-specific network configurations.

Common errors

```
'tronbox' is not recognized as an internal or external command, operable program or batch file.
```
cause TronBox CLI is not globally installed or not in the system's PATH.

fix Ensure TronBox is installed globally using `npm install -g tronbox`. If already installed, verify your system's PATH environment variable.
```
Error: Node.js vXX.YY.Z is not supported. TronBox requires Node.js >=20.0.0.
```
cause The installed Node.js version is older than the minimum required by TronBox.

fix Upgrade your Node.js installation to version 20.0.0 or higher. Using a version manager like `nvm` (Node Version Manager) is recommended: `nvm install 20 && nvm use 20`.
```
Error: Network 'development' not found in tronbox-config.js.
```
cause The specified network for compilation or migration is not defined in the `tronbox-config.js` file.

fix Open `tronbox-config.js` and add or correct the network configuration, ensuring the network name matches the one provided in the CLI command (e.g., `tronbox migrate --network myNetwork`).

Warnings

breaking EPM (Ethereum Package Manager) support has been entirely removed from TronBox. Projects relying on EPM for package management will need to migrate to alternative dependency management solutions.
Fix: Migrate any EPM-managed dependencies to npm or direct contract imports. Review your `tronbox-config.js` and migration scripts for EPM references.
breaking Configuration directory paths, including `build_directory`, `contracts_directory`, `contracts_build_directory`, `migrations_directory`, and `test_directory`, have been reconfigured. Existing projects may require updates to their `tronbox-config.js`.
Fix: Review the latest TronBox documentation for the correct default and configurable directory paths. Update your `tronbox-config.js` to reflect any necessary changes to avoid file lookup errors during compilation or deployment.
breaking TronBox has migrated from `web3` v4 to `ethers` v6 for all EVM-mode operations. This affects migration scripts, test scripts, and the TronBox console, requiring code adjustments for existing projects.
Fix: Refactor any code interacting with contract instances or blockchain APIs to use the `ethers.js` v6 API. Consult the `ethers.js` documentation for updated methods and patterns.
breaking The `build`, `serve`, and `watch` CLI commands have been removed. These functionalities are no longer available directly via the TronBox CLI.
Fix: For building, use `tronbox compile`. For serving or watching files, integrate external tools (e.g., `webpack`, `nodemon`) into your development workflow. The `tronbox help` command provides updated command usage.

Install

npm install tronbox npm
yarn add tronbox yarn
pnpm add tronbox pnpm

Imports

tronbox CLI
wrong:
```
import { tronbox } from 'tronbox'
```
correct:
```
npm install -g tronbox
tronbox <command>
```
TronBox is primarily a command-line interface (CLI) tool installed globally. It is not designed for programmatic `import` or `require` into other JavaScript/TypeScript applications. Interaction occurs via shell commands.
tronbox init
wrong:
```
const project = new TronBoxProject()
```
correct:
```
tronbox init
```
This command initializes a new TronBox project, creating boilerplate directories (contracts/, migrations/, test/) and the `tronbox-config.js` file. It's a CLI-driven setup.
tronbox console
wrong:
```
import { console } from 'tronbox'
```
correct:
```
tronbox console
```
Provides an interactive JavaScript runtime environment where compiled contracts are automatically made available for direct interaction. This is an environment provided by the CLI, not a library module.

Quickstart

This quickstart demonstrates the full lifecycle of a TronBox project: global installation, project initialization, creating a simple Solidity contract and its deployment migration, compilation, deployment to a development network, and interaction via the console.

npm install -g tronbox

mkdir my-tron-project
cd my-tron-project

tronbox init

# Example contract in contracts/MyContract.sol (create this file)
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

contract MyContract {
    string public greeting;

    constructor() {
        greeting = "Hello, TronBox!";
    }

    function setGreeting(string memory _greeting) public {
        greeting = _greeting;
    }
}

# Example migration in migrations/1_deploy_my_contract.js (create this file)
const MyContract = artifacts.require("MyContract");

module.exports = function (deployer) {
  deployer.deploy(MyContract);
};

tronbox compile
tronbox migrate --network development # Assuming 'development' network is configured in tronbox-config.js
tronbox test # Ensure test files exist in test/ directory

tronbox console

view raw JSON →