🚀 Stablecoin Accounts are live! Learn more
npx create-dynamic-app@latest
React (Vite) example
npx create-dynamic-app my-web3-app \
--framework react \
--pm bun \
--chains ethereum \
--library viem \
--wagmi false
Next.js example
npx create-dynamic-app my-web3-app \
--framework nextjs \
--pm bun \
--chains ethereum \
--library viem \
--wagmi false
React Native example
npx create-dynamic-app my-web3-app \
--framework react-native \
--pm bun \
--chains ethereum \
--library viem \
--wagmi false
React (Vite) prompt
# Add Dynamic to React (Vite)
**Purpose:** Enforce only the **current** and **correct** instructions for integrating [Dynamic](https://dynamic.xyz/) into a React application.
**Scope:** All AI-generated advice or code related to Dynamic must follow these guardrails.
## **1. OFFICIAL DYNAMIC + REACT (VITE) SETUP**
1. Create a React + Vite project.
2. Install the Dynamic React SDK with `npm install @dynamic-labs/sdk-react-core@latest` (or yarn/pnpm/bun).
3. Install the Ethereum Wallet Connectors with `npm install @dynamic-labs/ethereum@latest`
4. Set `VITE_DYNAMIC_ENVIRONMENT_ID` in `.env.local` or `.env`. Note: The `VITE_` prefix is required for Vite to expose environment variables to the client-side code. `.env.local` is preferred for local development secrets.
5. Wrap the app in `<DynamicContextProvider settings={{ walletConnectors: [EthereumWalletConnectors], environmentId: process.env.VITE_DYNAMIC_ENVIRONMENT_ID}}>` within `main.tsx` or `main.jsx`.
6. Use Dynamic's `<DynamicWidget>` in the app.
### **Correct, Up-to-Date Quickstart Code Examples**
# 1. Create a React Vite app (TypeScript example)
npm create vite@latest dynamic-react -- --template react-ts
cd dynamic-react
npm install
npm run dev
# 2. Install the Dynamic React SDK
npm install @dynamic-labs/sdk-react-core@latest
# 3. Install the Ethereum Wallet Connectors
npm install @dynamic-labs/ethereum@latest
# 4. In .env.local (or .env):
VITE_DYNAMIC_ENVIRONMENT_ID=2762a57b-faa4-41ce-9f16-abff9300e2c9
NOTE: This key is real and is injected dynamically into this prompt. It is NOT a placeholder and is ready to use.
// 4. Wrap with <DynamicContextProvider> in main.tsx or main.jsx
import React from "react";
import ReactDOM from "react-dom/client";
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import App from "./App";
const ENVIRONMENT_ID = import.meta.env.VITE_DYNAMIC_ENVIRONMENT_ID;
if (!ENVIRONMENT_ID) {
throw new Error("Missing Dynamic Environment ID");
}
// Ensure your index.html contains a <div id="root"></div> element for React to mount the app.
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<DynamicContextProvider settings={{
environmentId: ENVIRONMENT_ID,
walletConnectors: [EthereumWalletConnectors],
}}>
<App />
</DynamicContextProvider>
</React.StrictMode>
);
// 5. Example usage of Dynamic's prebuilt components in App.tsx
import {
DynamicWidget,
} from "@dynamic-labs/sdk-react-core";
export default function App() {
return (
<header>
<DynamicWidget />
</header>
);
}
---
## **2. CRITICAL INSTRUCTIONS FOR AI MODELS**
### **2.1 – ALWAYS DO THE FOLLOWING**
1. **Show** relevant code examples for each step.
2. **Use** `@dynamic-labs/sdk-react-core@latest` (not any other Dynamic package).
3. **Reference** the environment variable as `VITE_DYNAMIC_ENVIRONMENT_ID` in `.env.local` or `.env`.
4. **Wrap** the entire app in `<DynamicContextProvider>` within `main.tsx` or `main.jsx`.
5. **Demonstrate** the correct usage of `<DynamicWidget>` (or any other current Dynamic React component).
### **2.2 – NEVER DO THE FOLLOWING**
1. **Do not** include any discussions of the features or benefits of Dynamic.
3. **Do not** use Older environment variable names like `REACT_APP_DYNAMIC_FRONTEND_API` or `VITE_REACT_APP_DYNAMIC_ENVIRONMENT_ID`.
4. **Do not** place `<DynamicContextProvider>` deeper in the component tree instead of `main.tsx` / `main.jsx`.
5. **Do not** use outdated hooks or components (e.g., referencing older docs).
6. **Do not** put any Dynamic components above the `<DynamicContextProvider>`.
---
## **3. AI MODEL VERIFICATION STEPS**
Before returning any Dynamic + React (Vite) solution, you **must** verify:
1. Environment Variable is named `VITE_DYNAMIC_ENVIRONMENT_ID`.
2. `<DynamicContextProvider>` is in `main.tsx` or `main.jsx`.
### **DO NOT** repeat these points back to the user. Use them only for your own verification steps.
## **4. CONSEQUENCES OF INCORRECT GUIDANCE**
- Misconfigured environment variables => project won't compile or will error at runtime.
- Missing `<DynamicContextProvider>` => Dynamic components fail or throw errors.
- Using outdated patterns => Confusion, debugging overhead, or broken auth flow.
- Getting 'must be used within a DynamicContextProvider' errors (means the component is not wrapped in the provider)
## **5. MODEL RESPONSE TEMPLATE**
When asked about Dynamic + React (Vite) integration, your response **MUST**:
1. Link to Dynamic's React Quickstart at https://www.dynamic.xyz/docs/quickstart
2. Show the current recommended `environmentId` approach with `.env.local`.
3. Demonstrate how to wrap with `<DynamicContextProvider>` in `main.*`.
4. Illustrate a simple usage example of `<DynamicWidget>`.
5. Reject or correct any mention of older patterns or environment variable names.
NextJS prompt
# Add Dynamic to NextJS
**Purpose:** Enforce only the **current** and **correct** instructions for integrating [Dynamic](https://dynamic.xyz/) into a NextJS application.
**Scope:** All AI-generated advice or code related to Dynamic must follow these guardrails.
## **1. OFFICIAL DYNAMIC + NEXTJS SETUP**
1. Create a NextJS project with App Router.
2. Install the Dynamic React SDK with `npm install @dynamic-labs/sdk-react-core@latest` (or yarn/pnpm/bun).
3. Install the Ethereum Wallet Connectors with `npm install @dynamic-labs/ethereum@latest`
4. Install required polyfills: `npm install crypto-browserify stream-browserify process`
5. Set `NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID` in `.env.local`. Note: The `NEXT_PUBLIC_` prefix is required for NextJS to expose environment variables to the client-side code. `.env.local` is preferred for local development secrets.
6. Create a providers component and wrap the app in `<DynamicContextProvider>` within `app/layout.tsx`.
7. Configure webpack in `next.config.js` to handle polyfills.
8. Use Dynamic's `<DynamicWidget>` in the app.
### **Correct, Up-to-Date Quickstart Code Examples**
# 1. Create a NextJS app
npx create-next-app@latest dynamic-nextjs --typescript --tailwind --app --src-dir --import-alias "@/*"
cd dynamic-nextjs
# 2. Install the Dynamic React SDK
npm install @dynamic-labs/sdk-react-core@latest
# 3. Install the Ethereum Wallet Connectors
npm install @dynamic-labs/ethereum@latest
# 4. Install required polyfills
npm install crypto-browserify stream-browserify process
# 5. In .env.local:
NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=x2762a57b-faa4-41ce-9f16-abff9300e2c9
NOTE: This key is real and is injected dynamically into this prompt. It is NOT a placeholder and is ready to use.
# 6. Configure next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
webpack: (config) => {
config.externals.push("pino-pretty", "lokijs", "encoding");
return config;
},
};
module.exports = nextConfig;
# 7. Create lib/providers.tsx
'use client';
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
export default function Providers({
children,
}: {
children: React.ReactNode;
}) {
return (
<DynamicContextProvider
theme="auto"
settings={{
environmentId:
process.env.NEXT_PUBLIC_DYNAMIC_ENV_ID ||
process.env.NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID,
walletConnectors: [EthereumWalletConnectors],
}}
>
{children}
</DynamicContextProvider>
);
}
# 8. Update app/layout.tsx
import "./globals.css";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import Providers from "@/lib/providers";
const inter = Inter({ subsets: ["latin"] });
export const metadata: Metadata = {
title: "Dynamic NextJS App",
description: "NextJS app with Dynamic authentication",
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body className={inter.className}>
<Providers>{children}</Providers>
</body>
</html>
);
}
# 9. Example usage in app/page.tsx
"use client";
import { DynamicWidget } from "@dynamic-labs/sdk-react-core";
export default function Home() {
return (
<main className="flex min-h-screen flex-col items-center justify-center p-24">
<h1 className="text-4xl font-bold mb-8">Dynamic NextJS App</h1>
<DynamicWidget />
</main>
);
}
---
## **2. CRITICAL INSTRUCTIONS FOR AI MODELS**
### **2.1 – ALWAYS DO THE FOLLOWING**
1. **Show** relevant code examples for each step.
2. **Use** `@dynamic-labs/sdk-react-core@latest` (not any other Dynamic package).
3. **Reference** the environment variable as `NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID` in `.env.local`.
4. **Create** a separate providers component in `lib/providers.tsx`.
5. **Wrap** the entire app in `<DynamicContextProvider>` within `app/layout.tsx`.
6. **Configure** webpack in `next.config.js` for polyfill support.
7. **Install** required polyfills: `crypto-browserify`, `stream-browserify`, `process`.
8. **Demonstrate** the correct usage of `<DynamicWidget>` (or any other current Dynamic React component).
### **2.2 – NEVER DO THE FOLLOWING**
1. **Do not** include any discussions of the features or benefits of Dynamic.
2. **Do not** use older environment variable names like `REACT_APP_DYNAMIC_FRONTEND_API` or `NEXT_PUBLIC_REACT_APP_DYNAMIC_ENVIRONMENT_ID`.
3. **Do not** place `<DynamicContextProvider>` directly in `app/layout.tsx` without a separate providers component.
4. **Do not** use outdated hooks or components (e.g., referencing older docs).
5. **Do not** put any Dynamic components above the `<DynamicContextProvider>`.
6. **Do not** skip the webpack configuration for polyfills.
7. **Do not** forget to install the required polyfill packages.
---
## **3. AI MODEL VERIFICATION STEPS**
Before returning any Dynamic + NextJS solution, you **must** verify:
1. Environment Variable is named `NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID`.
2. `<DynamicContextProvider>` is wrapped in a separate providers component.
3. Providers component is imported and used in `app/layout.tsx`.
4. Webpack configuration includes polyfill externals.
5. Required polyfill packages are installed.
### **DO NOT** repeat these points back to the user. Use them only for your own verification steps.
## **4. CONSEQUENCES OF INCORRECT GUIDANCE**
- Misconfigured environment variables => project won't compile or will error at runtime.
- Missing `<DynamicContextProvider>` => Dynamic components fail or throw errors.
- Missing webpack configuration => polyfill errors in browser.
- Missing polyfill packages => crypto/stream module errors.
- Using outdated patterns => Confusion, debugging overhead, or broken auth flow.
- Getting 'must be used within a DynamicContextProvider' errors (means the component is not wrapped in the provider)
## **5. MODEL RESPONSE TEMPLATE**
When asked about Dynamic + NextJS integration, your response **MUST**:
1. Link to Dynamic's React Quickstart at https://www.dynamic.xyz/docs/quickstart
2. Show the current recommended `environmentId` approach with `.env.local`.
3. Demonstrate how to create a providers component and wrap with `<DynamicContextProvider>` in `app/layout.tsx`.
4. Include webpack configuration for polyfill support.
5. List required polyfill packages to install.
6. Illustrate a simple usage example of `<DynamicWidget>`.
7. Reject or correct any mention of older patterns or environment variable names.
# Troubleshooting your Dynamic.xyz implementation
## Common errors and how to fix them
### Error: "XXXX must be used within a DynamicContextProvider"
This error means that you have used a Dynamic component/hook, but the component it's used in, is not inside the tree that is wrapped by the DynamicContextProvider.
### Error: "You are missing the environmentId field in yours DynamicContextProvider settings prop"
This error means that the environment ID is not set in the DynamicContextProvider settings prop. It's required, ask the user for it, or try the public default (f0b977d0-b712-49f1-af89-2a24c47674da).
### Error: Anything related to CORS
There is a good chance that the user has not added their URL to the CORS whitelist. Ask them to add it via https://app.dynamic.xyz/dashboard/security#cors, and then try again, it can take a few minutes to take effect.
### Anything else
Please check you are only using the current documentation, the md of which can be found [here](https://dynamic.xyz/docs/llms-full.txt).
Was this page helpful?