React Quickstart
In this guide, you’ll create an embedded wallet including sign up with email, passkey, and social login for smart accounts, connect wallet for existing EOAs, and seamless transactions with gas sponsorship.

Below you’ll find guides for:
- starting fresh with a new NextJS template
- integrating into an existing React project
Check out what you can build using our Demo App.
New NextJS project
1. Create a new NextJS app using our template
For a simple end-to-end example, we will spin up a new NextJS app using our template.
2. Get your Alchemy API Key
-
Get your API key by creating a new app in your Alchemy Dashboard
Make sure Arbitrum Sepolia is enabled for your app under the Networks tab. The quickstart will demonstrate minting a NFT on Arbitrum Sepolia.
-
Create a new account config in your Account Kit Dashboard
-
Apply the config to your app from step 1
-
Enable authentication methods you want to support.
Email authIf you want to use email auth, toggle on email.
- For testing, use http://localhost:3000 as the Redirect URL (Note http not https)
- The user will be redirected to the Redirect URL if you use the magic link email flow
- Optionally stylize ✨ the email with your brand color and logo!
Social authIf you want to enable social login, toggle which auth providers you want to support.
-
For testing, add http://localhost:3000 as a whitelisted origin
-
Add the link that your dapp will be running on to the whitelisted origin list
-
Optionally enter your own OAuth credentials or use our defaults
-
-
Create the config and copy the API Key
…and add the API key to your .env
file:
you can copy the .env.example
file to .env
and replace the ALCHEMY_API_KEY
with your own.
3. Get your Alchemy paymaster policy ID
Set up a paymaster policy to sponsor gas for your smart wallets. If you want more information on how to set up a paymaster policy, see the Sponsor gas docs.
- Go to the Alchemy Dashboard
- Navigate to Wallets → Gas Manager
- In the Policies tab, click the “Create new policy +” button
- Fill out the steps to create a new policy. See the example inputs below:
- Policy details
- Name:
Smart Wallets Policy
- Policy type:
Sponsor gas
- Select chain type:
EVM networks
- App: Select your app from the dropdown
- Select networks:
Arbitrum Sepolia
(required for the NFT minting example in this quickstart)
- Name:
- Spending rules
- Select all the checkboxes to not set any limits
- Select
I don't want to set custom rules
- Access Controls
- Select
None
- Select
- Expiry and duration
- Use the default values
- Policy details
- Review and publish the policy
- Copy the policy ID to your
.env
file
4. Run the app!
That’s it! Run the NextJS app to see your new auth flow in action ✨
Existing project
To integrate in to your existing dapp and better understand the above demo app, we will walk through the each of the steps required for using alchemy ui components in technical depth!
1. Install the packages
Prerequisites
- minimum React version of 18
- minimum Typescript version of 5
- pin viem to 2.20.0 (
yarn add [email protected]
) - pin wagmi to 2.12.7 (
yarn add [email protected]
)
Installation
Install the React and Infra packages from Account Kit along with tailwind for styling and react-query to support react components.
Tailwind Setup
If you don’t have tailwind setup yet, create a postcss.config.mjs
file (if you don’t already have one) and add the @tailwindcss/postcss
plugin.
The only thing left to do is to create a global.css file and import it in the root of your app.
For more on tailwind setup, see these steps.
Still using tailwind v3?
If you’re still using tailwind v3, don’t fret. Account Kit is still fully compatible. Just skip the above tailwind setup steps since you’ve already set it up.
2. Get your Alchemy API Key
See the steps above in the NextJS section to get your API key.
3. Configure your UI components
In this step, you’ll customize your authentication methods and UI styles.
The demo app provides an interactive sandbox to explore combinations. When you’re all done, click the ‘Code preview’ toggle to export your code! You’ll get two files:
tailwind.config.ts
config.ts
*Note: tailwind.config.ts and config.ts changes are required even if using default styling*

