Truffle: Ethereum Development Framework

Common errors

• Error: Cannot find module '@truffle/contract'

  cause Attempting to import `@truffle/contract` without it being installed as a dependency, or using an outdated `require('truffle-contract')` pattern.
  fix Install the `@truffle/contract` package: `npm install @truffle/contract`. Ensure `truffle` is at a compatible version for your contract abstractions.

• Error: `truffle test` fails with 'Cannot compile contracts with solc version X'

  cause The Solidity compiler version specified in `truffle-config.js` (or implied) is incompatible with the contracts or the `truffle` version itself.
  fix Update the `compilers.solc.version` in `truffle-config.js` to a compatible version (e.g., `"^0.8.0"` or `"0.8.21"`). Ensure your local `solc` version matches.

• Error: `truffle migrate` fails with 'No network defined in configuration'

  cause The `truffle-config.js` file is missing a `networks` configuration, or the specified network name for `truffle migrate --network <name>` does not exist in the configuration.
  fix Ensure `truffle-config.js` has a `networks` object with at least a `development` network or the specific network you intend to use. Example: `networks: { development: { host: "127.0.0.1", port: 8545, network_id: "*" } }`.

Warnings

• breaking Truffle has dropped official support for Node.js 14 as of v5.11.3. Users must upgrade their Node.js environment to maintain compatibility and receive updates. Supported versions are now Node 16.20, 18.16, or >=20.
  Fix: Upgrade Node.js to version 16.20, 18.16, or 20 using a tool like `nvm` (`nvm install 20 && nvm use 20`).
• gotcha When installing Truffle globally via `npm install -g truffle`, users on Windows Command Prompt might encounter conflicts if `truffle.js` (an older config file name) is present in the working directory, as `truffle.js` can take precedence over `truffle.cmd`. This can lead to unexpected command execution.
  Fix: Rename `truffle.js` to `truffle-config.js` (recommended and default for newer projects), or explicitly call `truffle.cmd compile`, or use PowerShell/Git BASH.
• gotcha The primary interaction with the `truffle` package is via its Command Line Interface (CLI). While internal components exist, the `truffle` package itself is not designed for direct modular JavaScript/TypeScript imports of its core functionalities for programmatic execution. For programmatic interaction with Truffle's features (e.g., contract abstraction, debugging, configuration), users should typically install and import specific `@truffle/` scoped packages (e.g., `@truffle/contract`, `@truffle/debugger`).
  Fix: For CLI usage, install globally (`npm install -g truffle`) and run `truffle <command>`. For programmatic API access, identify and install the relevant `@truffle/` sub-package (e.g., `npm install @truffle/contract`).
• gotcha Truffle's debugging features, especially for external transactions (`truffle debug --fetch-external`) and the Truffle Dashboard debugger, can sometimes be experimental or require specific setup steps, including fetching external sources or ensuring compilations are available in the Dashboard.
  Fix: Refer to the official Truffle documentation for the latest instructions on debugging specific contract types or network configurations, and ensure all preparation steps for Truffle Dashboard are followed.
• deprecated Some underlying Truffle utility packages, such as `@truffle/config`, have been marked as deprecated. While the main `truffle` CLI continues to function, direct programmatic reliance on these specific deprecated sub-packages should be reviewed.
  Fix: Review the Truffle Suite documentation and changelogs for recommended alternatives or updated integration patterns when interacting with core functionalities programmatically. Consider alternative libraries or newer versions of Truffle's internal components if exposed.

Install

• npm install truffle npm
• yarn add truffle yarn
• pnpm add truffle pnpm

Imports

• truffle
  wrong:

  const truffle = require('truffle');

  correct:

  import * as truffle from 'truffle';

  The `truffle` package is primarily a CLI tool. Direct programmatic imports of the top-level package for its core CLI functionality are uncommon. When imported, it exposes its bundled CLI entry point, not a modular API. Programmatic interaction with specific Truffle functionalities (e.g., contract abstraction, debugging, configuration) typically involves installing and importing dedicated `@truffle/` scoped packages like `@truffle/contract` or `@truffle/config` (though `@truffle/config` is deprecated as a direct import).
• Config
  wrong:

  import { Config } from 'truffle';

  correct:

  import Config from '@truffle/config';

  To access Truffle's configuration utility programmatically, developers typically import the `@truffle/config` package directly, rather than trying to access a 'Config' symbol from the main 'truffle' package. Note that `@truffle/config` itself has been deprecated.
• console

  import "truffle/console.sol";

  This is a special import used *within Solidity contracts* (not JavaScript/TypeScript files) to enable `console.log` like debugging functionality during contract execution. It's a key part of the Truffle debugging experience for smart contracts.

Quickstart

Demonstrates the initial setup of a Truffle project, compiling and deploying smart contracts, and running tests. This uses the globally installed Truffle CLI.

npm install -g truffle

mkdir my-truffle-project
cd my-truffle-project

truffle init

# Open truffle-config.js and ensure Node 20 is supported (if not already)
// module.exports = {
//   networks: {
//     development: {
//       host: "127.0.0.1",
//       port: 8545,
//       network_id: "*"
//     }
//   },
//   compilers: {
//     solc: {
//       version: "^0.8.0" // or specify a newer version like "0.8.21"
//     }
//   }
// };

truffle compile
truffle migrate
truffle test