{"id":14982,"library":"truffle","title":"Truffle: Ethereum Development Framework","description":"Truffle is a comprehensive development environment, testing framework, and asset pipeline designed to simplify smart contract development on Ethereum and other EVM-compatible blockchains. Currently at version 5.11.5, it receives frequent minor updates and internal improvements, often on a weekly or bi-weekly basis. Key features include built-in smart contract compilation, linking, deployment, binary management, automated testing with Mocha and Chai, a configurable build pipeline, and a scriptable deployment and migrations framework. Truffle streamlines the entire DApp development lifecycle, offering tools for writing, compiling, testing, and deploying smart contracts efficiently, distinguishing itself through its integrated suite of tools and strong community support. It also bundles a local development blockchain server and integrates with tools like Ganache and Truffle Dashboard for enhanced debugging and interaction.","status":"active","version":"5.11.5","language":"javascript","source_language":"en","source_url":"https://github.com/trufflesuite/truffle","tags":["javascript"],"install":[{"cmd":"npm install truffle","lang":"bash","label":"npm"},{"cmd":"yarn add truffle","lang":"bash","label":"yarn"},{"cmd":"pnpm add truffle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended for advanced local development environments, though Truffle bundles a basic local server.","package":"ganache","optional":true}],"imports":[{"note":"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).","wrong":"const truffle = require('truffle');","symbol":"truffle","correct":"import * as truffle from 'truffle';"},{"note":"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.","wrong":"import { Config } from 'truffle';","symbol":"Config","correct":"import Config from '@truffle/config';"},{"note":"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.","symbol":"console","correct":"import \"truffle/console.sol\";"}],"quickstart":{"code":"npm install -g truffle\n\nmkdir my-truffle-project\ncd my-truffle-project\n\ntruffle init\n\n# Open truffle-config.js and ensure Node 20 is supported (if not already)\n// module.exports = {\n//   networks: {\n//     development: {\n//       host: \"127.0.0.1\",\n//       port: 8545,\n//       network_id: \"*\"\n//     }\n//   },\n//   compilers: {\n//     solc: {\n//       version: \"^0.8.0\" // or specify a newer version like \"0.8.21\"\n//     }\n//   }\n// };\n\ntruffle compile\ntruffle migrate\ntruffle test","lang":"typescript","description":"Demonstrates the initial setup of a Truffle project, compiling and deploying smart contracts, and running tests. This uses the globally installed Truffle CLI."},"warnings":[{"fix":"Upgrade Node.js to version 16.20, 18.16, or 20 using a tool like `nvm` (`nvm install 20 && nvm use 20`).","message":"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.","severity":"breaking","affected_versions":">=5.11.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`).","message":"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`).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.11.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the `@truffle/contract` package: `npm install @truffle/contract`. Ensure `truffle` is at a compatible version for your contract abstractions.","cause":"Attempting to import `@truffle/contract` without it being installed as a dependency, or using an outdated `require('truffle-contract')` pattern.","error":"Error: Cannot find module '@truffle/contract'"},{"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.","cause":"The Solidity compiler version specified in `truffle-config.js` (or implied) is incompatible with the contracts or the `truffle` version itself.","error":"Error: `truffle test` fails with 'Cannot compile contracts with solc version X'"},{"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: \"*\" } }`.","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.","error":"Error: `truffle migrate` fails with 'No network defined in configuration'"}],"ecosystem":"npm"}