Skip to main content
This guide will walk you through the process of integrating the ParaProvider with the ParaModal 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.

​
Prerequisites

To use Para, you need an API key. This key authenticates your requests to Para 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

npm install @getpara/react-sdk @tanstack/react-query
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;
This will ensure that the Para SDK is properly transpiled for your CJS or ESM build configuration.

​
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 using the recommended ParaProvider approach.

​
Create a Providers Component

First, create a Providers component that will wrap your application with both the QueryClientProvider (required for Para) and the ParaProvider:
providers.tsx
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Environment, ParaProvider } from "@getpara/react-sdk";
import "@getpara/react-sdk/styles.css";

const queryClient = new QueryClient();

export function Providers({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <QueryClientProvider client={queryClient}>
      <ParaProvider
        paraClientConfig={{
          apiKey: process.env.NEXT_PUBLIC_PARA_API_KEY || "",
          env: Environment.BETA,
        }}>
        {children}
      </ParaProvider>
    </QueryClientProvider>
  );
}
Para 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.
The ParaProvider and the ParaModal are client side only components. Use the "use client" directive at the top of your file to ensure that this component is rendered on the client side. If using an older version of Next.js use the next/dynamic import to dynamically import the Providers component with ssr: false.

​
Wrap Your App with Providers

Next, wrap your root layout with the Providers component. This is typically done in the app/layout.tsx file in a Next.js app using the App Router or if using the Pages Router, in the _app.tsx file.
layout.tsx
import { Providers } from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

​
Add the Para Modal

Now you can include the ParaModal component in any client component within your application and use the ParaProvider hooks to control it: 
"use client";

import { ParaModal, useModal } from "@getpara/react-sdk";

export function ParaButton() {
  const { openModal } = useModal();

  return (
    <>
      <button onClick={() => openModal()}>
        Sign in with Para
      </button>

      <ParaModal
        appName="Your App Name"
        logo="/para.svg"
      />
    </>
  );
}
The ParaModal will automatically connect to the ParaProvider context, so you don’t need to pass any additional props for functionality. You only need to customize its appearance.
Beta Testing Credentials In the BETA Environment, you can use any email ending in @test.getpara.com (like dev@test.getpara.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 Para Modal

To provide the best experience for your users, you can customize the appearance of the Para Modal to match your application’s branding. When rendering the ParaModal component, you can pass props to customize its appearance: 
<ParaModal
  appName="Your App Name"
  logo="/logo.png"
  theme={{ backgroundColor: "#ffffff", foregroundColor: "#000000" }}
  oAuthMethods={["GOOGLE", "TWITTER", "DISCORD"]}
/>
For a full list of available ParaModalProps, refer to the customization guide:
Customizing the Para Modal

Customizing the Para Modal

Customizing the Para Modal, including advanced theming options, branding configurations, and more.

​
Alternative Approach: Standalone Para Modal

While the ParaProvider approach is recommended, you can also use the ParaModal as a standalone component. This approach requires you to create and manage a Para client instance manually.

​
Creating a Para Client Instance

You can create the Para client instance in a dedicated file:
import Para, { Environment } from "@getpara/react-sdk";

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

export default para;

​
Integrating the Standalone Para Modal

Because Next.js supports server-side rendering (SSR), you need to ensure the modal runs on the client side:
"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>
  );
}

​
Examples

For practical implementation of the Para SDK in Next.js applications, explore our Examples Hub repository. It contains a variety of examples showcasing how to integrate the Para SDK with different Para configurations and use cases.
React NextJS Examples

React NextJS Examples

Explore our examples hub repository for practical implementations of the Para SDK in Next.js applications.

​
Troubleshooting

If you encounter issues during the integration or usage of the Para Modal in Next.js applications, refer to our Next.js troubleshooting guide. It provides solutions to common problems and helps you resolve any issues you may face.
Troubleshooting

Troubleshooting

Our troubleshooting guide provides solutions to common integration and usage problems.

​
Next Steps

After integrating Para, you can explore other features and integrations to enhance your Para experience.
EVM Integration

EVM Integration

Learn how to use Para with EVM-compatible libraries like ethers.js, viem, and wagmi.
Solana Integration

Solana Integration

Discover how to integrate Para with solana-web3.js.
Cosmos Integration

Cosmos Integration

Explore Para integration with Cosmos ecosystem using CosmJS, Cosmos Kit, and Graz.
⌘I