Initial Setup

Installing the SDK & Incorporating it into Your Project

Getting set up with Capsule is easy, just get an API Key, Install the Capsule packages, and Instantiate the Capsule Class!

1. Get an API Key

First, you'll need an API key from the Capsule team. Please request one if you don't have one yet.

2. Install Capsule Packages

Install the relevant SDK packages using the following

# if you'd like to use our React modal components for easier integration
npm install @usecapsule/react-sdk
pnpm install @usecapsule/react-sdk
yarn add @usecapsule/react-sdk

# if you'd prefer to use the capsule SDK functionality directly with your own UI components
npm install @usecapsule/web-sdk
pnpm install @usecapsule/web-sdk
yarn add @usecapsule/web-sdk

2a. [Mobile App Only] Configure Project

Skip these steps if you're using Capsule with a web-based project

Note: These steps are for a bare React Native project. See our Expo example for how to use Capsule with Expo.

Install pods

cd ios && pod install && cd ..

Add capsule domains to your associated domains list(s)

For iOS, open ios/Runner.xcworkspace in Xcode

Navigate to Signing & Capabilities and add the capability "Associated Domains"

Add a new associated domain for each environment you will be using (this will most likely be beta and prod) Beta should be and Prod should be

You will also need to send us your full App ID, which is formatted as follows: <TEAM_ID>.bundleIdentifier You can find your Team ID via Apple developer console.

Polyfill the necessary libraries

Note: These steps are for React Native v0.73. See our examples for how to setup on previous React Native versions.

  1. Add the following to your metro.config.js file

    const nodeLibs = require("node-libs-react-native");
    // Other imports
    const config = {
      // Rest of your config
      resolver: {
        // Rest of your config.resolver
        extraNodeModules: {
          // Rest of your config.resolver.extraNodeModules
          crypto: require.resolve("react-native-crypto"),
          stream: require.resolve("readable-stream"),
          process: require.resolve("process"),
    module.exports = mergeConfig(getDefaultConfig(__dirname), config);
  2. Create a shim.js file in the root of your project with the following contents

    import { shim } from "@usecapsule/react-native-wallet";
    if (typeof process === "undefined") {
      global.process = require("process");
    } else {
      const bProcess = require("process");
      for (var p in bProcess) {
        if (!(p in process)) {
          process[p] = bProcess[p];
  3. Call your shim.js file in your index.js file

    import "./shim";
    // Rest of your `index.js` file

3. Instantiating the Capsule Class and Component

NOTE: There are two hosted Capsule environments, Environment.BETA is for development and testing and Environment.PROD is for production. If you prefer, you can also reference Beta as Environment.DEVELOPMENT.

If you're referencing Environments as strings, for example in a .env file, you should refer to these environments as BETA and PRODUCTION, respectively.

Web Modal

If you're using the CapsuleModal component, simply import the Modal Component into your application and configure it to your preferences. If you're using Next.js or a Server-Side rendering framework, you may need to do this via a dynamic import

import Capsule, {
} from '@usecapsule/react-sdk';

const capsule = new Capsule(
  { }   // Add options here to customize emails, passkey screen and more

const [isOpen, setIsOpen] = useState(false) // Use any state management you wish, this is purely an example!

// The default modal -- add oAuth methods, logos, themes via props
<CapsuleModal capsule={capsule} isOpen={isOpen} onClose={() => {setIsOpen(false)}} />

For the full list of configuration options on both capsule andCapsuleModal, check out the Customize Capsule section

Core SDKs

If you are using the Core SDK directly, either on Web or Mobile, here’s how you can import it.

If you are using the SDKs directly, you'll need to implement your own logic to connect the different auth steps. We've simplified this to ~5 functions, but as this approach is more nuanced, we recommend studying one of the Examples first and basing your integration off of them.

import { Capsule, Environment } from "@usecapsule/web-sdk";
const capsule = new Capsule(Environment.BETA, YOUR_API_KEY);

With the SDK now incorporated, the Capsule wallet should serve as a near seamless replacement for your existing wallet setup. The key replacement you'll need to make is substituting current Remote Wallet imports with the import from the Capsule library.

NOTE: Capsule is compatible with major libraries for signing like ethers.js , wagmi. and viem. For more on this, check out the Wagmi, Viem, and Ethers Quickstart

Last updated