> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Troubleshooting Para integration with Next.js applications

export const Link = ({href, label, newTab = false}) => {
  const [isHovered, setIsHovered] = useState(false);
  return <a href={href} target={newTab ? '_blank' : '_self'} rel={newTab ? 'noopener noreferrer' : undefined} className="not-prose inline-block relative text-black font-semibold cursor-pointer border-b-0 no-underline" onMouseEnter={() => setIsHovered(true)} onMouseLeave={() => setIsHovered(false)}>
      {label}
      <span className={`absolute left-0 bottom-0 w-full rounded-sm bg-gradient-to-r from-orange-600 to-purple-600 transition-all duration-300 ${isHovered ? 'h-0.5' : 'h-px'}`} />
    </a>;
};

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.

<Tip>
  Using an LLM (ChatGPT, Claude) or Coding Assistant (Cursor, Github Copilot)? Here are a few tips:

  1. Include the <Link label="Para LLM-optimized context file" href="https://docs.getpara.com/llms-full.txt" /> for the most up-to-date help
  2. Check out the <Link label="Example Hub Wiki" href="https://deepwiki.com/getpara/examples-hub" /> for an interactive LLM using Para Examples Hub
</Tip>

## General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:

<AccordionGroup>
  <Accordion title="Clear cache and node_modules">
    ```bash theme={null}
    rm -rf .next
    rm -rf node_modules
    npm cache clean --force
    ```
  </Accordion>

  <Accordion title="Reinstall dependencies">`bash npm install `</Accordion>

  <Accordion title="Update Para-related packages">
    ```bash theme={null}
    npm update @getpara/web-sdk @getpara/react-sdk
    ```
  </Accordion>
</AccordionGroup>

## Common Issues and Solutions

<AccordionGroup>
  <Accordion title="SSR Compatibility Issues">
    **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.

    ```jsx theme={null}
    import dynamic from "next/dynamic";

    const ParaComponent = dynamic(() => import("@getpara/react-sdk").then((mod) => mod.ParaComponent), {
      ssr: false,
    });
    ```
  </Accordion>

  <Accordion title="Transpilation Errors">
    **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`:

    ```javascript theme={null}
    /** @type {import('next').NextConfig} */
    const nextConfig = {
      transpilePackages: [
        "@getpara/web-sdk",
        "@getpara/react-sdk",
        // Add any other Para-related packages here
      ],
      // ... other configurations
    };

    module.exports = nextConfig;
    ```
  </Accordion>

  <Accordion title="CSS Loading Issues">
    **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:

    ```jsx theme={null}
    import "@getpara/react-sdk/styles.css";

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

    export default MyApp;
    ```
  </Accordion>

  <Accordion title="Environment Variable Configuration">
    **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:

    ```javascript theme={null}
    const para = new Para(process.env.NEXT_PUBLIC_PARA_API_KEY);
    ```
  </Accordion>

  <Accordion title="Duplicate ParaModal Instances">
    **Problem**: Your app renders `<ParaProvider>` and also renders a separate `<ParaModal />`. `ParaProvider` includes its own embedded modal by default, so the two modal instances can compete for the same Para state and cause inconsistent open, close, or authentication behavior.

    **Solution**: Prefer the embedded modal and remove the separate `<ParaModal />`. Pass modal options to `ParaProvider` with `paraModalConfig`:

    ```tsx theme={null}
    <ParaProvider
      paraClientConfig={{ apiKey: "YOUR_API_KEY" }}
      config={{ appName: "YOUR_APP_NAME" }}
      paraModalConfig={modalOptions}
    >
      <YourApp />
    </ParaProvider>
    ```

    If you intentionally render your own `<ParaModal />`, disable the provider's embedded modal:

    ```tsx theme={null}
    <ParaProvider
      paraClientConfig={{ apiKey: "YOUR_API_KEY" }}
      config={{
        appName: "YOUR_APP_NAME",
        disableEmbeddedModal: true,
      }}
    >
      <YourApp />
      <ParaModal {...modalOptions} />
    </ParaProvider>
    ```

    <Warning>
      Do not render a separate `<ParaModal />` while `ParaProvider` has its embedded modal enabled. Run `para doctor` to detect this setup automatically.
    </Warning>
  </Accordion>

  <Accordion title="Build-time Errors with Node.js Modules">
    **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`:

    ```javascript theme={null}
    /** @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;
    ```
  </Accordion>

  <Accordion title="Wagmi v3 Module Resolution Errors">
    **Problem**: After upgrading from wagmi v2 to v3, you encounter module resolution errors or missing dependency warnings.

    **Solution**: Wagmi v3 requires additional peer dependencies that are not included in the default installation. Install them:

    ```bash theme={null}
    npm install porto @base-org/account @gemini-wallet/core @metamask/sdk @safe-global/safe-apps-provider @safe-global/safe-apps-sdk
    ```

    <Note>
      The default Para SDK installation uses wagmi v2. These additional dependencies are only needed if you choose to upgrade to wagmi v3.
    </Note>
  </Accordion>
</AccordionGroup>

### 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](https://join.slack.com/t/para-community/shared_invite/zt-304keeulc-Oqs4eusCUAJEpE9DBwAqrg) for
assistance. To help us resolve your issue quickly, please include the following information in your request:

<ol className="space-y-4 list-none pl-0">
  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      1
    </span>

    <p className="flex-1 my-0">A detailed description of the problem you're encountering.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      2
    </span>

    <p className="flex-1 my-0">Any relevant error messages or logs.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      3
    </span>

    <p className="flex-1 my-0">Steps to reproduce the issue.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      4
    </span>

    <p className="flex-1 my-0">Details about your system or environment (e.g., device, operating system, software version).</p>
  </li>
</ol>

Providing this information will enable our team to address your concerns more efficiently.