Documentation Index
Fetch the complete documentation index at: https://docs.privy.io/llms.txt
Use this file to discover all available pages before exploring further.
If you’re running into build errors with your framework, check out the following troubleshooting steps:
Gatsby
NextJS
Create React App
Vite
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: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:import React from 'react';
import {PrivyProvider} from '@privy-io/react-auth';
export const wrapPageElement = ({element}) => {
return <PrivyProvider appId={'insert-your-app-id'}>{element}</PrivyProvider>;
};
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 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>;
}
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>
);
}
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.
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
package.json, in your start, build, and test scripts, update react-scripts to react-app-rewired. The “scripts” object should look like the following:{
...,
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-scripts eject"
},
...
}
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: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;
};
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
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()]
});
Solana optional peer dependency build errors
If you encounter a Vite build error like one of the following:"getTransferSolInstruction" is not exported by "__vite-optional-peer-dep:@solana-program/system:..."
Missing "./program-client-core" specifier in "@solana/kit" package
@solana-program/system as a temporary workaround.1. Add an alias to your vite.config.ts
import {fileURLToPath, URL} from 'node:url';
import {defineConfig} from 'vite';
export default defineConfig({
resolve: {
alias: {
'@solana-program/system': fileURLToPath(
new URL('./src/shims/solana-program-system.ts', import.meta.url)
)
}
}
});
2. Add a shim file
// src/shims/solana-program-system.ts
export function getTransferSolInstruction() {
throw new Error(
'@solana-program/system is not installed. Install Solana peer dependencies if you use Solana wallets.'
);
}
Still have questions? Reach out to our support team - we’re here to help! 
