Skip to main content
Integrating Para with Next.js can 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 for the most up-to-date help
  2. Check out the for an interactive LLM using Para Examples Hub

​
General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps: 
rm -rf .next
rm -rf node_modules
npm cache clean --force
bash 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.
import dynamic from "next/dynamic";

const ParaComponent = dynamic(() => import("@getpara/react-sdk@alpha").then((mod) => mod.ParaComponent), {
  ssr: false,
});
Problem: Next.js may not transpile Para packages by default, leading to build errors.Solution: Add Para packages to the transpilePackages configuration in next.config.js:
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: [
    "@getpara/web-sdk@alpha",
    "@getpara/react-sdk@alpha",
    // Add any other Para-related packages here
  ],
  // ... other configurations
};

module.exports = nextConfig;
Problem: Para’s CSS files may not load correctly in Next.js.Solution: Import Para’s CSS file in your _app.js or _app.tsx file:
import "@getpara/react-sdk/dist/index.css@alpha";

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;
Problem: Para API key not being recognized in the application.Solution: Ensure you’re setting the environment variable correctly in your .env.local 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(process.env.NEXT_PUBLIC_PARA_API_KEY);
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:
/** @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;

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