lib.md

Importing Truffle as a module

const truffle = require("truffle");

Beginning with v5.0.30, Truffle exports the methods listed in truffle-core/index.js. This means your plugin can consume the user's Truffle instance as a library and access a subset of its internal command APIs.

These are useful if you need to touch several Truffle commands in succession. For example, imagine a plugin that evaluated how a contract system performed at different levels of solc optimization. Its workflow might look like:

for a range of solc settings:
   compile contracts to a temp folder
   run user's tests using the temp artifacts
   measure and save gas usage data

aggregate data and report

The Truffle library lets you do this without making the user add configuration or string their own commands together.

⚠️ Important Note ⚠️

Truffle does not guarantee its internal APIs will follow semver. You should be prepared for your user to run any Truffle version and handle mismatches gracefully. By using the library you are entering into a gentleperson's agreement to manage API volatility and other contingencies on your user's behalf. Some tips:

• Always require Truffle in a try/catch block
• At runtime, verify the API components you need are actually exposed
• Consume separately published (and semver guaranteed) Truffle modules when possible
• Add yourself to the Truffle repo watch list on GitHub and keep abreast of internal changes that might affect you.
• Do not go on vacation