React Holochain Hook available at npm

Technical Discussion App Development
#1

I wrote a React Hook to provide easy Holochain access to components.

:link: react-holochain-hook

Feedback and PRs welcome!

React Holochain Hook

Provides React apps with easy access to Holochain using the useHolochain() hook.

Encapsulates hc-web-client in a React Context, provides sensible connection status information, some automation and a few convenience functions. :pisces: :unicorn::rainbow:

npm version npm downloads gzip size

Installation

Install it with yarn:

yarn add react-holochain-hook

Or with npm:

npm i react-holochain-hook --save

Usage

Setting up

import { 
  ProvideHolochain, 
  useHolochain, 
  CONNECTION_STATUS 
  } from 'react-holochain-hook'

const Connected = () => {
  const hc = useHolochain()
  if (hc.status === CONNECTION_STATUS.CONNECTED) {
    return <div>✅ Connected</div>
  }
  return null
}

function App() {
  return (
    <div className="App">
      <ProvideHolochain options={{ url: 'ws://localhost:10003' }}>
        <Connected />
      </ProvideHolochain>
    </div>
  );
}

Talk to Holochain, display data in React component

import { useEffect, useState } from 'react'

const CronutCounting = () => {
  const hc = useHolochain()
  const [cronutCount, setCronutCount] = useState(0)

  useEffect(() => {
    if (hc.status === CONNECTION_STATUS.CONNECTED) {
      try {
        hc.connection.callZome(
          'instance_id',
          'my_cronut_zome',
          'count_cronuts')()
          .then((result) => {
            const obj = JSON.parse(result)
            if (obj.Ok) {
              setCronutCount(obj.Ok)
            }
          })
      } catch (err) {
        console.log("Unable to count cronuts.")
      }
    }
  }, [hc.connection, hc.status,])

  return <div>{cronutCount} cronuts counted. 🍩🍩</div>
}

API

ProvideHolochain

Encapsulates hc-web-client using a React Context, making holochain connection available throughout the application.

Auto connects to Holochain when application starts.

In development (process.env.NODE_ENV === 'development'):

  • Attempt connection at ws://localhost:3401.
  • Override port number by setting process.env.REACT_APP_WSPORT
  • Manually set url by providing options prop.

In production

  • Attempt to fetch connection settings from conductor at the auto generated /_dna_connections.json
  • Manually set url by providing options prop.

Props:

  • options {Object}: (OPTIONAL) Client options that are also forwarded to hc-web-client and rpc-websockets.
    • url{String}: Websocket url to access Holochain.
    • timeout {Number}: Connection timeout in milliseconds. Defaults to 5000.
    • wsClient {Object}: Client options that are also forwarded to ws.
      • autoconnect {Boolean}: Client autoconnect upon Client class instantiation. Defaults to true.
      • reconnect {Boolean}: Whether client should reconnect automatically once the connection is down. Defaults to true.
      • reconnect_interval {Number}: Time between adjacent reconnects. Defaults to 2000.
      • max_reconnects {Number}: Maximum number of times the client should try to reconnect. Defaults to 5. 0 means unlimited.

useHolochain

Gives access to holochain connection, connection status, etc.

Returns object containing:

  • options {Object}: Options for current connection (READ ONLY)
  • connect {Function}: Connect manually to Holochain using the same options as described for ProvideHolochain. Use only when status is NOT_CONNECTEDor CONNECT_FAILED.
  • connection {Any}: Exposes the underlying hc-web-client connection object with the call, and callZome functions. See hc-web-client for details.
  • status {Number}: Connection status using the values specified by CONNECTION_STATUS
  • setMeta(key, value) {Function}: Convenience funtion to save connection related metadata during the lifespan of the connection.
  • meta{Object}: Metadata object in the form of key/value pairs.
export const CONNECTION_STATUS = {
  NOT_CONNECTED: 0,
  CONNECTING: 1,
  CONNECTED: 2,
  ATTEMPTING_RECONNECT: 3,
  CONNECT_FAILED: 4
}

Contributing

Yes, please do! Raise an issue or post a pull request. Let’s make working with Holochain a breeze!

TODO

  • Add TypeScript types

License

AGPL-3.0

8 Likes
#2

Awesome. It is nice to see at least one alternative to hc-redux-middleware, up to date with React hooks style.

1 Like
#3

:+1: Yup, for smaller apps Redux can often feel a bit overkill. Then hooks are awesome.

#4

I corrected a small bug and posted a new version that actually … works. :slight_smile:

4 Likes
#5

@kristofer, would you happen to have some time this weekend and help me with trying to integrate Holochain into my capstone project with your react-holochain-hook?

EDIT: I’ve opened a new topic on the forum for a weekend hacking session for everyone to join. See here:

1 Like
#6

Sending you a DM.

1 Like