Common framework errors

If you’re running into build errors with your framework, check out the following troubleshooting steps:

If you’re using a framework like Gatsby and are running into build errors, check out some common errors below, and how to resolve them.

iframe not initialized

If you encounter an error like the one below:

iframe not initialized

There is likely an issue with how you are rendering the PrivyProvider component within your app.

Namely, if you are using Gatsby’s wrapRootElement to wrap your app with the PrivyProvider, you should use wrapPageElement instead, like below:

gatsby-browser.tsx
import React from 'react';

import {PrivyProvider} from '@privy-io/react-auth';

export const wrapPageElement = ({element}) => {
  return <PrivyProvider appId={'insert-your-app-id'}>{element}</PrivyProvider>;
};

Though Gatsby typically recommends using wrapRootElement for React Contexts, the PrivyProvider component contains UI (HTML) elements as well, including a dialog (the Privy modal) and an iframe (the Privy iframe, used for embedded wallets). Given these UI elements, wrapPageElement must be used instead of wrapRootElement.

Still have questions? Reach out to our support team – we’re here to help!

If you’re using a framework like Gatsby and are running into build errors, check out some common errors below, and how to resolve them.

iframe not initialized

If you encounter an error like the one below:

iframe not initialized

There is likely an issue with how you are rendering the PrivyProvider component within your app.

Namely, if you are using Gatsby’s wrapRootElement to wrap your app with the PrivyProvider, you should use wrapPageElement instead, like below:

gatsby-browser.tsx
import React from 'react';

import {PrivyProvider} from '@privy-io/react-auth';

export const wrapPageElement = ({element}) => {
  return <PrivyProvider appId={'insert-your-app-id'}>{element}</PrivyProvider>;
};

Still have questions? Reach out to our support team – we’re here to help!

If you’re using a framework like NextJS and are running into build errors, check out some common errors below, and how to resolve them.

App router

If you are using the new app router, you may encounter issues when attempting to wrap your app with the PrivyProvider. If so, follow the instructions below to set up your app with Privy:

1. Create a wrapper component for the `PrivyProvider`

Since the PrivyProvider is a third-party React Context, it can only be used client-side, with the 'use client'; directive. Check out these docs from NextJS for more information.

First, create a new component file and add 'use client'; as the first line. Then, within this same file, create a custom component (e.g. Providers) that accepts React children as props, and renders these children, wrapped by the PrivyProvider:

// components/providers.tsx
'use client';

import {PrivyProvider} from '@privy-io/react-auth';

export default function Providers({children}: {children: React.ReactNode}) {
  return <PrivyProvider appId="insert-your-privy-app-id">{children}</PrivyProvider>;
}

This wrapper component ensures that the PrivyProvider is only ever rendered client-side, as required by NextJS.

2. Wrap your app with the providers component in your `RootLayout`

Next, in your app’s Root Layout, wrap the layout’s children with your providers component, like so:

import Providers from '../components/providers';

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

Within your RootLayout, make sure you are using the wrapper component you created in step (1), not the raw PrivyProvider exported by the SDK.

That’s it! You can check out a complete example of Privy integrated into a NextJS app using the App Router here.

Still have questions? Reach out to our support team – we’re here to help!

If you’re using a framework like Create React App and are running into build errors, check out some common errors and how to resolve them.

Missing Polyfills (Webpack 5)

Since Create React App uses Webpack 5, you may encounter errors like the one below:

BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

This is because many standard web3 libraries, such as ethers.js, have dependencies that need to be polyfilled into your build environment. Webpack 5 no longer automatically handles these polyfills, which triggers this error.

You can work past these issues by explicitly adding in these dependencies and overriding some configurations, as outlined below:

1. Install dependencies

Run the following command in your project to install the necessary dependencies:

npm i --save-dev react-app-rewired assert buffer process stream-browserify url

2. Configure your project with `react-app-rewired`

In your package.json, in your start, build, and test scripts, update react-scripts to react-app-rewired. The “scripts” object should look like the following:

package.json
{
    ...,
    "scripts": {
        "start": "react-app-rewired start",
        "build": "react-app-rewired build",
        "test": "react-app-rewired test",
        "eject": "react-scripts eject"
    },
    ...
}

This allows you to bypass the default webpack configurations from create-react-app.

3. Add `config-overrides.js` to your project

Lastly, at the root of your project, create a file called config-overrides.js and paste in the following:

config-overrides.js
const webpack = require('webpack');
module.exports = function override(config) {
  config.resolve.fallback = {
    assert: require.resolve('assert'),
    buffer: require.resolve('buffer'),
    'process/browser': require.resolve('process/browser'),
    stream: require.resolve('stream-browserify'),
    url: require.resolve('url'),
    http: false,
    https: false,
    os: false
  };
  config.plugins.push(
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer']
    })
  );
  config.ignoreWarnings = [/Failed to parse source map/];
  return config;
};

This tells your browser where to look for the dependencies that you’ve now added.

That’s it!

Still have questions? Reach out to our support team – we’re here to help!

If you’re using a framework like Vite and are running into build errors, check out some common errors below, and how to resolve them.

`process` is not defined

If you encounter an error like the one below:

Uncaught (in promise) ReferenceError: process is not defined at ../../../node_modules/@coinbase/wallet-sdk/dist/CoinbaseWalletSDK.js

This is due to an issue in one of Privy’s necessary dependencies, the Coinbase Wallet SDK. You can read more about the issue here.

To resolve the issue, we recommend using the vite-plugin-node-polyfills package, which will polyfill the process dependency that Coinbase requires.

1. Install `vite-plugin-node-polyfills`

First, install vite-plugin-node-polyfills as a dev dependency:

npm i --save-dev vite-plugin-node-polyfills

2. Update your `vite.config.ts`

Then, update your vite.config.ts file to include the following to use the plugin:

import {defineConfig} from 'vite';
import {nodePolyfills} from 'vite-plugin-node-polyfills';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [nodePolyfills()]
});

That’s it!

Still have questions? Reach out to our support team - we’re here to help!

Get started

Get started by SDK

Changelogs

Troubleshooting and tips

Common framework errors

iframe not initialized

iframe not initialized

App router

1. Create a wrapper component for the `PrivyProvider`

2. Wrap your app with the providers component in your `RootLayout`

Missing Polyfills (Webpack 5)

1. Install dependencies

2. Configure your project with `react-app-rewired`

3. Add `config-overrides.js` to your project

`process` is not defined

1. Install `vite-plugin-node-polyfills`

2. Update your `vite.config.ts`

Get started

Get started by SDK

Changelogs

Troubleshooting and tips

​iframe not initialized

​iframe not initialized

​App router

​1. Create a wrapper component for the PrivyProvider

​2. Wrap your app with the providers component in your RootLayout

​Missing Polyfills (Webpack 5)

​1. Install dependencies

​2. Configure your project with react-app-rewired

​3. Add config-overrides.js to your project

​process is not defined

​1. Install vite-plugin-node-polyfills

​2. Update your vite.config.ts

iframe not initialized

iframe not initialized

App router

1. Create a wrapper component for the `PrivyProvider`

2. Wrap your app with the providers component in your `RootLayout`

Missing Polyfills (Webpack 5)

1. Install dependencies

2. Configure your project with `react-app-rewired`

3. Add `config-overrides.js` to your project

`process` is not defined

1. Install `vite-plugin-node-polyfills`

2. Update your `vite.config.ts`