Next.js

This guide will walk you through the process of integrating the Para 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 Para Modal setup: Para Next.js Starter.

​

Prerequisites

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

​

Installing Dependencies

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

First, install the Para 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 @getpara/*).

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

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

module.exports = nextConfig;

​

Setting Up the Para SDK

Now that you’ve installed the necessary dependencies, let’s set up the Para 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 Para Client Instance

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

import Para, { Environment } from "@getpara/react-sdk";

const para = new Para(Environment.BETA, process.env.NEXT_PUBLIC_PARA_API_KEY);

export default para;

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

​

Integrating the Para 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 ParaModal 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 para from "../clients/para"; // or wherever your para instance is exported
import "@getpara/react-sdk/styles.css";

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

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

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Sign in with Para</button>
      <ParaModal
        para={para}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </div>
  );
}

export default HomePage;

​

Option 2: "use client"

"use client";
import React, { useState } from "react";
import { ParaModal } from "@getpara/react-sdk";
import para from "../clients/para";
import "@getpara/react-sdk/styles.css";

export default function HomePage() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Sign in with Para</button>
      <ParaModal
        para={para}
        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 Para Modal

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

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

<ParaModal
  para={para}
  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 ParaModalProps, refer to the customization guide:

​

Examples

For practical implementation of the Para SDK in Next.js applications, explore our example repository. This repository contains a walkthrough application demonstrating usage of all Para features, including the Para Modal. Use the Readme.md file to get started:

​

Next Steps

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

​

Ecosystems

Learn how to use Para 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 Para integration, make sure to review our go-live checklist:

​

Troubleshooting

If you encounter issues during the integration or usage of the Para 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.