React library_

The Appwrite React library is a thin layer over the Web SDK that exposes a provider and a small set of hooks for authentication operations and current user state. It works in both client-rendered React apps and server-rendered apps on Next.js and TanStack Start.

Why use it

• SSR auth without boilerplate. Drop in one handler route per framework and skip the days normally spent writing cookie logic, session sync, and server/client hydration.
• Consistent user state across server and client. Server components, loaders, and client hooks return the same authenticated user, removing the need to reconcile auth state across the render boundary.
• Server-side access when you need it. Read the current user, create per-request session clients, or reach for an admin client without hand-wiring the Node SDK on every route.

Install

Install the library along with the Appwrite Web SDK and TanStack Query packages.

npm install @appwrite.io/react appwrite @tanstack/react-query

For SSR apps on Next.js or TanStack Start, also install node-appwrite. The SSR handlers create sessions with a server API key.

npm install @appwrite.io/react appwrite node-appwrite @tanstack/react-query

Pick your framework

Client-side React

For Vite and other client-rendered React apps.

Next.js

For server-rendered apps on the Next.js App Router.

TanStack Start

For server-rendered apps on TanStack Start.

The provider

Every app starts with an AppwriteProvider. In a CSR app, only endpoint and projectId are required.

import { AppwriteProvider } from "@appwrite.io/react";

<AppwriteProvider
  endpoint={import.meta.env.VITE_APPWRITE_ENDPOINT}
  projectId={import.meta.env.VITE_APPWRITE_PROJECT_ID}
>
  <App />
</AppwriteProvider>;

In an SSR app, pass an ssr prop with the session secret read from the server-side cookie and the path your handlers are mounted at.

<AppwriteProvider
  endpoint={endpoint}
  projectId={projectId}
  ssr={{ session, basePath: "/api/appwrite" }}
>
  {children}
</AppwriteProvider>

When ssr is set, sign-in, sign-up, and sign-out mutations route through your handler. The underlying Web SDK is hydrated with the session secret on first render, so authenticated reads do not need a round trip.

Hooks

The library exports one combined hook and four focused mutation hooks. All hooks share the same TanStack Query cache, so updating user state from any of them reflects everywhere.

useAuth

The primary hook for most apps. It bundles the current user, loading and error state, and handles for sign-in, sign-up, and sign-out into a single return value.

import { useAuth } from "@appwrite.io/react";

const { user, isLoading, error, refresh, signIn, signUp, signOut } = useAuth();

useUser

Read-only access to the current authenticated user. Use it in components that only need to display user state and do not trigger auth mutations.

import { useUser } from "@appwrite.io/react";

const { user, isLoading, error, refresh } = useUser();

useSignIn

Email and password and OAuth sign-in, with pending and error state scoped to the email and password flow.

const { emailPassword, oAuth, isPending, error } = useSignIn();

useSignUp

Create an account and start a session in one call. The hook also surfaces pending and error state for the in-flight request.

const { emailPassword, isPending, error } = useSignUp();

Email and password

emailPassword({ email, password, name, userId, onSuccess, onError });

useSignOut

End the current session, drop cached auth queries, and reset the local Web SDK client.

const { signOut, isPending, error } = useSignOut();

Sign out

signOut({ onSuccess, onError });

After a successful sign-out, all cached auth queries are dropped and the local Web SDK client is reset. On Next.js, call router.refresh() from onSuccess to re-render server components with the cleared cookie. On TanStack Start, call router.invalidate().

useAppwrite

Escape hatch to the underlying provider context. Use it when you need direct access to a Web SDK service the higher-level hooks do not wrap (tablesDB, storage, messaging, realtime, and so on).

import { useAppwrite } from "@appwrite.io/react";

const { client, account, tablesDB, storage, teams, ssr } = useAppwrite();

Throws if called outside an AppwriteProvider.

Server helpers

The library ships server entrypoints scoped per framework. Each helper exposes the same surface, differing only in how it reads the request cookie.

// Next.js (App Router)
import { createNextServerHelpers } from "@appwrite.io/react/server/next";

// TanStack Start
import { createTanStackServerHelpers } from "@appwrite.io/react/server/tanstack";

Both return an object with:

Session client

For per-request operations scoped to the current user (reading their data, calling APIs on their behalf), call createSessionClient from the framework helper. It returns a node-appwrite client already authenticated with the session cookie, ready to use in server components, loaders, and server functions.

import { createNextServerHelpers } from "@appwrite.io/react/server/next";

const helpers = createNextServerHelpers({
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
});

const session = await helpers.createSessionClient();

if (session) {
  const user = await session.account.get();
}

Admin client

For privileged operations (creating users, listing sessions, managing teams), call createAdminClient on the framework helper. Pass apiKey in the helper config to enable it, then call the method anywhere on the server. The returned object exposes every node-appwrite service: account, users, tablesDB, storage, teams, functions, messaging, and more.

import { createNextServerHelpers } from "@appwrite.io/react/server/next";

const helpers = createNextServerHelpers({
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
  apiKey: process.env.APPWRITE_API_KEY!,
});

const admin = helpers.createAdminClient();
const users = await admin.users.list();

If you would rather not pass the API key into the helper, the library also exports a standalone createAdminClient from @appwrite.io/react/server that takes the key directly.

import { createAdminClient } from "@appwrite.io/react/server";

const admin = createAdminClient({
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
  apiKey: process.env.APPWRITE_API_KEY!,
});

const users = await admin.users.list();

Never import any @appwrite.io/react/server/* module from client code: the entrypoints are marked server-only and will throw if bundled into the browser.

Handler routes

The SSR mutations (sign-in, sign-up, sign-out, oauth/callback, oauth/failure) live behind a handler route you mount once per app. The handler reads the request, talks to Appwrite with the server API key, and writes the session cookie back.

Cookie and redirect options

Customize how sessions persist in the browser and where users land after an OAuth round trip.

createAppwriteHandlers({
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
  apiKey: process.env.APPWRITE_API_KEY!,
  basePath: "/api/appwrite",
  cookieName: "my-app-session",
  cookieOptions: {
    sameSite: "strict",
    domain: ".example.com",
  },
  redirects: {
    success: "/dashboard",
    failure: "/login?error=oauth",
  },
});

Required scopes

Your server API key needs three scopes for the SSR handler to function:

• users.write (sign-up creates a user)
• users.read (sign-up confirms the created user)
• sessions.write (sign-in, sign-out, and OAuth callbacks create or delete sessions)

Next steps

• Start with React
• Start with Next.js
• Start with TanStack Start
• Account API reference