Next.js

This guide will walk you through the process of integrating the Capsule Modal into your Next.js application, providing a seamless way to manage user authentication and wallets.

If you haven’t already set up your Next.js app, you can get started by creating a new project via the Next.js official docs. Alternatively, you can fork our minimal starter that already includes the Capsule Modal setup: Capsule Next.js Starter.

​

Prerequisites

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

​

Installing Dependencies

In this section, you’ll install the Capsule React SDK, which is the core dependency needed to integrate Capsule into your Next.js application.

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

​

(Optional) Adding Transpile Configuration

Depending on your Next.js version or your build/TypeScript settings, you may want or need to transpile external modules (like @usecapsule/*).

In your next.config.js, enable the transpilation:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ["@usecapsule/react-sdk", "@usecapsule/*"],
};

module.exports = nextConfig;

​

Setting Up the Capsule SDK

Now that you’ve installed the necessary dependencies, let’s set up the Capsule SDK in your Next.js project. This involves creating a client instance and optionally configuring Next.js to transpile external modules if needed.

​

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:

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).

​

Integrating the Capsule Modal (SSR Considerations)

Because Next.js supports server-side rendering (SSR), you have two options to ensure the modal runs on the client side:

1. Dynamic Import — dynamically import the CapsuleModal so that it’s only rendered client-side.
2. "use client" Directive — on newer versions of Next.js, you can add "use client" at the top of a component file to mark the entire component as client-only.

​

Option 1: Dynamic Import

import React, { useState } from "react";
import dynamic from "next/dynamic";
import capsule from "../clients/capsule"; // or wherever your capsule instance is exported
import "@usecapsule/react-sdk/styles.css";

// Dynamically import the CapsuleModal to avoid SSR issues
const CapsuleModal = dynamic(
  () => import("@usecapsule/react-sdk").then((mod) => mod.CapsuleModal),
  { ssr: false }
);

function HomePage() {
  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 HomePage;

​

Option 2: "use client"

"use client";
import React, { useState } from "react";
import { CapsuleModal } from "@usecapsule/react-sdk";
import capsule from "../clients/capsule"; 
import "@usecapsule/react-sdk/styles.css";

export default function HomePage() {
  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>
  );
}

Using the "use client" directive at the top of your file tells Next.js that this component should render purely on the client side, making dynamic imports unnecessary.

​

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 Next.js applications, explore our example repository. This repository contains a walkthrough application demonstrating usage of all Capsule features, including the Capsule Modal. Use the Readme.md file to 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 Next.js, 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.