161 lines
6.2 KiB
Markdown
161 lines
6.2 KiB
Markdown
title: Subspace 2.0
|
|
author: richard_ramos
|
|
summary: "New components to simplify the usage of Subspace within React projects"
|
|
categories:
|
|
- announcements
|
|
- releases
|
|
- subspace
|
|
layout: blog-post
|
|
image: '/assets/images/subspace.png'
|
|
---
|
|
|
|
Subspace 2.0
|
|
===
|
|
|
|
New to subspace? Check out the website at [http://subspace.embarklabs.io/](http://subspace.embarklabs.io/)
|
|
|
|
## Introducing Subspace React's components
|
|
A new set of components were created to simplify the usage of Subspace within React projects. Learn more about them [here](https://subspace.embarklabs.io/react.html)
|
|
|
|
### Install
|
|
You can install it through `npm` or `yarn`:
|
|
```
|
|
npm install --save @embarklabs/subspace-react web3 rxjs
|
|
```
|
|
|
|
|
|
### Usage
|
|
|
|
#### SubspaceProvider
|
|
To use most of the `subspace-react` components, you need to wrap your app with the `<SubspaceProvider web3={web3} />` component. This will make Subspace available to any nested components that accesses it via the `useSubspace` hook or has been wrapped in the `withSubspace` higher order component. Any React component might use Subspace so it makes sense to add the provider near the top level of your DApp. The `SubspaceProvider` requires a web3 object to interact with an Ethereum node.
|
|
|
|
```js
|
|
// index.js
|
|
import React from 'react'
|
|
import ReactDOM from 'react-dom'
|
|
import MyApp from './MyApp'
|
|
import { SubspaceProvider } from '@embarklabs/subspace-react';
|
|
|
|
const web3 = new Web3("ws://localhost:8545");
|
|
|
|
const rootElement = document.getElementById('root')
|
|
ReactDOM.render(
|
|
<SubspaceProvider web3={web3}>
|
|
<MyApp />
|
|
</SubspaceProvider>,
|
|
rootElement
|
|
);
|
|
```
|
|
|
|
#### useSubspace
|
|
Rather than relying on global variables or passing Subspace through props, the easiest way to access Subspace features is via the `useSubspace` hook. Be sure that your entire DApp is wrapped with a `<SubspaceProvider />` to have it available throughout the component tree.
|
|
```js
|
|
// index.js
|
|
import React from 'react'
|
|
import { useSubspace } from '@embarklabs/subspace-react';
|
|
|
|
const MyComponent = () => {
|
|
const subspace = useSubspace();
|
|
|
|
// do something....
|
|
// subspace.trackBalance(web3.eth.defaultAccount);
|
|
|
|
return ...;
|
|
}
|
|
|
|
export default MyComponent
|
|
```
|
|
|
|
#### withSubspace
|
|
This higher order component is provided as an alternative to the `useSubspace` hook. This injects the `subspace` property with an already initialized Subspace instance. Just like with the hook, your entire DApp needs to be wrapped with a `<SubspaceProvider />`.
|
|
|
|
```js
|
|
// index.js
|
|
import React from 'react'
|
|
import { withSubspace } from '@embarklabs/subspace-react';
|
|
|
|
const MyComponent = (props) => {
|
|
// do something....
|
|
// props.subspace.trackBalance(web3.eth.defaultAccount);
|
|
|
|
return ...;
|
|
}
|
|
|
|
export default withSubspace(MyComponent);
|
|
```
|
|
|
|
|
|
#### observe
|
|
|
|
This function is useful to make your component subscribe to any observable props it receives when the component is mounted and automatically unsubscribes when the component is unmounted. It can be used with any kind of observables. This component already existed in the previous version of Subspace. The only difference is that it has been moved to the `subspace-react` package.
|
|
|
|
|
|
```js
|
|
import { observe } from '@embarklabs/subspace-react';
|
|
|
|
const ObserverComponent = observe(WrappedComponent);
|
|
```
|
|
|
|
##### Example usage:
|
|
```js
|
|
const MyComponent = ({eventData}) => {
|
|
// Handle initial state when no data is available
|
|
if (!eventData) {
|
|
return <p>No data</p>;
|
|
}
|
|
|
|
return <p>Value: {eventData.someReturnValue}</p>
|
|
};
|
|
|
|
|
|
const MyEnhancedComponent = observe(MyComponent);
|
|
|
|
|
|
const SomeOtherComponent = () => {
|
|
const myObservable$ = MyContractInstance.events.MyEvent.track({fromBlock: 1});
|
|
return <MyEnhancedComponent myProp={myObservable$} />;
|
|
}
|
|
```
|
|
|
|
|
|
## Breaking changes
|
|
|
|
- **Peer dependencies**
|
|
Installing subspace requires explicitly installing `web3` and `rxjs` as peer depenencies, while before they were installed as dependencies of the package
|
|
```js
|
|
npm install --save @embarklabs/subspace web3 rxjs
|
|
```
|
|
|
|
- **Web3**
|
|
In the previous version, Subspace received a web3.js provider in the constructor. This new version receives instead a `Web3` object:
|
|
```js
|
|
const web3 = new Web3("http://localhost:8545");
|
|
const subspace = new Subspace(web3);
|
|
```
|
|
|
|
- **`init()` is `async`.**
|
|
This means that you need to wait until Subspace has been initialized to use its features:
|
|
```js
|
|
await subspace.init();
|
|
```
|
|
|
|
- The `observe` higher-order component was moved from the `@embarklabs/subspace` package to the new `@embarklabs/subspace-react` package.
|
|
|
|
- If no call interval is specified in the Subspace options, it will use the average blocktime as the interval of time to poll the contract addresses for changes in state or balance.
|
|
|
|
|
|
## Maintenance / Bug fixes
|
|
- Major refactor increasing the usage of observables within the subspace package: Subjects in tracking functions were replaced by observables (they still keep the same functionality), New blocks and interval timers are done via observables.
|
|
- Subscriptions to web3js are handled automatically depending on the number of subscribers. The subscriptions are kept if there is at least one observer subscribed to an observable, otherwise the subscription is closed and will be reopened once there's a new subscriber.
|
|
- The checksum of the address to be tracked is performed automatically when performing balance tracking
|
|
- Dropped the usage of `web3-utils`.
|
|
- Simplified the logic for tracking events
|
|
- Added Lerna to the repository to organize the different packages, as well as making the documentation part of the project
|
|
- Updated all the examples to use the latest subspace-react components
|
|
|
|
### Contributions
|
|
|
|
Subspace and the entire Embark labs organization are open source. As such, we welcome contributions and input from the community using the product.
|
|
|
|
If you'd like to contribute to Subspace, please fork this [repository](https://github.com/embarklabs/subspace), fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on #embark-status channel to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.
|