This guide will walk you through the process of integrating the Capsule Modal into a Create React App (CRA) project that uses CRACO, ensuring a seamless way to manage user authentication and wallets.

If you haven’t already created your React app with CRA, follow

the official CRA docs

to scaffold a new project. Once you’ve set up CRA, you can install and configure CRACO:

CRACO docs

.

Prerequisites

To use Capsule, you need an API key. This key authenticates your requests to Capsule services and is essential for integration.

Don’t have an API key yet? Request access to the Developer Portal to create API keys, manage billing, teams, and more.

Installing Dependencies

First, install the Capsule React SDK using your preferred package manager:

npm install @usecapsule/react-sdk

Setting Up Polyfills in CRACO

Capsule relies on certain Node.js modules that are not available in the browser by default (e.g., crypto, buffer, stream). You’ll need to configure polyfills via CRACO’s config to ensure those modules work properly.

Install the necessary polyfill packages before updating your configuration:

npm install crypto-browserify buffer stream-browserify

Then, modify your craco.config.js:

craco.config.js
const webpack = require("webpack");

module.exports = {
  webpack: {
    configure: (webpackConfig) => {
      webpackConfig.resolve.fallback = {
        ...webpackConfig.resolve.fallback,
        crypto: require.resolve("crypto-browserify"),
        buffer: require.resolve("buffer/"),
        stream: require.resolve("stream-browserify"),
      };
      webpackConfig.plugins = [
        ...webpackConfig.plugins,
        new webpack.ProvidePlugin({
          process: "process/browser",
          Buffer: ["buffer", "Buffer"],
        }),
      ];
      return webpackConfig;
    },
  },
};

This configuration ensures that the Capsule SDK can properly utilize the necessary Node.js modules in your CRA environment.

You can adjust the polyfill configuration based on your specific needs and the requirements of your project. You’re welcome to use different polyfill packages or modify the fallback settings as needed.

Setting Up the Capsule SDK

Now that you’ve installed the necessary dependencies, let’s set up the Capsule SDK in your CRA project. This involves creating a client instance.

Creating a Capsule Client Instance

You can create the Capsule client instance in a dedicated file, such as clients/capsule.tsx, or as part of your state management logic. Below is a basic example:

clients/capsule.tsx
import Capsule, { Environment } from "@usecapsule/react-sdk";

const capsule = new Capsule(Environment.BETA, process.env.NEXT_PUBLIC_CAPSULE_API_KEY);

export default capsule;

This step initializes the Capsule SDK with your API key and the chosen environment. If successful, you should see the Capsule instance logged in your console (if you choose to console.log it).

Capsule offers two hosted environments: Environment.BETA (alias Environment.DEVELOPMENT) for testing, and Environment.PROD (alias Environment.PRODUCTION) for live use. Select the environment that matches your current development phase.

Integrating the Capsule Modal

Next, integrate the Capsule Modal into your React component by importing the CapsuleModal component from the Capsule SDK, adding a button to trigger the modal, and managing the modal’s state.

import React, { useState } from "react";
import { CapsuleModal } from "@usecapsule/react-sdk";
import capsule from "./clients/capsule"; // Adjust the path to where your capsule instance is located
import "@usecapsule/react-sdk/styles.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Sign in with Capsule</button>
      <CapsuleModal
        capsule={capsule}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </div>
  );
}

export default App;

This creates a button that, when clicked, opens the Capsule Modal for user authentication. The Capsule Modal handles all aspects of user authentication and wallet management.

Beta Testing Credentials In the BETA Environment, you can use any email ending in @test.usecapsule.com (like dev@test.usecapsule.com) or US phone numbers (+1) in the format (area code)-555-xxxx (like (425)-555-1234). Any OTP code will work for verification with these test credentials. These credentials are for beta testing only. You can delete test users anytime in the beta developer console to free up user slots.

Customizing the Capsule Modal

To provide the best experience for your users, you can customize the appearance and behavior of the Capsule Modal to match your application’s branding.

When rendering the CapsuleModal component, you can pass props to customize its appearance and behavior:

<CapsuleModal
  capsule={capsule}
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  appName="Your App Name"
  logo="https://yourapp.com/logo.png"
  theme={{
    backgroundColor: "#ffffff",
    foregroundColor: "#000000",
  }}
  oAuthMethods={["GOOGLE", "TWITTER", "DISCORD"]}
/>

For a full list of available CapsuleModalProps, refer to the customization guide:

Examples

For practical implementation of the Capsule SDK in CRACO applications, explore our example repository. This repository contains real-world examples to help you get started.

Next Steps

After integrating Capsule, you can explore other features and integrations to enhance your Capsule experience. Here are some resources to help you get started:

Ecosystems

Learn how to use Capsule with popular Web3 clients and wallet connectors. We’ll cover integration with key libraries for EVM, Solana, and Cosmos ecosystems.

If you’re ready to go live with your Capsule integration, make sure to review our go-live checklist:

Troubleshooting

If you encounter issues during the integration or usage of the Capsule Modal in a CRACO-based app, here are some common problems and their solutions:

For a more comprehensive list of solutions, visit our troubleshooting guide:

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.