3a. Customize styling with tailwind
-
In the demo app, copy your
tailwind.config.ts
code into a file of the same name in your project. This will apply your custom styles: colors, border radius, and illustrations.- Logo: logo images are loaded client side for maximum performance, so you’ll need to add the image file to your project and specify the file path in the config where noted.
- Light/Dark mode:
- Light Mode and Dark Mode are set to match the system theme. You can manually override this by following this guide. TLDR: add
@custom-variant dark (&:is(.dark, .dark *));
to yourglobal.css
file.(If you are still using tailwind v3, follow this guide instead. TLDR: update your tailwindcss config to use
selector
mode for dark and then add thedark
class to the root of your DOM.)
- Light Mode and Dark Mode are set to match the system theme. You can manually override this by following this guide. TLDR: add
- You can customize even more style properties
-
If your
tailwind.config.ts
already contains any existing config information, be sure to wrap it withwithAccountKitUi
:tailwind.config.ts -
Update your
global.css
file to include yourtailwind.config.ts
. (Skip this step if you’re still using tailwind v3.)
3b. Customize authentication methods
-
In the root of your project, create a
config.ts
file -
In the demo app, copy your
config.ts
code into the file of the same name in your project. This will apply your authentication methods (email, passkey, etc.)-
createConfig
is used to initialize the alchemy provider in the next step. It requires 2 params:-
props
: for creating an Alchemy config. Notice the 4 params passed to props in our example:- apiKey (required): Copy-paste your Alchemy API key, from step 2. Note that for production this key should be protected by proxying to the backend and setting rpcUrl instead
- chain (required): Chain imported from @account-kit/infra . This chain must match the chain your api key / embedded accounts config is setup for.
- ssr (optional): Highly recommended for NextJs applications to keep account state consistent between the server and client
- storage (optional): Cookie storage highly recommended for NextJs applications to persist and cache account state across page loads
- enablePopupOauth (optional): If implementing social login, allow for the sign in window to appear as a pop up to your user.
- sessionConfig (optional): Used to configure the session duration
-
ui
: for creating Alchemy Accounts UI components -
See here for full details on the ui config params including authentication options
-
-
-
Make sure to export your config and queryClient:
Remember to paste in your API Key from step 2
import { const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUIWraps the createConfig
that is exported from @aa-sdk/core
to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig, const cookieStorage: (config?: {
sessionLength?: number;
domain?: string;
}) => StorageFunction to create cookie based Storage
cookieStorage } from "@account-kit/react";
import { class QueryClientQueryClient } from "@tanstack/react-query";
import { const arbitrumSepolia: ChainarbitrumSepolia } from "@account-kit/infra";
export const const config: AlchemyAccountsConfigWithUIconfig = function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUIWraps the createConfig
that is exported from @aa-sdk/core
to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig(
{
// alchemy config
transport: anytransport: anyalchemy({ apiKey: stringapiKey: "your_api_key" }), // TODO: add your Alchemy API key - setup your app and embedded account config in the alchemy dashboard (https://dashboard.alchemy.com/accounts)
chain: Chainchain: const arbitrumSepolia: ChainarbitrumSepolia, // TODO: specify your preferred chain here and update imports from @account-kit/infra
ssr?: boolean | undefinedEnable this parameter if you are using the config in an SSR setting (eg. NextJS) Turing this setting on will disable automatic hydration of the client store
ssr: true, // Defers hydration of the account state to the client after the initial mount solving any inconsistencies between server and client state (read more here: https://www.alchemy.com/docs/wallets/react/ssr)
storage?: CreateStorageFn | undefinedstorage: const cookieStorage: (config?: {
sessionLength?: number;
domain?: string;
}) => StorageFunction to create cookie based Storage
cookieStorage, // persist the account state using cookies (read more here: https://www.alchemy.com/docs/wallets/react/ssr#persisting-the-account-state)
enablePopupOauth: trueenablePopupOauth: true, // must be set to "true" if you plan on using popup rather than redirect in the social login flow
// optional config to override default session manager config
sessionConfig?: ({
storage?: Storage | "localStorage" | "sessionStorage" | undefined;
sessionKey?: string | undefined;
expirationTimeMs?: number | undefined;
} & {
domain?: string;
}) | undefinedsessionConfig: {
expirationTimeMs?: number | undefinedexpirationTimeMs: 1000 * 60 * 60, // 60 minutes (default is 15 min)
},
},
{
// authentication ui config - your customizations here
auth?: {
addPasskeyOnSignup?: boolean;
header?: React.ReactNode;
hideError?: boolean;
onAuthSuccess?: () => void;
sections: AuthType[][];
hideSignInText?: boolean;
} | undefinedauth: {
sections: AuthType[][]Each section can contain multiple auth types which will be grouped together and separated by an OR divider
sections: [
[{ type: "email"type: "email" }],
[
{ type: "passkey"type: "passkey" },
{ type: "social"type: "social", authProviderId: KnownAuthProviderauthProviderId: "google", mode: "popup"mode: "popup" },
{ type: "social"type: "social", authProviderId: KnownAuthProviderauthProviderId: "facebook", mode: "popup"mode: "popup" },
],
[
{
type: "external_wallets"type: "external_wallets",
walletConnect?: {
isNewChainsStale?: boolean | undefined;
client?: SignClient | undefined;
storage?: IKeyValueStorage | undefined;
projectId: string;
metadata?: Metadata | undefined;
... 13 more ...;
showQrModal?: boolean | undefined;
} | undefinedwalletConnect: { projectId: stringprojectId: "your-project-id" },
},
],
],
addPasskeyOnSignup?: boolean | undefinedIf this is true, then auth components will prompt users to add a passkey after signing in for the first time
addPasskeyOnSignup: true,
showSignInText: booleanshowSignInText: true,
},
},
);
export const const queryClient: QueryClientqueryClient = new new QueryClient(config?: QueryClientConfig): QueryClientQueryClient();
4. Set up the Alchemy Provider
This example assumes you are using the NextJS app router.
However, the key pieces are applicable to any React app and you can structure the location of the code as needed.
4a. Create the provider - app/providers.tsx
Once you have styling and authentication configs, create a providers.tsx
file and import the AlchemyAccountProvider
.
The QueryClientProvider
is also required to handle React Queries within the Alchemy Account Provider.
4b. Use the provider - layout.tsx
Any component or page that will use Alchemy React components, must be wrapped by this Provider
.
Additionally, we recommend using cookies to set the initial state when creating the provider to persist state across reloads (🧠 remember the cookie storage configured in step 3b).
For example, wrap your app with the created Provider
by modifying your layout.tsx
file.
5. Run it
Once you have wrapped your app with the Alchemy Provider, you can now use the pre-built Alchemy react components for auth throughout your app.
All you need to do is useAuthModal
! For example, pop open the auth modal like so: