# @appwrite\.io/react 中文文档

规范地址：https://npmcn.com/package/%40appwrite.io/react/

版本：0\.1\.1
npm 元数据更新时间：2026-10-24T10:24:44.289Z
中文译文更新时间：2026-11-07T09:05:29.806Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40appwrite.io/react
原文对照：https://npmcn.com/package/%40appwrite.io/react/?lang=original
项目主页：https://github.com/appwrite/sdk-for-react#readme
源码仓库：https://github.com/appwrite/sdk-for-react

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：152 kB，101 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：next \>=15\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，appwrite ^25\.2\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，node-appwrite ^26\.0\.0，@tanstack/react-query ^5\.0\.0，@tanstack/react-start ^1\.0\.0
- 首次发布：2026-05-16T18:01:01.483Z
- 最新版本发布：2026-10-24T10:24:43.814Z
- 近 30 天下载量：1969（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

[![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord)

## 安装

```sh
npm install @appwrite.io/react
```

也可以使用：`pnpm add @appwrite.io/react`、`yarn add @appwrite.io/react`、`bun add @appwrite.io/react`

## README

# 默认重现 SDK

[![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord)

Appwrite是一个开源后端,作为一种服务,在简单的API后面摘要介绍共同的应用程序特征. Appwrite React SDK在客户端和服务器端的React应用程序中为Appwrite认证提供React switch和框架适配器.

![Appwrite](https://github.com/appwrite/appwrite/raw/main/public/images/github.png)

## 特征

-   对注册、登录、签出、OAuth和当前用户状态的反应提供者和钩子
-   Vite 和其他非 SSR 反应应用程序的客户端代理
-   Next.js 和 TanStack Start 的 SSR 认证处理器
-   从 HTTP 只读 cookie 读取当前用户/ 会话的服务器助手
-   服务器连接会话客户端和管理员客户端

## 安装

对于客户端的 React 应用程序 :

```sh
pnpm add @appwrite.io/react appwrite @tanstack/react-query
```

对于使用服务器处理器或管理员客户端的 SSR 应用程序,也安装 `node-appwrite`数字 :

```sh
pnpm add @appwrite.io/react appwrite node-appwrite @tanstack/react-query
```

框架软件包,例如 `next`, (中文(简体) ), `@tanstack/react-start`, (中文(简体) ), `react`,以及 `react-dom` 应该来自你的应用脚手架.

## 非 SSR 反应应用程序

使用此设置用于 Vite 或任何在浏览器中直接处理 auth 的应用程序 .

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

export function Root() {
  return (
    <AppwriteProvider
      endpoint={import.meta.env.VITE_APPWRITE_ENDPOINT}
      projectId={import.meta.env.VITE_APPWRITE_PROJECT_ID}
    >
      <App />
    </AppwriteProvider>
  );
}
```

然后,为了认证:

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

export function AuthPanel() {
  const { user, isLoading, signIn, signUp, signOut } = useAuth();

  if (isLoading) return <p>Loading...</p>;

  if (!user) {
    return (
      <>
        <button
          onClick={() =>
            signIn.emailPassword({
              email: "user@example.com",
              password: "password123",
            })
          }
        >
          Sign in
        </button>
        <button
          onClick={() =>
            signUp.emailPassword({
              email: "user@example.com",
              password: "password123",
              name: "Jane Doe",
            })
          }
        >
          Sign up
        </button>
      </>
    );
  }

  return (
    <>
      <p>Signed in as {user.email}</p>
      <button onClick={() => signOut.signOut()}>Sign out</button>
    </>
  );
}
```

## Next.js App 路由器 SSR

设定 public Appwrite 值并只保留 API 密钥 :

```env
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://fra.cloud.appwrite.io/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=PROJECT_ID
APPWRITE_API_KEY=SERVER_ONLY_API_KEY
```

创建 Appwrite auth 处理器路由 :

```ts
// app/api/appwrite/[...appwrite]/route.ts
import { createAppwriteHandlers } from "@appwrite.io/react/handlers/next";

export const { GET, POST } = 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",
});
```

将服务器会话传递到客户端提供者 :

```tsx
// app/providers.tsx
"use client";

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

export function Providers({
  session,
  children,
}: {
  session?: string | null;
  children: React.ReactNode;
}) {
  return (
    <AppwriteProvider
      endpoint={process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!}
      projectId={process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!}
      ssr={{ session, basePath: "/api/appwrite" }}
    >
      {children}
    </AppwriteProvider>
  );
}
```

```tsx
// app/layout.tsx
import { createNextServerHelpers } from "@appwrite.io/react/server/next";
import { Providers } from "./providers";

const appwrite = {
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
};

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const helpers = createNextServerHelpers(appwrite);
  const session = await helpers.readSessionCookie();

  return (
    <html lang="en">
      <body>
        <Providers session={session}>{children}</Providers>
      </body>
    </html>
  );
}
```

读取 SSR 认证状态并创建服务器文本客户端 :

```tsx
// app/page.tsx
import { createNextServerHelpers } from "@appwrite.io/react/server/next";

const appwrite = {
  endpoint: process.env.NEXT_PUBLIC_APPWRITE_ENDPOINT!,
  projectId: process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID!,
  apiKey: process.env.APPWRITE_API_KEY!,
};

export default async function Page() {
  const helpers = createNextServerHelpers(appwrite);

  const user = await helpers.getLoggedInUser();
  const sessionClient = await helpers.createSessionClient();
  const adminClient = helpers.createAdminClient();
  const users = await adminClient.users.list({ total: false });

  return (
    <main>
      <p>SSR user: {user?.email ?? "signed out"}</p>
      <p>Session client: {sessionClient ? "available" : "none"}</p>
      <p>Admin users loaded: {users.users.length}</p>
    </main>
  );
}
```

在客户端组件中,使用同一种钩. 当服务器给定状态应更新时, 在验证后刷新路由器 .

```tsx
// app/auth-panel.tsx
"use client";

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

export function AuthPanel() {
  const { user, isLoading, signIn, signOut } = useAuth();
  const router = useRouter();

  if (isLoading) return <p>Loading...</p>;

  if (!user) {
    return (
      <button
        onClick={() =>
          signIn.emailPassword({
            email: "user@example.com",
            password: "password123",
            onSuccess: () => router.refresh(),
          })
        }
      >
        Sign in
      </button>
    );
  }

  return (
    <button
      onClick={() => signOut.signOut({ onSuccess: () => router.refresh() })}
    >
      Sign out
    </button>
  );
}
```

## TanStack 启动安全部门改革

设定 public Appwrite 值并只保留 API 密钥 :

```env
VITE_APPWRITE_ENDPOINT=https://fra.cloud.appwrite.io/v1
VITE_APPWRITE_PROJECT_ID=PROJECT_ID
APPWRITE_API_KEY=SERVER_ONLY_API_KEY
```

创建 Appwrite auth 处理器路由 :

```ts
// src/routes/api/appwrite/$.ts
import { createFileRoute } from "@tanstack/react-router";
import { createAppwriteHandlers } from "@appwrite.io/react/handlers/tanstack";

export const Route = createFileRoute("/api/appwrite/$")({
  server: {
    handlers: createAppwriteHandlers({
      endpoint: import.meta.env.VITE_APPWRITE_ENDPOINT,
      projectId: import.meta.env.VITE_APPWRITE_PROJECT_ID,
      apiKey: process.env.APPWRITE_API_KEY!,
      basePath: "/api/appwrite",
    }),
  },
});
```

在服务器函数中读取 SSR 认证状态并将会话传递到提供者 :

```tsx
// src/routes/index.tsx
import { createFileRoute, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { AppwriteProvider, useAuth } from "@appwrite.io/react";
import { createTanStackServerHelpers } from "@appwrite.io/react/server/tanstack";

const getAuthSnapshot = createServerFn({ method: "GET" }).handler(async () => {
  const appwrite = {
    endpoint: import.meta.env.VITE_APPWRITE_ENDPOINT,
    projectId: import.meta.env.VITE_APPWRITE_PROJECT_ID,
    apiKey: process.env.APPWRITE_API_KEY!,
  };

  const helpers = createTanStackServerHelpers(appwrite);
  const user = await helpers.getLoggedInUser();
  const sessionClient = await helpers.createSessionClient();
  const adminClient = helpers.createAdminClient();
  const users = await adminClient.users.list({ total: false });

  return {
    session: helpers.readSessionCookie() ?? null,
    user,
    hasSessionClient: Boolean(sessionClient),
    adminUserCount: users.users.length,
  };
});

export const Route = createFileRoute("/")({
  loader: () => getAuthSnapshot(),
  component: Page,
});

function Page() {
  const { session, user, hasSessionClient, adminUserCount } = Route.useLoaderData();

  return (
    <AppwriteProvider
      endpoint={import.meta.env.VITE_APPWRITE_ENDPOINT}
      projectId={import.meta.env.VITE_APPWRITE_PROJECT_ID}
      ssr={{ session, basePath: "/api/appwrite" }}
    >
      <main>
        <p>SSR user: {user?.email ?? "signed out"}</p>
        <p>Session client: {hasSessionClient ? "available" : "none"}</p>
        <p>Admin users loaded: {adminUserCount}</p>
        <AuthPanel />
      </main>
    </AppwriteProvider>
  );
}

function AuthPanel() {
  const { user, isLoading, signIn, signOut } = useAuth();
  const router = useRouter();

  if (isLoading) return <p>Loading...</p>;

  if (!user) {
    return (
      <button
        onClick={() =>
          signIn.emailPassword({
            email: "user@example.com",
            password: "password123",
            onSuccess: () => router.invalidate(),
          })
        }
      >
        Sign in
      </button>
    );
  }

  return (
    <button
      onClick={() => signOut.signOut({ onSuccess: () => router.invalidate() })}
    >
      Sign out
    </button>
  );
}
```

## API 概览

客户切入点 :

```ts
import {
  AppwriteProvider,
  OAuthProvider,
  useAuth,
  useSignIn,
  useSignOut,
  useSignUp,
  useUser,
} from "@appwrite.io/react";
```

服务器入口 :

```ts
import { createAppwriteHandlers as createNextAppwriteHandlers } from "@appwrite.io/react/handlers/next";
import { createAppwriteHandlers as createTanStackAppwriteHandlers } from "@appwrite.io/react/handlers/tanstack";

import {
  createAdminClient,
  createSessionClient,
} from "@appwrite.io/react/server";
import { createNextServerHelpers } from "@appwrite.io/react/server/next";
import { createTanStackServerHelpers } from "@appwrite.io/react/server/tanstack";
```

不从客户端组件或仅浏览器代码导入服务器入口 .

## 学习更多

-   [接受文档](https://appwrite.io/docs)
-   [迪斯科德社区](https://appwrite.io/discord)

## 许可证

请看 [麻省理工学院许可证](https://npmcn.com/package/%40appwrite.io/react/LICENSE) 文档以获取更多信息.

## 常见问题

### 如何安装 @appwrite\.io/react？

在项目目录运行 npm install @appwrite\.io/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、appwrite（^25\.2\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@tanstack/react-query（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @appwrite\.io/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @appwrite\.io/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @appwrite\.io/react 可以商用吗？

@appwrite\.io/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @appwrite\.io/react 的下载量有多少？

根据 npm 官方下载统计，@appwrite\.io/react 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,969 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @appwrite\.io/react 还在维护吗？

最新版本 0\.1\.1 发布于 2026/10/24（14 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/05/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。