ResourcesTroubleshooting

Server-side Rendering

⚠️ Common Issue: If SSR is not set up correctly, you may see sessions resetting or users getting logged out unexpectedly. Make sure to follow this guide fully to preserve session state.

When using Smart Wallets in a server-side rendered setting, you will see inconsistencies of the user state between the server and the client. This will lead to flashes of content when a user is logged in. To avoid this, the account state can be optimistically loaded on the server and passed to the client.

Update your config

To enable server-side rendering support, you need to set ssr: true when creating a config.

When using React, you should also make the config a function so that you can call it once per request, which allows for request-based isolation of the account state.

import { 
const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUI
Wraps 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 } from "@account-kit/react";
import { 
const sepolia: Chain
sepolia, 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";

export const 
const config: () => AlchemyAccountsConfigWithUI
config = () =>
  
function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUI
Wraps 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({
    // required
    
transport: AlchemyTransport
transport: 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ 
rpcUrl: string
rpcUrl: "/api/rpc" }),
    
chain: Chain
chain: 
const sepolia: Chain
sepolia,
    
ssr?: boolean | undefined
Enable 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,
  });

This setting will defer hydration of the account state to the client after the initial mount.

Persisting the Account State

To consistently pass the state between the server and the client, you can pass in a cookie storage to the config object created above. The cookie storage allows the client state to be written serialized to a cookie which can be passed along to the server on each request. This allows the server to have access to certain parts of the account state when rendering, ensuring a consistent render between client and server (eg. user’s address displayed in the top nav). Instances which can only be created on the client will still not be available on the server, however. This includes the signer or smart contract account instances.

import { 
const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUI
Wraps 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;
}) => Storage
Function to create cookie based Storage
cookieStorage } from "@account-kit/react";
import { 
const sepolia: Chain
sepolia, 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";
import { 
class QueryClient
QueryClient } from "@tanstack/react-query";

export const 
const queryClient: QueryClient
queryClient = new 
new QueryClient(config?: QueryClientConfig): QueryClient
QueryClient();

export const 
const config: () => AlchemyAccountsConfigWithUI
config = () =>
  
function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUI
Wraps 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({
    // required
    
transport: AlchemyTransport
transport: 
function alchemy(config: AlchemyTransportConfig): AlchemyTransport
Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ 
rpcUrl: string
rpcUrl: "/api/rpc" }),
    
chain: Chain
chain: 
const sepolia: Chain
sepolia,
    
ssr?: boolean | undefined
Enable 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,
    
storage?: CreateStorageFn | undefined
storage: 
const cookieStorage: (config?: {
    sessionLength?: number;
    domain?: string;
}) => Storage
Function to create cookie based Storage
cookieStorage,
  });

Now, depending on your application, you can get the state from cookies and pass in the initialState to the AlchemyAccountProvider to hydrate the account state on the client.

Next.js App Directory

If you are using NextJS App Directory, you can read the cookie state and pass it to the providers like so:

1// @noErrors
2import React from "react";
3import { cookieToInitialState } from "@account-kit/core";
4import type { Metadata } from "next";
5import { Inter } from "next/font/google";
6import { headers } from "next/headers";
7import { config } from "./config";
8import "./globals.css";
9import { Providers } from "./providers";
10
11const inter = Inter({ subsets: ["latin"] });
12
13export const metadata: Metadata = {
14  title: "Embedded Accounts Getting Started",
15  description: "Embedded Accounts Quickstart Guide",
16};
17
18export default function RootLayout({
19  children,
20}: Readonly<{
21  children: React.ReactNode;
22}>) {
23  // This will allow us to persist state across page boundaries
24  const initialState = cookieToInitialState(
25    // the config here is just used to compute the initial state
26    config(),
27    headers().get("cookie") ?? undefined,
28  );
29
30  return (
31    <html lang="en">
32      <body className={inter.className}>
33        <Providers initialState={initialState}>{children}</Providers>
34      </body>
35    </html>
36  );
37}