npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@aragon/api-react

v2.2.4

Published

Aragon app API for React

Downloads

74

Readme

aragonAPI for React

This module allows for interacting with aragonAPI with React Hooks. @aragon/api is used under the hood, so being familiar with it can be useful.

Usage

import { AragonApi, useAragonApi } from '@aragon/api-react'

function App() {
  const { api, appState } = useAragonApi()
  const { count = 0 } = appState

  return (
    <div>
      <div>{count}</div>
      <button onClick={() => api.increment(1).toPromise()}>Increment</button>
    </div>
  )
}

ReactDOM.render(
  <AragonApi>
    <App />
  </AragonApi>,
  document.getElementById('root')
)

This is a simple example demonstrating how we can use @aragon/api-react to connect an app's frontend to its contract, fetch some data from its state (appState), and trigger an action on it (api.increment(1)). The full API is detailed below.

Installation

Install it alongside @aragon/api:

npm install --save @aragon/api @aragon/api-react

Documentation

<AragonApi />

Before using any Hook provided, you need to declare this component to connect the app. It is generally a good idea to do it near the top level of your React tree. It should only be declared once.

It has an optional reducer prop, which lets you process the state coming from the background script. If not provided, the state is passed as-is.

Example

import { AragonApi, useAppState } from '@aragon/api-react'
import BN from 'bn.js'

function App() {
  const { balance } = useAppState()
  return <div>{balance.toString(10)}</div>
}

function reducer(state) {
  if (state === null) {
    // initial sync
    return { balance: new BN(0) }
  }
  return { balance: new BN(state.balance) }
}

ReactDOM.render(
  <AragonApi reducer={reducer}>
    <App />
  </AragonApi>,
  document.getElementById('root')
)

useAragonApi()

A React Hook that returns the data needed to interact with the app contract.

As with any React Hook, please ensure that you follow the Rules of Hooks.

It returns an object containing the following entries:

api

This is the current AragonApp instance. Use it to call methods on the contract.

Example:

function App() {
  const { api } = useAragonApi()
  return <button onClick={() => api.vote(true).toPromise()}>Vote</button>
}

appState

The app state, after having passed the background script state through the reducer prop of AragonApi.

Example:

import { useAragonApi } from '@aragon/api-react'

function App() {
  const { appState } = useAragonApi()
  return <div>{appState.count}</div>
}

connectedAccount

The connected Ethereum account. Its value is "" (empty string) when there is no account connected.

Example:

function App() {
  const { connectedAccount } = useAragonApi()
  return (
    <div>Account: {connectedAccount ? connectedAccount : 'Not connected'}</div>
  )
}

currentApp

Details about the current app. Once loaded, it returns a single object with the following keys:

  • abi: the app's ABI
  • appAddress: the app's contract address
  • appId: the app's appId
  • appImplementationAddress: the app's implementation contract address, if any (only available if this app is a proxied AragonApp)
  • identifier: the app's identifier, if any
  • isForwarder: whether the app is a forwarder
  • kernelAddress: the app's attached Kernel address (i.e. organization address)
  • name: the app's name, if available
  • roles (experimental): an array of this app's roles

Each app detail also includes an icon(size) function, that allows you to query for the app's icon (if available) based on a preferred size.

Its value is null until it gets loaded.

Example:

function App() {
  const { currentApp } = useAragonApi()
  return (
    <div>
      <img width="40" height="40" src={app.icon(40)} />
      {currentApp.appAddress}
    </div>
  )
}

guiStyle

The GUI style sent by the client. It contains two entries: appearance and theme.

appearance is currently one of light or dark. Other values could be passed in the future (e.g. black for OLED screens). It is always present and should be respected by apps to display a corresponding theme, unless theme is present.

theme contains an entire theme object (e.g. aragonUI's light theme) that should be applied to the app. It is optional and apps should respect it when present. If not possible, apps should respect the value of appearance.

Example:

function App() {
  const { guiStyle } = useAragonApi()
  return (
    <div
      style={{
        background: guiStyle.appearance === 'light' ? 'white' : 'grey',
      }}
    >
      <div
        style={{ color: guiStyle.appearance === 'light' ? 'black' : 'white' }}
      >
        Hello world
      </div>
    </div>
  )
}

Complete example if you are using aragonUI:

// index.js
import React from 'react'
import ReactDOM from 'react-dom'
import { AragonApi } from '@aragon/api-react'

ReactDOM.render(
  <AragonApi reducer={/* … */}>
    <App />
  </AragonApi>,
  document.getElementById('root')
)
// App.js
import React from 'react'
import { useGuiStyle } from '@aragon/api-react'
import { Main } from '@aragon/ui'

function App() {
  // useGuiStyle() updates whenever the theme
  // gets updated in the client running the app.
  const { appearance } = useGuiStyle()

  return (
    <Main theme={appearance}>
      <Header>Hello world</Header>
    </Main>
  )
}

installedApps

The complete list of apps installed in the organization. Its value is an empty array ([]) until the list of apps are loaded.

Each object in the array holds the same keys as currentApp.

Example:

function App() {
  const { installedApps } = useAragonApi()
  return (
    <div>
      {installedApps.map(app => (
        <div>{app.appAddress}</div>
      ))}
    </div>
  )
}

network

An object representing the current network using its id and type entries. Its value is null until it gets loaded.

Example:

function App() {
  const { network } = useAragonApi()
  return <div>Current network: {network.type}</div>
}

path / requestPath()

The app's current path. Its value is "/" by default.

Use requestPath() to request the app be navigated to another path. Note that the navigation request may be rejected, and in that case the path will stay constant.

Example:

function App() {
  const { path, requestPath } = useAragonApi()

  // “Hello World” screen
  if (path === '/hello-world') {
    return (
      <div>
        <h1>Hello World</h1>
        <button onClick={() => requestPath('/')}>
          Back
        </button>
      </div>
    )
  }

  // Home
  return (
    <div>
      <button onClick={() => requestPath('/hello-world')}>
        Click
      </button>
    </div>
  )
}

useApi()

This Hook returns the same data as the api entry from the useAragonApi() hook.

useAppState()

This Hook returns the same data as the appState entry from the useAppState() hook.

useConnectedAccount()

This Hook returns the same data as the connectedAccount entry from the useAragonApi() hook.

useCurrentApp()

This Hook returns the same data as the currentApp entry from the useAragonApi() hook.

useGuiStyle()

This Hook returns the same data as the guiStyle entry from the useAragonApi() hook.

useInstalledApps()

This Hook returns the same data as the installedApps entry from the useAragonApi() hook.

useNetwork()

This Hook returns the same data as the network entry from the useAragonApi() hook.

usePath()

This Hook returns an array holding two values from the useAragonApi() hook:

  1. path, and
  2. requestPath