🚧 ReactTruffle is a WIP 🚧
- Expand the feature set
- Improve testing strategy
- QA / identifying potential problems or performance issues
The purpose of this package is to provide an excellent developer experience for those looking to integrate Ethereum smart contracts into their web app. The project itself is heavily inspired by ReactRedux, so any familiarity there will make understanding this API a breeze.
This package makes use of the Truffle framework, and more specifically the truffle-contract
node package. It's recommended that you first become familiar with writing and compiling smart contracts with Truffle, then use this package to utilize your contracts with ease.
This package can be installed using npm.
npm install --save react-truffle
You can easily get a truffle development environment up and running by following the instructions outlined on their page. For simplicity I recommend the React box: http://truffleframework.com/boxes/react. Basic contracts and functions are provided for you in their boxes, making it easy to jump right in.
Once that's set up you can simply install this package (see above) and start using the components!
A very simple example of what wrapping a component with a contract looks like
import React, {Component} from 'react';
import Thing from './components/Thing';
import SimpleStorage from './build/SimpleStorage.json';
import {ContractProvider, withContract} from 'react-truffle';
const mapContractToProps = contract => ({
get: contract.get,
set: contract.set
});
const ThingWrappedWithContract = withContract(
SimpleStorage,
mapContractToProps
)(Thing);
const App = () => (
<ContractProvider>
<ThingWrappedWithContract />
</ContractProvider>
);
export default App;
This component provides a ContractStore
to all of your components created by withContract
within its hierarchy.
store
(optional) - If for any reason you'd like to pass in your ownContractStore
. This allows you to initialize a store with opts and/or pre-cached contract objects. 🚧 In theory this could be built server-side and used to hydrate the provider on the front-end. 🚧...rest
(optional) - All other props will be passed to theContractStore
asopts
.children
(ReactElement) - The root of your component hierarchy
This function returns a component that wraps Component
and provides it with props as specified by a combination of mapContractToProps
and {opts}
.
contract
- A smart contract compiled into JSONmapContractToProps
(optional) - A function that accepts the contract as an argument and returns an object consisting of the desired props forComponent
. An example of this can be seen above. If no function is provided, the whole contract will be provided as props in a singlecontract
object.opts
(optional) - An object of options for configuring the componentsubscribeToAccountChange
(true) - receive updates from theContractStore
if the web3 account changesrenderBeforeContractResolves
(false) - it takes time to find a contract on the blockchain. By default, the component won't render until the contract is available. If you design your wrapped component to handle a lack of contract props gracefully then you should set this to true.renderCountProp
(false) - simply provides a proprenderCount
toComponent
for debugging
opts
(optional) - An object of options for configuring the storepollInterval
(5000) - In ms, how often the store should poll web3 for account changesautoPoll
(true) - Set to false if you'd like to disable polling or manually trigger polling
This class performs the underlying work of:
- making web3 requests
- caching contract objects
- polling for account changes and notifying notifySubscribersSpy
You generally shouldn't find a need to perform any operations on it directly unless you're:
- writing your own components that consume
ContractStore
oncontext
- manipulating the
ContractStore
before providing it as a prop to<ContractProvider>
startPolling()
,stopPolling()
- Start and stop polling for account changes on the web3 object.subscribe(callback)
- Subscribe to account changes by passing a callback. Returns a callback for unsubscribing.notifySubscribers()
- Call the callbacks of all the subscribers.getContract(contract)
-contract
is a smart contract compiled to JSON. Find the contract in cache or on the blockchain. Returns aPromise
that resolves when the contract can be found in cache.
npm test
Accepting PRs - WIP
- Trevor Scheer - Initial work
This project is licensed under the MIT License - see the LICENSE.md file for details