truffle

library0.1.dev0jsnpmunverified

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.

data workflow testing devops

npm install truffle

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TRUFFLE

truffle

datajavascriptv0.1.dev0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

truffle

✓ import * as truffle from 'truffle';

✗ const truffle = require('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

✓ import Config from '@truffle/config';

✗ import { Config } from 'truffle';

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.

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

truffle --version

Debug

Known issues

breakingTruffle 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`).

affects: >=5.11.3

gotchaWhen 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.

affects: All

gotchaThe 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`).

affects: All

gotchaTruffle'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.

affects: >=5.11.0

deprecatedSome 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.

affects: All

Errors

Common errors & fixes

Error: Cannot find module '@truffle/contract'

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'

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'

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: "*" } }`.

Upgrade

Version history

0.1.dev0latest on npm

Audit

Dependencies

ganacheoptionalRecommended for advanced local development environments, though Truffle bundles a basic local server.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/trufflesuite/truffle ↗

packagehttps://www.npmjs.com/package/truffle ↗

homepagehttps://trufflesuite.com ↗