React Blockstack
React hooks to use the Blockstack SDK with react function components.
Includes backward compatibility with react class components.
Installation
npm install react-blockstack
Blockstack Authentication
Execute as early as possible to initialize the Blockstack SDK and user authentication:
const blockstack =
Consider placing this code in the main index.js file of your project. For customization of the authentication, use the same options argument as for UserSession in the Blockstack SDK:
const appConfig = 'store_write' 'publish_data'const blockstack =
The blockstack.userSession
property is available in case you need to access to the blockstack SDK on toplevel. It is typically preferable to get userSession
from the useBlockstack
hook, ignoring the return value from ReactBlockstack
.
React Hook for Function Components
The package provides a useBlockStack
React hook for use in function components. It provides access to the Blockstack SDK and eventually an authenticated user:
const {userSession, userData, signIn, signOut, person} = useBlockstack()
The hook returns these properties:
userSession
(UserSession interface for the Blockstack SDK)userData
(UserData interface from the Blockstack SDK;null
unless authenticated)authenticated
(true when authentication is complete)signIn
(function to sign in the user;null
when already logged in or pending authentication)signOut
(function to sign out the user;null
when not logged in or pending authentication)person
(if authenticated, a Person instance containing the user profile)
Only userSession
and signIn
are available before authentication.
After authentication, signIn
is null, but there are bindings for
userData
, authenticated
, signOut
and person
. This can be used for conditional rendering
depending on the authentication status. Note that the user can neither sign in nor sign out when the authentication is pending, so:
const pendingAuthentication = !signIn && !signOut
Example: Authentication Button
Here is a react function component that implements an authentication button. It handles both signin and logout, adapting the label depending on status, disabling the button while authentication is pending:
{ const signIn signOut = return <button disabled= !signIn && !signOut onClick= signIn || signOut > signIn ? "Sign In" : signOut ? "Sign Out" : "..." </button> }
To include the button in jsx:
<Auth />
Persistent Data Storage
The useFile(path: string)
hook is used to access the app's data store, covering
the functionality of getFile
, putFile
and deleteFile
in the Blockstack SDK.
The argument is a pathname in the app's data store. The file does not have to exists before the call.
The useFile
hook returns the content of the file like getFile
, with a function to change the file content as second value. The returned content is undefined
until the file has been accessed and null
if the file is determined not to exist. The setter accepts the same content types as putFile
, and will delete the file if called with null
. The content returned by useFile
is conservatively updated, not reflecting the change until after storing the content is completed.
Example
const content setContent =
Blockstack Connect
React Blockstack can be used with Blockstack Connect.
To ensure that the state is properly updated after Connect authentication,
make Connect's authOptions.finished
callback function call didConnect()
.
The useConnectOptions()
hook can be used to fill in default options like the
userSession
. The argument is the same as the authOptions in Connect.
The hook provides sensible defaults if called without an argument.
Example
const connectOptions = redirectTo: '/' { } ; const App = { const authOptions = ; return <Connect authOptions=authOptions> // the rest of your app's components </Connect>}
React Class Components
For conventional React class components, the package provides an optional
React context object
that pass properties from useBlockstack
down to components.
Enclose top level elements in a shared Blockstack context:
ReactDOM
The Blockstack SDK properties are implicitly passed through the component tree and can be used as any other React context.
Example
The App component below will automatically be updated whenever there is a change in the Blockstack status. Note the use of the this.context
containing the properties and
that the class is required to have contextType = BlockstackContext
.
static contextType = BlockstackContext { const person = thiscontext const avatarUrl = person && personavatarUrl && person const personName = person && personname && personname return <div> <img hidden= !avatarUrl src= avatarUrl /> personName <Auth /> </div> }
If there are multiple Blockstack components they will all share the same context.
Live Demo
The REBL Stack starter app is a reimplementation of the Blockstack react template.
It demonstrates different ways of using react-blockStack. You are encouraged to use the example as a starting point for your own projects.