gitalk-react 1.0.0-beta.8 → 1.1.0

package/README-zh-CN.md

@@ -1,4 +1,4 @@
-基于 Github 议题和 React 的现代评论组件。
+基于 GitHub Issue 和 React 的现代评论组件。
 
 [ENGLISH](./README.md) | 简体中文
 
@@ -7,56 +7,66 @@
 [![NPM][npm-version-image]][npm-version-url]
 [![gzip-size][gzip-size]][gzip-url]
 
-使用 TypeScript, React 和 Vite 重新实现 [Gitalk](https://github.com/gitalk/gitalk) —— 基于 Github 议题的评论组件。
+使用 TypeScript, React 和 Vite 重新实现 [Gitalk](https://github.com/gitalk/gitalk) —— 基于 Github Issue 的评论组件。
 
-面向现代浏览器开发，专注于减少构建包的体积，提升开发与使用的体验。
+面向现代浏览器开发，致力于减小构建体积，提升开发与使用的体验。
 
 ## 与原版的区别
 
 - **不兼容旧版浏览器**：仅保证兼容支持 [ES2020](https://caniuse.com/?feats=mdn-javascript_operators_optional_chaining,mdn-javascript_operators_nullish_coalescing,mdn-javascript_builtins_globalthis,es6-module-dynamic-import,bigint,mdn-javascript_builtins_promise_allsettled,mdn-javascript_builtins_string_matchall,mdn-javascript_statements_export_namespace,mdn-javascript_operators_import_meta) 的现代浏览器。
-- **依赖 React 运行时环境**：`react >= 16.8.0 && react-dom >= 16.8.0`。
 - **部分参数的默认值发生了变化**：迁移到此组件时请留意。
   - `id`：Gitalk 使用 `location.href` 作为默认值，Gitalk React 使用 `location.host + location.pathname` 作为默认值，避免预期外的查询参数。
   - `defaultAuthor`：仍然可以使用。Gitalk React 新增了参数项 `defaultUser` 来设置评论的默认用户，保持字段命名与 Github API 一致。
 
-## 开发中的功能
-
-- [ ] Feature: 支持在 Gitalk React 编辑自己发表的评论。
-- [x] Feature: 支持折叠过长的评论，允许点击展开该评论。
-- [ ] refactor: 逐渐移除对非必要三方库的依赖。减少构建包的体积。
-- [ ] test: 添加自动化测试流程。提升项目的健壮性。
-- [x] chore: 部署[预览环境](https://lolipopj.github.io/gitalk-react/)。
-
 ## 快速开始
 
-### 安装
+### Node.js 项目
 
 ```bash
 npm install gitalk-react
 ```
 
-### 使用
-
-在项目中引入 Gitalk React 的样式与组件：
+在项目中引入样式与组件：
 
 ```tsx
-// 引入浅色模式样式
+// 引入浅色样式
 import 'gitalk-react/gitalk.css'
-// 或深色模式样式
-import 'gitalk-react/gitalk-dark.css'
+// 或深色样式
+// import 'gitalk-react/gitalk-dark.css'
 
 import Gitalk from 'gitalk-react'
 ```
 
-Gitalk React 依赖于 Github OAuth App 实现登录鉴权，您需要首先[注册一个应用](https://github.com/settings/applications/new)。请注意，您必须将站点域名作为 `Authorization callback URL` 字段的值，例如 `https://yourdomain.com/site` 或开发环境下的 `http://localhost:5432`。
+Gitalk React 依赖于 Github OAuth App 进行登录认证；您需要首先[注册一个应用](https://github.com/settings/applications/new)。请注意，您必须将站点域名作为 `Authorization callback URL` 字段的值，例如 `https://yourdomain.com/site`，开发环境下则为 `http://localhost:5432`。
+
+通过自建后端代理服务器实现安全部署，请使用以下配置：
+
+- `clientID`：您的 GitHub OAuth App ID。
+- `proxy`：后端代理服务器的 URL 端点，用于安全地处理 OAuth 授权码到令牌的交换。详见[部署代理](#部署代理)章节。
+- `owner`：您的 GitHub 用户名。
+- `repo`：您的 GitHub 仓库名称。必须是公开仓库。
+- `admin`：Gitalk React 管理员列表；只有列表中的用户才能初始化评论话题。可以是 Github 仓库的拥有者和协作者。
+
+```tsx
+<Gitalk
+  clientID="YOUR_GITHUB_OAUTH_APP_CLIENT_ID"
+  proxy="https://your-server.com/oauth/access_token"
+  owner="GITHUB_REPO_OWNER"
+  repo="GITHUB_REPO_NAME"
+  admin={['GITHUB_REPO_OWNER', 'GITHUB_REPO_COLLABORATOR']}
+/>
+```
+
+> [!CAUTION]
+> 提供 `clientSecret` 会使 Gitalk 将 OAuth 授权模式降级为隐式授权流（Implicit Grant Flow）模式。该模式会将密钥暴露给访问者和中继服务，行业标准已正式弃用并反对使用此模式。
 
-使用 Gitalk React 组件，填写必要的配置项：
+**请务必清楚您正在执行的操作。** 对于仍需使用已暴露密钥的旧版部署方式，请使用以下配置：
 
-- `clientId`：Github OAuth App 的 ID。
-- `clientSecret`：Github OAuth App 的 Secret 密钥。
-- `owner`：Github 用户名。
-- `repo`：Github 仓库名。需要是公开的仓库。
-- `admin`：Gitalk React 管理员列表，只有列表里的人可以初始化评论议题。可以是 Github 仓库的拥有者和协作者。
+- `clientID`：您的 GitHub OAuth App ID。
+- `clientSecret`：您的 GitHub OAuth App Secret。
+- `owner`：您的 GitHub 用户名。
+- `repo`：您的 GitHub 仓库名称。必须是公开仓库。
+- `admin`：Gitalk React 管理员列表；只有列表中的用户才能初始化评论话题。可以是 Github 仓库的拥有者和协作者。
 
 ```tsx
 <Gitalk
@@ -68,6 +78,67 @@ Gitalk React 依赖于 Github OAuth App 实现登录鉴权，您需要首先[注
 />
 ```
 
+Gitalk React 是一个**客户端组件**，**不支持服务端渲染（SSR）**。它在渲染过程中会读取浏览器 API。源码入口及两个发布的 JavaScript 入口均带有 `"use client"` 指令；这标记了 React 客户端边界，但不会禁用 SSR 框架中的预渲染功能。
+
+在 Next.js App Router 中，创建一个客户端包装器并对动态导入禁用 SSR：
+
+```tsx
+'use client'
+
+import dynamic from 'next/dynamic'
+import type { GitalkProps } from 'gitalk-react'
+import 'gitalk-react/gitalk.css'
+
+const Gitalk = dynamic(() => import('gitalk-react'), { ssr: false })
+
+export default function Comments(props: GitalkProps) {
+  return <Gitalk {...props} />
+}
+```
+
+使用上述配置渲染此包装器。其他 SSR 框架也必须确保仅在浏览器端加载和挂载 Gitalk。
+
+### 浏览器 CDN
+
+两种浏览器构建版本都会暴露一个全局的 `Gitalk` 构造函数。加载其中一个构建版本及所需的样式表即可；以下示例使用的是浅色主题。如需使用深色主题，请引入 `dist/gitalk-dark.css`。
+
+对于未使用 React 的页面，请使用完整版构建，该版本内置了 React 19.3.1 和 ReactDOM 19.3.1，并通过 `createRoot` 进行挂载：
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk-light.css"
+/>
+<div id="gitalk-container"></div>
+<script src="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk.browser.full.js"></script>
+<script>
+  const gitalk = new Gitalk({
+    clientID: 'YOUR_GITHUB_OAUTH_APP_CLIENT_ID',
+    proxy: 'https://your-server.com/oauth/access_token',
+    owner: 'GITHUB_REPO_OWNER',
+    repo: 'GITHUB_REPO_NAME',
+    admin: ['GITHUB_REPO_OWNER'],
+  })
+  gitalk.render('gitalk-container')
+</script>
+```
+
+jsDelivr 和 unpkg 的裸包 URL 默认指向完整版构建。
+
+如果页面中已存在匹配的全局 `React` 和 `ReactDOM` 对象，请使用 `gitalk.browser.js` 而非 `gitalk.browser.full.js`。当检测到 `ReactDOM.createRoot` 可用时（React 18+），它会优先使用该方法；否则将回退使用 `ReactDOM.render` / `ReactDOM.unmountComponentAtNode`（适用于 React 16/17）。以下是 React 18 环境下的完整脚本加载顺序示例：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/react@18.3.1/browser/react.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/react-dom@18.3.1/browser/react-dom.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk.browser.js"></script>
+```
+
+通过应用打包工具安装的 React 不会自动提供这些全局变量。此类应用应使用 React 组件导入方式，或在加载浏览器构建前显式暴露共享运行时。在使用 React 19 时，需将 `react-dom/client` 模块作为 `ReactDOM` 暴露出来，以确保其 `createRoot` 方法可用；仅引入 `react-dom` 模块并不会导出 `createRoot`。加载完整版构建既不依赖也不覆盖页面现有的 React 全局变量。
+
+`render(id)` 方法接受元素 ID（不带 `#` 前缀）。调用该方法时，对应元素必须已存在于 DOM 中。重复调用此方法会更新当前挂载点；若传入新的 ID，则会先卸载之前的容器。在移除组件前（例如页面跳转时），请务必调用 `gitalk.destroy()`。实例在销毁后仍可重新渲染。
+
+构造函数接受的配置项与 React 组件相同，建议采用前述 `clientID` + `proxy` 的配置方式，以确保密钥安全存储于服务端。两种浏览器构建均不会自动包含 CSS 样式。
+
 ## 配置
 
 ### clientID `string`
@@ -76,7 +147,9 @@ Gitalk React 依赖于 Github OAuth App 实现登录鉴权，您需要首先[注
 
 ### clientSecret `string`
 
-**必填项**。Github OAuth App 的 Secret 密钥。
+您的 GitHub OAuth App Secret。提供此项时，Gitalk 会通过 `proxy` 发送包含授权码、Client ID 和 Secret 的 POST 请求；若省略或留空 `proxy`，则使用 `DEFAULT_PROXY`。此模式会在浏览器和 CORS 中继中暴露密钥。
+
+您应该将 OAuth App Secret 保存在服务端。对于安全部署，请省略 `clientSecret` 并提供服务端 `proxy`。
 
 ### owner `string`
 
@@ -120,7 +193,7 @@ Gitalk React 在创建评论议题时，自动将此参数作为评论议题的
 
 Gitalk React 使用的语言。
 
-可用的语言包括：`"de" | "en" | "es-ES" | "fa" | "fr" | "ja" | "ko" | "pl" | "ru" | "zh-CN" | "zh-TW"`。
+可用翻译：`ar`、`bn`、`de`、`en`、`es`、`fa`、`fr`、`hi`、`ja`、`ko`、`pl`、`pt`、`ru`、`ur`、`zh-CN` 和 `zh-TW`。诸如 `fr-FR`、`de-DE` 和 `ja-JP` 等 BCP 47 区域标签会选择基础翻译。中文地区和文字标签会保留简体/繁体中文（`zh-Hans` / `zh-Hant`）。不支持或无效的标签将使用英语。相对评论日期使用具有相同解析语言的 `Intl.RelativeTimeFormat`。
 
 ### perPage `number = 10`
 
@@ -128,7 +201,7 @@ Gitalk React 使用的语言。
 
 ### pagerDirection `"last" | "first" = "last"`
 
-评论排序的方式。`last` 表示按评论创建时间倒叙排列，`first` 表示按评论创建时间正叙排列。
+评论排序的方式。`last` 表示按评论创建时间降序排列，`first` 表示按评论创建时间升序排列。
 
 ### createIssueManually `boolean = false`
 
@@ -144,24 +217,11 @@ Gitalk React 使用的语言。
 
 是否启用仿 Facebook 评论框的全屏遮罩效果。
 
-### flipMoveOptions `FlipMove.FlipMoveProps`
-
-评论列表的动画效果。
-
-默认值，效果[参考](https://github.com/joshwcomeau/react-flip-move/blob/master/documentation/enter_leave_animations.md)：
-
-```json
-{
-  "staggerDelayBy": 150,
-  "appearAnimation": "accordionVertical",
-  "enterAnimation": "accordionVertical",
-  "leaveAnimation": "accordionVertical"
-}
-```
+### proxy `string`
 
-### proxy `string = "https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token"`
+当提供 `clientSecret` 时，这是一个可选的 CORS 中继 URL。默认为 `https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token`。您可以选择其他 CORS 服务。Gitalk 会发送包含 code、client ID 和 secret 的 POST 请求；中继服务解决浏览器的跨域限制，同时 GitHub 仍会验证 OAuth 凭证。
 
-Github OAuth App 鉴权反向代理，支持 CORS。[为什么需要它？](https://github.com/isaacs/github/issues/330)
+当省略 `clientSecret` 时，`proxy` 为必填项，且必须指向您的服务端 OAuth 交换端点。Gitalk 仅发送带有授权码（作为编码的 `code` 查询参数）的 GET 请求，并保留现有的查询参数。服务端存储凭证并返回 JSON `{ "access_token": "..." }`。
 
 ### defaultUser `{ avatar_url: string; login: string; html_url: string }`
 
@@ -181,6 +241,10 @@ Github OAuth App 鉴权反向代理，支持 CORS。[为什么需要它？](http
 
 当评论的高度大于 `${collapsedHeight}px` 时，自动折叠到 `${collapsedHeight}px`。
 
+### highlightAdminComment `boolean = true`
+
+是否高亮管理员发表的评论，高亮的评论具有额外的阴影效果。
+
 ### updateCountCallback `(count: number) => void`
 
 评论数量更新的调用的回调方法。
@@ -189,11 +253,13 @@ Github OAuth App 鉴权反向代理，支持 CORS。[为什么需要它？](http
 
 创建评论**成功时**调用的回调方法。
 
-## 主题样式
+## 主题
 
-通过设置 CSS 变量，您可以快速地将 Gitalk React 的主题颜色修改为适配您站点的样式。
+### 颜色
 
-当您引入浅色主题 `import 'gitalk-react/gitalk.css'` 时，默认的 CSS 变量如下：
+您可以通过设置 CSS 变量快速修改 Gitalk React 的主题颜色，以匹配您的站点风格。
+
+当您通过 `import 'gitalk-react/gitalk.css'` 引入浅色主题时，默认 CSS 变量如下：
 
 ```css
 .gt-container {
@@ -222,7 +288,7 @@ Github OAuth App 鉴权反向代理，支持 CORS。[为什么需要它？](http
 }
 ```
 
-引入深色主题 `import 'gitalk-react/gitalk-dark.css'` 时，默认的 CSS 变量如下：
+当通过 `import 'gitalk-react/gitalk-dark.css'` 引入深色主题时，默认 CSS 变量如下：
 
 ```css
 .gt-container {
@@ -251,9 +317,25 @@ Github OAuth App 鉴权反向代理，支持 CORS。[为什么需要它？](http
 }
 ```
 
-## 开发者
+### 动画
+
+评论的进入和退出使用原生 CSS 手风琴/淡入淡出动画，重新排序时使用 CSS transform 过渡。动画持续时间为 0.3 秒，并遵循 `prefers-reduced-motion` 偏好设置。动画库选项和默认选项导出已被移除；请在 CSS 中自定义 `.gt-comment-item`。
 
-在项目根目录新建 `.env.local` 文件，添加开发用环境变量如下：
+## 部署代理
+
+[内置的 Node 代理](./proxy-server/README.md)需要 Node.js 22 或更高版本，无需额外安装包。将 `proxy-server/.env.example` 复制为 `proxy-server/.env.local`，然后在服务器上设置 `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET` 和 `ALLOWED_ORIGIN`。Origin 必须与你的站点源完全匹配，不包含路径或尾部斜杠。
+
+```bash
+npm run start:proxy
+```
+
+本地开发时使用 `http://localhost:3000/oauth/access_token`。在生产环境中，应将代理置于 HTTPS 之后，并将组件的 `proxy` 设置为其公共端点。请禁用该端点的查询字符串日志记录和缓存，因为其 URL 包含一次性授权码。浏览器端的 `clientID` 必须与服务端的 OAuth App 一致。
+
+预览环境专门使用这种服务端模式。本地 Vite 开发会将 `/oauth/access_token` 转发到本地代理。对于静态预览部署，请在构建前将 `VITE_PROXY` 设置为已部署的 HTTPS 端点；GitHub Pages 无法托管 Node 代理。
+
+## 开发者指南
+
+在项目根目录新建 `.env.local` 文件，并添加如下开发环境变量：
 
 ```bash
 VITE_CLIENT_ID="YOUR_GITHUB_OAUTH_APP_CLIENT_ID"
@@ -265,10 +347,22 @@ VITE_ADMIN='["YOUR_GITHUB_USERNAME"]'
 
 ### 开发
 
+安装依赖：
+
+```bash
+pnpm install
+```
+
 在浏览器中调试开发：
 
 ```bash
-yarn dev
+pnpm run dev
+```
+
+运行测试：
+
+```bash
+pnpm run test
 ```
 
 ### 质量检查
@@ -276,22 +370,30 @@ yarn dev
 检查并修复代码的质量与格式问题：
 
 ```bash
-yarn lint
+pnpm run lint
 ```
 
 ### 构建
 
-打包构建组件：
+打包并构建组件：
 
 ```bash
-yarn build
+pnpm run build
 ```
 
+## 开发中的功能
+
+- [ ] 特性：支持在 Gitalk React 中编辑用户自己发布的评论。
+- [x] 特性：支持折叠过长的评论，允许用户点击展开。
+- [x] 重构：逐步移除非必要第三方库的依赖，以减小构建体积。
+- [x] 测试：添加自动化测试流程，增强项目健壮性。
+- [x] 杂项：部署[预览环境](https://lolipopj.github.io/gitalk-react/)。
+
 ## 许可证
 
 [MIT](./LICENSE)
 
 [npm-version-image]: https://img.shields.io/npm/v/gitalk-react.svg?style=flat-square
 [npm-version-url]: https://www.npmjs.com/package/gitalk-react
-[gzip-size]: https://img.badgesize.io/https://unpkg.com/gitalk-react/dist/gitalk.umd.cjs?compression=gzip&style=flat-square
-[gzip-url]: https://unpkg.com/gitalk-react/dist/gitalk.umd.cjs
+[gzip-size]: https://img.badgesize.io/https://unpkg.com/gitalk-react/dist/gitalk.browser.js?compression=gzip&style=flat-square
+[gzip-url]: https://unpkg.com/gitalk-react/dist/gitalk.browser.js

package/README.md

@@ -14,45 +14,55 @@ Developed for modern browsers, focusing on reducing build size and enhancing dev
 ## Differences
 
 - **Not compatible with older browsers**: Only guarantees compatibility with modern browsers that support [ES2020](https://caniuse.com/?feats=mdn-javascript_operators_optional_chaining,mdn-javascript_operators_nullish_coalescing,mdn-javascript_builtins_globalthis,es6-module-dynamic-import,bigint,mdn-javascript_builtins_promise_allsettled,mdn-javascript_builtins_string_matchall,mdn-javascript_statements_export_namespace,mdn-javascript_operators_import_meta).
-- **Depends on React runtime environment**: `react >= 16.8.0 && react-dom >= 16.8.0`.
 - **Some default values for parameters have changed**: Please pay attention when migrating to this component.
   - `id`: Gitalk uses `location.href` as the default value, while Gitalk React uses `location.host + location.pathname` as the default value, to avoid unexpected search parameters.
   - `defaultAuthor`: Can still be used. Gitalk React has added a new parameter `defaultUser` to set the default user for comments, keeping the field naming consistent with the GitHub API.
 
-## Features in Development
-
-- [ ] Feature: Support editing comments published by the user in Gitalk React.
-- [x] Feature: Support collapse overly long comments, allowing users to click to expand the comment.
-- [ ] refactor: Gradually remove dependencies on non-essential third-party libraries to reduce build size.
-- [ ] test: Add automated testing processes to enhance project robustness.
-- [x] chore: Deploy [preview environment](https://lolipopj.github.io/gitalk-react/).
-
 ## Quick Start
 
-### Installation
+### Node.js Project
 
 ```bash
 npm install gitalk-react
 ```
 
-### Usage
-
 Import styles and component into your project:
 
 ```tsx
 // Import light mode styles
 import 'gitalk-react/gitalk.css'
 // Or dark mode styles
-import 'gitalk-react/gitalk-dark.css'
+// import 'gitalk-react/gitalk-dark.css'
 
 import Gitalk from 'gitalk-react'
 ```
 
 Gitalk React relies on GitHub OAuth App for login authentication; you need to first [register an application](https://github.com/settings/applications/new). Please note that you must set your site domain as the value of the `Authorization callback URL` field, such as `https://yourdomain.com/site` or for development environments `http://localhost:5432`.
 
-When using the Gitalk React component, fill in the necessary configuration items:
+For a secure deployment with your own backend proxy server, use the following configurations:
+
+- `clientID`: The ID of your GitHub OAuth App.
+- `proxy`: The URL endpoint of your backend proxy server which securely handles the OAuth authorization code-to-token exchange. See [Proxy Deployment](#proxy-deployment).
+- `owner`: Your GitHub username.
+- `repo`: The name of your GitHub repository. It must be a public repository.
+- `admin`: A list of Gitalk React administrators; only those listed can initialize comment topics. This can include the owner and collaborators of the GitHub repository.
+
+```tsx
+<Gitalk
+  clientID="YOUR_GITHUB_OAUTH_APP_CLIENT_ID"
+  proxy="https://your-server.com/oauth/access_token"
+  owner="GITHUB_REPO_OWNER"
+  repo="GITHUB_REPO_NAME"
+  admin={['GITHUB_REPO_OWNER', 'GITHUB_REPO_COLLABORATOR']}
+/>
+```
+
+> [!CAUTION]
+> Providing `clientSecret` will make Gitalk downgrade the OAuth grant mode to the Implicit Grant Flow mode. This mode exposes the secret key to visitors and the relay, industry standards formally deprecate and discourage the mode.
 
-- `clientId`: The ID of your GitHub OAuth App.
+**Be aware of what you are doing.** For a legacy deployment with exposed secret key, use the following configurations:
+
+- `clientID`: The ID of your GitHub OAuth App.
 - `clientSecret`: The Secret key of your GitHub OAuth App.
 - `owner`: Your GitHub username.
 - `repo`: The name of your GitHub repository. It must be a public repository.
@@ -68,6 +78,67 @@ When using the Gitalk React component, fill in the necessary configuration items
 />
 ```
 
+Gitalk React is a **client component** and does **not support server-side rendering (SSR)**. It reads browser APIs during rendering. The source entry and both published JavaScript entry points carry `"use client"`; this marks the React client boundary but does not disable prerendering in SSR frameworks.
+
+In Next.js App Router, create a client wrapper and disable SSR for the dynamic import:
+
+```tsx
+'use client'
+
+import dynamic from 'next/dynamic'
+import type { GitalkProps } from 'gitalk-react'
+import 'gitalk-react/gitalk.css'
+
+const Gitalk = dynamic(() => import('gitalk-react'), { ssr: false })
+
+export default function Comments(props: GitalkProps) {
+  return <Gitalk {...props} />
+}
+```
+
+Render this wrapper with the configuration shown above. Other SSR frameworks must also load and mount Gitalk only in the browser.
+
+### Browser CDN
+
+Both browser builds expose a global `Gitalk` constructor. Load one build and the desired stylesheet; the examples below use the light theme. Use `dist/gitalk-dark.css` for the dark theme.
+
+For a page without React, use the full build, which includes React 19.3.1 and ReactDOM 19.3.1 and mounts with `createRoot`:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk-light.css"
+/>
+<div id="gitalk-container"></div>
+<script src="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk.browser.full.js"></script>
+<script>
+  const gitalk = new Gitalk({
+    clientID: 'YOUR_GITHUB_OAUTH_APP_CLIENT_ID',
+    proxy: 'https://your-server.com/oauth/access_token',
+    owner: 'GITHUB_REPO_OWNER',
+    repo: 'GITHUB_REPO_NAME',
+    admin: ['GITHUB_REPO_OWNER'],
+  })
+  gitalk.render('gitalk-container')
+</script>
+```
+
+Bare jsDelivr and unpkg package URLs select the full build.
+
+For a page that already provides matching global `React` and `ReactDOM` objects, use `gitalk.browser.js` instead of `gitalk.browser.full.js`. It uses `ReactDOM.createRoot` when available (React 18+) and otherwise uses `ReactDOM.render` / `ReactDOM.unmountComponentAtNode` (React 16/17). A complete script loading order for React 18 is:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/react@18.3.1/browser/react.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/react-dom@18.3.1/browser/react-dom.production.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/gitalk-react/dist/gitalk.browser.js"></script>
+```
+
+React installed inside an application bundle does not automatically provide these globals. Use the React component import for such applications, or explicitly expose the shared runtime before loading the browser build. With React 19, expose the `react-dom/client` module as `ReactDOM` so its `createRoot` is available; the `react-dom` module alone does not export `createRoot`. Loading the full build does not require or replace the page's React globals.
+
+`render(id)` accepts an element ID, without `#`. The element must exist before calling it. Calling it again updates the current mount; calling it with another ID unmounts the previous container first. Call `gitalk.destroy()` before removing the widget, such as during page navigation. The instance can render again after destruction.
+
+The constructor accepts the same options as the React component, prefer the `clientID` + `proxy` configuration above so the secret stays on the server. Neither browser build includes CSS automatically.
+
 ## Configuration
 
 ### clientID `string`
@@ -76,7 +147,9 @@ When using the Gitalk React component, fill in the necessary configuration items
 
 ### clientSecret `string`
 
-**Required**. The Secret key of your GitHub OAuth App.
+The Secret key of your GitHub OAuth App. When provided, Gitalk sends the authorization code, client ID and secret in a POST request through `proxy`, using `DEFAULT_PROXY` when `proxy` is omitted or empty. This mode exposes the secret in the browser and to the CORS relay.
+
+You should keep your OAuth App secret on the server. Omit `clientSecret` and provide a server-side `proxy` for secure deployments.
 
 ### owner `string`
 
@@ -120,7 +193,7 @@ The content of the comment topic.
 
 The language used by Gitalk React.
 
-Available languages include: `"de" | "en" | "es-ES" | "fa" | "fr" | "ja" | "ko" | "pl" | "ru" | "zh-CN" | "zh-TW"`.
+Available translations: `ar`, `bn`, `de`, `en`, `es`, `fa`, `fr`, `hi`, `ja`, `ko`, `pl`, `pt`, `ru`, `ur`, `zh-CN`, and `zh-TW`. BCP 47 regional tags such as `fr-FR`, `de-DE`, and `ja-JP` select the base translation. Chinese region and script tags preserve simplified/traditional Chinese (`zh-Hans` / `zh-Hant`). Unsupported or invalid tags use English. Relative comment dates use `Intl.RelativeTimeFormat` with the same resolved language.
 
 ### perPage `number = 10`
 
@@ -144,24 +217,11 @@ Whether to enable hotkeys like `cmd + enter` or `ctrl + enter` to publish commen
 
 Whether to enable full-screen overlay effects similar to Facebook's comment box.
 
-### flipMoveOptions `FlipMove.FlipMoveProps`
-
-Animation effects for the comment list.
-
-Default values (referenced effects can be found [here](https://github.com/joshwcomeau/react-flip-move/blob/master/documentation/enter_leave_animations.md)):
-
-```json
-{
-  "staggerDelayBy": 150,
-  "appearAnimation": "accordionVertical",
-  "enterAnimation": "accordionVertical",
-  "leaveAnimation": "accordionVertical"
-}
-```
+### proxy `string`
 
-### proxy `string = "https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token"`
+When `clientSecret` is provided, this is an optional CORS relay URL. It defaults to `https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token`. You can select another CORS service. Gitalk sends a POST request containing the code, client ID and secret; the relay solves the browser's cross-origin restriction while GitHub still validates the OAuth credentials.
 
-Reverse proxy for authenticating with Github OAuth App that supports CORS. [Why needed?](https://github.com/isaacs/github/issues/330)
+When `clientSecret` is omitted, `proxy` is required and must point to your server-side OAuth exchange endpoint. Gitalk sends a GET request with only the authorization code as an encoded `code` query parameter, preserving existing query parameters. The server stores the credentials and returns JSON `{ "access_token": "..." }`.
 
 ### defaultUser `{ avatar_url: string; login: string; html_url: string }`
 
@@ -181,6 +241,10 @@ The default user used when the comment user does not exist.
 
 When the height of the comment exceeds `${collapsedHeight}px`, it will automatically collapse to `${collapsedHeight}px`.
 
+### highlightAdminComment `boolean = true`
+
+Whether to highlight comments published by administrators, which have additional shadow effects.
+
 ### updateCountCallback `(count: number) => void`
 
 Callback method invoked when updating the number of comments.
@@ -189,7 +253,9 @@ Callback method invoked when updating the number of comments.
 
 Callback method invoked when a comment is successfully created.
 
-## Theme Styles
+## Theme
+
+### Color
 
 You can quickly modify Gitalk React's theme colors to match your site's style by setting CSS variables.
 
@@ -251,13 +317,29 @@ When importing dark theme with `import 'gitalk-react/gitalk-dark.css'`, the defa
 }
 ```
 
+### Animation
+
+Comments use native CSS accordion/fade animations for entry and exit, and CSS transform transitions when reordered. Animations last 0.3 seconds and respect `prefers-reduced-motion`. The animation library options and default-options export have been removed; customize `.gt-comment-item` in CSS.
+
+## Proxy Deployment
+
+The [included Node proxy](./proxy-server/README.md) requires Node.js 22 or newer and no additional packages. Copy `proxy-server/.env.example` to `proxy-server/.env.local`, then set `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` and `ALLOWED_ORIGIN` on the server. The origin must match your site origin exactly, without a path or trailing slash.
+
+```bash
+npm run start:proxy
+```
+
+Use `http://localhost:3000/oauth/access_token` locally. In production, put the proxy behind HTTPS and set the component's `proxy` to its public endpoint. Disable query-string logging and caching for this endpoint, since its URL contains a one-time authorization code. The browser `clientID` must match the server's OAuth App.
+
+The preview uses this server-side mode exclusively. Local Vite development forwards `/oauth/access_token` to the local proxy. For a static preview deployment, set `VITE_PROXY` to a deployed HTTPS endpoint before building; GitHub Pages cannot host the Node proxy.
+
 ## Developer
 
 Create a `.env.local` file in your project's root directory and add development environment variables as follows:
 
 ```bash
 VITE_CLIENT_ID="YOUR_GITHUB_OAUTH_APP_CLIENT_ID"
-VITE_CLIENT_SECRET="YOUR_GITHUB_OAUTH_APP_CLIENT_SECRET"
+VITE_PROXY="http://localhost:3000/oauth/access_token"
 VITE_REPO_OWNER="YOUR_GITHUB_USERNAME"
 VITE_REPO_NAME="YOUR_REPO_NAME"
 VITE_ADMIN='["YOUR_GITHUB_USERNAME"]'
@@ -265,10 +347,22 @@ VITE_ADMIN='["YOUR_GITHUB_USERNAME"]'
 
 ### Development
 
+Install dependencies:
+
+```bash
+pnpm install
+```
+
 Debug in your browser during development:
 
 ```bash
-yarn dev
+pnpm run dev
+```
+
+Run test:
+
+```bash
+pnpm run test
 ```
 
 ### Lint
@@ -276,7 +370,7 @@ yarn dev
 Check and fix code quality and formatting issues:
 
 ```bash
-yarn lint
+pnpm run lint
 ```
 
 ### Production
@@ -284,14 +378,22 @@ yarn lint
 Bundle and build components:
 
 ```bash
-yarn build
+pnpm run build
 ```
 
+## Features under Development
+
+- [ ] Feature: Support editing comments published by the user in Gitalk React.
+- [x] Feature: Support collapse overly long comments, allowing users to click to expand the comment.
+- [x] refactor: Gradually remove dependencies on non-essential third-party libraries to reduce build size.
+- [x] test: Add automated testing processes to enhance project robustness.
+- [x] chore: Deploy [preview environment](https://lolipopj.github.io/gitalk-react/).
+
 ## License
 
 [MIT](./LICENSE)
 
 [npm-version-image]: https://img.shields.io/npm/v/gitalk-react.svg?style=flat-square
 [npm-version-url]: https://www.npmjs.com/package/gitalk-react
-[gzip-size]: https://img.badgesize.io/https://unpkg.com/gitalk-react/dist/gitalk.umd.cjs?compression=gzip&style=flat-square
-[gzip-url]: https://unpkg.com/gitalk-react/dist/gitalk.umd.cjs
+[gzip-size]: https://img.badgesize.io/https://unpkg.com/gitalk-react/dist/gitalk.browser.js?compression=gzip&style=flat-square
+[gzip-url]: https://unpkg.com/gitalk-react/dist/gitalk.browser.js