Skip to content
A library for building excellent user experiences with Blockstack.
TypeScript JavaScript HTML CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci basic circleCI setup Dec 10, 2019
src feat: make `manifestPath` optional Feb 18, 2020
test-app fix: remove returns Feb 18, 2020
.babelrc support optional chaining Dec 17, 2019
.eslintignore
.eslintrc.js no need for display names imho Jan 28, 2020
.gitignore deps updates Feb 4, 2020
.npmignore cleanup, better local testing Jan 14, 2020
.prettierrc.js
LICENSE first commit from tsdx create Dec 3, 2019
README.md feat: updated README Feb 18, 2020
package.json build: minor version bump Feb 17, 2020
tsconfig.json initial api, components Dec 17, 2019
webpack.config.js fix: Spacing of new auth flow (#28) Feb 4, 2020
yarn.lock update @blockstack/ui to latest Feb 17, 2020

README.md

@blockstack/connect

A library for building excellent user experiences with Blockstack.

Demo

To get a test feel for the user experience of using connect, you can use Banter.

Why?

Although blockstack.js exposes everything you need to handle authentication with Blockstack, there is still the hard problem of getting users used to the paradigm of authentication that is privacy-first and self-sovereign. Many apps implement their own dialogues before authentication, which explain what Blockstack is and why they use it.

@blockstack/connect provides developers with a plug-and-play API that is simple to use, and provides great, out-of-the-box education that end-users can understand.

Installation

With yarn:

yarn add @blockstack/connect

With npm:

npm install --save @blockstack/connect

API

AuthOptions

Every major method you'll use with connect requires you to pass some options, like the name and icon of your app, and what to do when authentication is finished. In practice, this means you need to define these options, and pass them to the various API methods.

The exact interface you'll use is defined as:

export interface AuthOptions {
  // The URL you want the user to be redirected to after authentication.
  redirectTo: string;
  manifestPath?: string;
  finished?: (payload: FinishedData) => void;
  authOrigin?: string;
  sendToSignIn?: boolean;
  userSession?: UserSession;
  appDetails: {
    name: string;
    icon: string;
  };
}
  • redirectTo: The path in your app where users go after sign in.
  • appDetails: an optional object which includes appName: string and appIcon: string. This will speed up the process of loading your app's information during onboarding.
  • manifestPath: (optional) - the path in your app where your manifest.json file can be found
  • finished: (optional) - A callback that can be invoked after authentication. This prevents having to do a whole page refresh in a new tab. One argument is passed to this callback, which is an object with userSession included. If included, then the redirectTo path is ignored, and the user will be logged in automatically.
  • authOrigin: (optional) - The URL you'd like to use for authentication. Only necessary for local development of the authenticator.
  • sendToSignIn: (optional) - defaults to false. Whether the user should go straight to the 'sign in' flow.
  • userSession: (optional) - pass a UserSession instance to use for authentication. If it's not passed, @blockstack/connect will create one for you.

In React Apps

If you're using connect in a React app, then the best option is to include connect's React infrastructure in your React app.

First, setup the Connect provider at the "top-level" of your app - probably next to wherever you would put a Redux provider, for example.

import { Connect } from '@blockstack/connect';

const authOptions = {
  redirectTo: '/',
  finished: ({ userSession }) => {
    console.log(userSession.loadUserData());
  },
  appDetails: {
    name: 'My Cool App',
    icon: 'https://example.com/icon.png',
  },
};

const App = () => (
  <Connect authOptions={authOptions}>
    // the rest of your app's components
  </Connect>
)

Later, when you want to begin the onboarding process, use the useConnect hook to get connect's doOpenAuth method.

import { useConnect } from '@blockstack/connect';

const SignInButton = () => {
  const { doOpenAuth } = useConnect();

  return (
    <Button onClick={doOpenAuth}>
      Sign In
    </Button>
  )
}

In ES6 apps

If you aren't using React, or just want a simpler API, then you can use the showBlockstackConnect method.

import { showBlockstackConnect } from '@blockstack/connect';

const authOptions = { /** See docs above for options */ };
showBlockstackConnect(authOptions);

Using a hosted version of @blockstack/connect

If you aren't using ES6 imports, you can still use connect! We package the library so that it can be automatically used with unpkg.

First, include the script in your HTML:

<script src="https://unpkg.com/@blockstack/connect/dist/bundle.js" />

Then, you can use API methods under the blockstackConnect global variable:

const authOptions = { /** See docs above for options */ };
blockstackConnect.showBlockstackConnect(authOptions);

Local Development

There is a test app located in /test-app. cd test-app && yarn && yarn start to run a local react app with fast-refresh.

You can’t perform that action at this time.