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

# TanStack Start Troubleshooting

> Overcoming Para integration challenges in TanStack Start 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>;
};

TanStack Start's server-side rendering (SSR) capabilities can introduce unique challenges when integrating Para SDK. This guide addresses frequent issues and offers tailored solutions to ensure a successful implementation.

<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 node_modules
    npm cache clean --force
    ```
  </Accordion>

  <Accordion title="Reinstall dependencies">
    ```bash theme={null}
    npm install
    ```
  </Accordion>

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

  <Accordion title="Rebuild the project">
    ```bash theme={null}
    npm run build
    ```
  </Accordion>
</AccordionGroup>

## Common Issues and Solutions

<AccordionGroup>
  <Accordion title="Environment Variables Not Properly Configured">
    **Problem**: Para API key environment variables not being recognized in your application.

    **Solution**: Ensure you're using the correct prefix for environment variables in TanStack Start and accessing them properly:

    1. In your `.env` file:
       ```
       VITE_PARA_API_KEY=your_api_key_here
       VITE_PARA_ENVIRONMENT=BETA
       ```

    2. In your constants file:
       ```javascript theme={null}
       // src/constants.ts
       export const API_KEY = import.meta.env.VITE_PARA_API_KEY || "";
       export const ENVIRONMENT = import.meta.env.VITE_PARA_ENVIRONMENT || "BETA";
       ```

    3. When using these in your ParaProvider:
       ```jsx theme={null}
       <LazyParaProvider paraClientConfig={{ apiKey: API_KEY, env: ENVIRONMENT }}>
         {children}
       </LazyParaProvider>
       ```
  </Accordion>

  <Accordion title="Node.js Polyfills Missing or Misconfigured">
    **Problem**: Missing or improperly configured Node.js polyfills causing errors like `crypto is not defined` or similar issues.

    **Solution**: Configure the polyfills specifically for the client bundle only:

    1. Install the plugin:
       ```bash theme={null}
       npm install --save-dev vite-plugin-node-polyfills
       ```

    2. Update your `app.config.ts` to apply polyfills only to the client bundle:
       ```typescript theme={null}
       import { defineConfig } from "@tanstack/react-start/config";
       import tsConfigPaths from "vite-tsconfig-paths";
       import { nodePolyfills } from "vite-plugin-node-polyfills";

       export default defineConfig({
         tsr: { appDirectory: "src" },

         // Base configuration (applied to both client and server)
         vite: {
           plugins: [tsConfigPaths({ projects: ["./tsconfig.json"] })],
           define: {
             // This helps modules determine the execution environment
             "process.browser": true,
           },
         },

         // Client-specific configuration
         routers: {
           client: {
             vite: {
               // Apply node polyfills ONLY on the client side
               plugins: [nodePolyfills()],
             },
           },
         },
       });
       ```

    **Important**: Do NOT configure nodePolyfills in the top-level vite plugins array, as this will apply the polyfills to the server bundle and can cause conflicts.
  </Accordion>

  <Accordion title="Missing process.browser Configuration">
    **Problem**: Browser-specific modules not being resolved correctly, leading to missing APIs or incorrect environment detection.

    **Solution**: Add the `process.browser` definition to help modules determine the execution environment:

    ```typescript theme={null}
    // app.config.ts
    export default defineConfig({
      vite: {
        define: {
          "process.browser": true,
        },
        // other configurations...
      },
      // other configurations...
    });
    ```

    This setting is critical for ensuring that browser-specific code paths are correctly resolved during bundling.
  </Accordion>

  <Accordion title="Styled-Components Errors During Server Rendering">
    **Problem**: Errors like `styled.div is not a function` or `Cannot read properties of undefined (reading 'div')` during server rendering.

    **Solution**: Ensure Para components are only rendered on the client side by using both `React.lazy` for dynamic imports and `ClientOnly` from TanStack Router:

    ```jsx theme={null}
    import React from "react";
    import { ClientOnly } from "@tanstack/react-router";

    // Lazy load Para component to prevent server-side evaluation
    const LazyParaProvider = React.lazy(() =>
      import("@getpara/react-sdk").then((mod) => ({
        default: mod.ParaProvider
      }))
    );

    export function Providers({ children }) {
      return (
        <ClientOnly fallback={null}>
          <QueryClientProvider client={queryClient}>
            <LazyParaProvider paraClientConfig={{ apiKey: API_KEY, env: ENVIRONMENT }}>
              {children}
            </LazyParaProvider>
          </QueryClientProvider>
        </ClientOnly>
      );
    }
    ```

    The combination of `React.lazy` and `ClientOnly` ensures that Para components are not only rendered on the client side but also that the modules are not evaluated on the server.
  </Accordion>

  <Accordion title="Styled-Components Issues Despite ClientOnly Usage">
    **Problem**: Even with `ClientOnly`, you're still seeing styled-components errors during server rendering.

    **Solution**: Module-level evaluation can still happen on the server even if the component isn't rendered. Make sure all Para imports are lazy loaded:

    1. Don't import directly from Para SDK at the module level:
       ```jsx theme={null}
       // AVOID this at the top level:
       import { useModal } from "@getpara/react-sdk";
       ```

    2. Instead, create wrapper components for all Para components:
       ```jsx theme={null}
       // Create a component file like ParaContainer.tsx
       export function ParaContainer() {
         // Import and use Para components here
         const { openModal } = useModal();
         return (
           <>
             <button onClick={() => openModal()}>Open Para Modal</button>
           </>
         );
       }
       ```

    3. Then lazy load these wrapper components:
       ```jsx theme={null}
       const LazyParaContainer = React.lazy(() =>
         import("~/components/ParaContainer").then((mod) => ({
           default: mod.ParaContainer,
         }))
       );

       function HomePage() {
         return (
           <ClientOnly fallback={<p>Loading...</p>}>
             <LazyParaContainer />
           </ClientOnly>
         );
       }
       ```
  </Accordion>

  <Accordion title="CSS Styling Issues or Transparent Modal">
    **Problem**: The Para modal appears transparent or without proper styling.

    **Solution**: Import Para's CSS file in your component:

    ```jsx theme={null}
    // In your main component or route file:
    import "@getpara/react-sdk/styles.css";

    // Then use Para components as usual
    ```

    Ensure this import is included in the component that uses Para components or in a parent component that wraps them.
  </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="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 for TanStack Start Integration

1. **Client-Side Only Rendering**: Always use both `React.lazy` and `ClientOnly` for Para components to avoid SSR issues.

2. **Polyfill Strategy**: Configure node polyfills only for the client bundle using the `routers.client.vite.plugins` config.

3. **Environment Awareness**: Set `process.browser` to true to help modules determine the execution environment.

4. **Component Boundaries**: Clearly define boundaries between server and client components to prevent hydration mismatches.

5. **Error Handling**: Implement error boundaries to gracefully handle any runtime errors related to Para integration.

6. **Development vs Production**: Use environment-specific configurations to manage different settings for development and production builds.

By following these troubleshooting steps and best practices, you should be able to resolve most common issues when integrating Para with your TanStack Start 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.