Skip to main content
Integrating Para with Next.js can sometimes present unique challenges. This guide outlines common issues you might encounter and provides effective solutions and best practices to ensure a seamless integration.
Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:
  1. Include the Para LLM-optimized context file for the most up-to-date help
  2. Check out the Example Hub Wiki for an interactive LLM using Para Examples Hub

​
General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:
If you encounter unexpected behavior, clearing the cache and reinstalling dependencies can often resolve issues. Adjust the commands based on your package manager:
rm -rf .next
rm -rf node_modules
npm cache clean --force
After clearing the cache, reinstall your dependencies to ensure everything is up-to-date:
npm install

​
Common Issues and Solutions

Problem: Para is a client-side library and may cause issues with Server-Side Rendering (SSR) in Next.js.Solution: Use dynamic imports to load Para components only on the client side.In older versions of Next.js, you might need to use the next/dynamic import with ssr: false:
import dynamic from "next/dynamic";

const ParaComponent = dynamic(() => import("@getpara/react-sdk").then((mod) => mod.ParaComponent), {
  ssr: false,
});
Adjust ParaComponent to the specific component you are using, such as ParaModal or ParaProvider.In newer versions of Next.js, you can use the use client directive at the top of your component file to ensure it runs only on the client side:
"use client";
import React, { useState } from "react";
import { ParaModal } from "@getpara/react-sdk";

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

return (
  <>
    <button onClick={() => setIsOpen(true)}>Sign in with Para</button>
    <ParaModal
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
    />
  </>
);
Problem: Depending on your build configuration, you may encounter issues with CJS or ESM modules resolution for Para packages or related dependencies.Solution: Add Para packages to the transpilePackages configuration in next.config.js. This ensures that Next.js transpiles these packages correctly, especially if they are using modern JavaScript features not supported by your target browsers.
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: [
    "@getpara/web-sdk",
    "@getpara/react-sdk",
    // Add any other Para-related packages here
  ],
  // ... The rest of your Next.js configuration
};

module.exports = nextConfig;
Problem: ParaModal not displaying correctly and showing transparent background with no styles applied.Solution: Import Para’s CSS file in your application entry point or wherever you manage global styles. This is crucial for the proper styling of Para components.
import "@getpara/react-sdk/dist/index.css";
Problem: Para API key not being recognized in the application.Solution: Ensure you’re setting the environment variable correctly in your .env.* file and prefixing it with NEXT_PUBLIC_ for client-side access:
NEXT_PUBLIC_PARA_API_KEY=your_api_key_here
Then, use it in your code like this:
const para = new Para(Environment.BETA, process.env.NEXT_PUBLIC_PARA_API_KEY);
Ensure that the Environment is set correctly based on your Para environment (e.g., Environment.BETA).
Problem: Errors related to missing Node.js modules like crypto or buffer.Solution: While not always necessary for Next.js, you may need to add polyfills. Update your next.config.js:Install the necessary polyfills if you haven’t already:
npm install crypto-browserify stream-browserify buffer
Then, modify your next.config.js to include these polyfills:
/** @type {import('next').NextConfig} */
const nextConfig = {
  // ... other configs
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        crypto: require.resolve("crypto-browserify"),
        stream: require.resolve("stream-browserify"),
        buffer: require.resolve("buffer"),
      };
    }
    return config;
  },
};

module.exports = nextConfig;
Adding these polyfills ensures that the necessary Node modules are available in the browser environment, which is crucial for Para’s functionality.
Problem: If using SSR in Next.js, you might encounter issues with styled-components when integrating Para. Common errors include styled.div not being recognized.Solution: Ensure proper client side only rendering of Para components. See the solution for SSR compatibility issues above.
Problem: You’re unable to complete the authentication flow with ParaModal. Solution: Ensure that the ParaModal props have all the required fields for the authentication options you want to use. Also ensure that your Para API key and environment are correctly set up in your .env file. Lastly check your developer portal settings to ensure that you haven’t reached your API user limit or that your API key is not expired.

​
Best Practices

  1. Use the Latest Versions: Always use the latest versions of Next.js and Para SDK to ensure compatibility and access to the latest features.
  2. Client-Side Rendering for Para Components: Whenever possible, render Para components on the client-side to avoid SSR-related issues.
  3. Error Boundary: Implement error boundaries to gracefully handle any runtime errors related to Para integration.
  4. Environment-Specific Configurations: Use Next.js environment configurations to manage different settings for development and production environments.
  5. Lazy Loading: Consider using lazy loading in combination with dynamic imports to improve performance and reduce initial load times.
By following these troubleshooting steps and best practices, you should be able to resolve most common issues when integrating Para with your Next.js application.

​
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.
⌘I