truffle-plugin-modularizer

Truffle plugin to export built contract artifacts as a Javascript module

Motivation

When we make a DApp, we usually use truffle and ReactJS or VueJS together. But to integrate the front-end with the truffle contracts, we had to integrate the repositories also. Because integrating contracts & front-end app in a repository increases complexity, it might be better to seperate them. Therefore, this library offers a easy way to package and publish the smart contracts on the npm library, and then you can easily use the contracts with truffle-contract instance in a seperated ReactJS or VueJS application.

Now, let's import truffle projects into NodeJS applications more easily

Usage (after plugin setting)

$ truffle run modularize --help

Modularizer to export your truffle project as a node module

Usage: truffle run modularize [options] [CONTRACT_NAMES...]

If CONTRACT_NAMES is ommitted and there is no setting in truffle-config.js,
this will modularize all contracts in the build/contracts directory

Options:

   -o, --output <path>   Path to write modularized js file. default path is 'src/index.js'
   -t, --target <path>   Path to read built artifacts of contracts. default path is 'build/contracts'
   -n, --network <name>  Specify name of the network to record deployed addresses to the module
   -a, --all             It will modularize all contracts

You can store your custom settings in truffle-config.js

{
  ...,
  modularizer:
    {
      output: "src/index.js",
      target: "build/contracts",
      includeOnly: [
        "FirstContractName",
        "SecondContractName"
      ], // if you don\'t configure includeOnly property, it will save all contracts
      networks: [
        1,
        2
      ] // if you don\'t configure networks property, it will save all networks
    },
  ...
}

How to use (from scratch)

Step 1: Install plugin

$ npm install --save-dev truffle-plugin-modularizer

Step 2: Modify your truffle-config.json to configure plugin

// truffle-config.js
module.exports = {
  ...,
  plugins: [
    'truffle-plugin-modularizer'
  ],
  modularizer: {
    // output: 'src/index.js',
    // target: 'build/contracts'
    // includeOnly: [],
    // networks: []
  },
  ...
}

Step 3: Build contracts and run modularize

$ truffle compile
$ truffle migrate
$ truffle run modularize

This command generates src/index.js file.

Step 4: Configure package.json file & publish

If you don't have package.json, run npm init and set your entrypoint

// package.json
{
  "name": "your-project-name",
  "main": "src/index.js",
  ...
}

$ npm publish

Step 5: Use the deployed contract package in your ReactJS applicaton

$ cd /your/react/app/path
$ npm install --save "your-project-name"

Step 6: Import contracts into your front-end application and init with web3 provider

// ex: ReactJS, file: App.js
import React, { Component } from "react";
import ReactDOM from "react-dom";
import Web3 from 'web3';
import { YourContract } from 'your-project-name'

class App extends Component {
  constructor() {
    super();
    this.state = { data: [] };
  }
  async componentDidMount() {
    const web3 = window.web3 ? window.web3 : new Web3(yourCustomProvider)
    const yourContract = await YourContract(web3).at("0xCONTRACT_ADDRESS") 
    // const yourContract = await YourContract(web3).deployed()
    // const yourContract = await YourContract(web3).new()
    const values = await yourContract.getValues() // Assue that this returns an BigNumber array
    this.setState({ values });
  }
  render() {
    return (
      <div>
        <ul>
          {this.state.data.map(item => (
            <li>
              {item.toString()}
            </li>
          ))}
        </ul>
      </div>
    );
  }
}
export default App;
ReactDOM.render(<App />, document.getElementById("app"));

You can read the test cases here

Contribute

1. Fork & clone

   git clone https://github.com/{your-id}/truffle-plugin-modularizer

2. Install packages & run test cases

   npm install
   npm run test

3. Modify sample contracts & add some features

   vim src/index.js # entry point
   vim src/modualrizer.js # exports Contract.json files to js module
   vim src/parser.js # option parser
   vim src/manual.js # prints manual for this plugin
   vim sample-truffle/contracts/SampleContract.sol # Sample contract for testing

4. Add test cases for new features

   vim test/modularizer.default.js # test cases for default setup
   vim test/modularizer.config.js # test cases for truffle-config.js options
   vim test/modularizer.cli.js # test cases for cli options

5. Run test & commit (Read conventional commit)

   Husky will automatically run linter & test cases

   npm run test
   git add . && git commit -m "feat: add a new feature ~~"

License

Apache-2.0