appwrite-typescript by appwrite/agent-skills
npx skills add https://github.com/appwrite/agent-skills --skill appwrite-typescript# Web
npm install appwrite
# React Native
npm install react-native-appwrite
# Node.js / Deno
npm install node-appwrite
// Web
import { Client, Account, TablesDB, Storage, ID, Query } from 'appwrite';
// React Native
import { Client, Account, TablesDB, Storage, ID, Query } from 'react-native-appwrite';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]');
import { Client, Users, TablesDB, Storage, Functions, ID, Query } from 'node-appwrite';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject(process.env.APPWRITE_PROJECT_ID)
.setKey(process.env.APPWRITE_API_KEY);
const account = new Account(client);
// 邮箱注册
await account.create({
userId: ID.unique(),
email: 'user@example.com',
password: 'password123',
name: 'User Name'
});
// 邮箱登录
const session = await account.createEmailPasswordSession({
email: 'user@example.com',
password: 'password123'
});
// OAuth 登录(Web)
account.createOAuth2Session({
provider: OAuthProvider.Github,
success: 'https://example.com/success',
failure: 'https://example.com/fail',
scopes: ['repo', 'user'] // 可选 — 特定于提供者的作用域
});
// 获取当前用户
const user = await account.get();
// 登出
await account.deleteSession({ sessionId: 'current' });
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
重要提示:
createOAuth2Session()在 React Native 中不起作用。你必须使用createOAuth2Token()配合深度链接。
安装所需的依赖项:
npx expo install react-native-appwrite react-native-url-polyfill
npm install expo-auth-session expo-web-browser expo-linking
在你的 app.json 中设置 URL 方案:
{
"expo": {
"scheme": "appwrite-callback-[PROJECT_ID]"
}
}
import { Client, Account, OAuthProvider } from 'react-native-appwrite';
import { makeRedirectUri } from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]');
const account = new Account(client);
async function oauthLogin(provider: OAuthProvider) {
// 创建适用于所有 Expo 环境的深度链接
const deepLink = new URL(makeRedirectUri({ preferLocalhost: true }));
const scheme = `${deepLink.protocol}//`; // 例如 'exp://' 或 'appwrite-callback-[PROJECT_ID]://'
// 获取 OAuth 登录 URL
const loginUrl = await account.createOAuth2Token({
provider,
success: `${deepLink}`,
failure: `${deepLink}`,
});
// 打开浏览器并监听方案重定向
const result = await WebBrowser.openAuthSessionAsync(`${loginUrl}`, scheme);
if (result.type !== 'success') return;
// 从重定向 URL 中提取凭据
const url = new URL(result.url);
const secret = url.searchParams.get('secret');
const userId = url.searchParams.get('userId');
// 使用 OAuth 凭据创建会话
await account.createSession({ userId, secret });
}
// 用法
await oauthLogin(OAuthProvider.Github);
await oauthLogin(OAuthProvider.Google);
const users = new Users(client);
// 创建用户
const user = await users.create({
userId: ID.unique(),
email: 'user@example.com',
password: 'password123',
name: 'User Name'
});
// 列出用户
const list = await users.list({ queries: [Query.limit(25)] });
// 获取用户
const fetched = await users.get({ userId: '[USER_ID]' });
// 删除用户
await users.delete({ userId: '[USER_ID]' });
注意: 所有新代码请使用
TablesDB(而非已弃用的Databases类)。仅当现有代码库已依赖它或用户明确要求时才使用Databases。提示: 对于所有 SDK 方法调用,优先使用对象参数调用风格(例如,
{ databaseId: '...' })。仅当现有代码库已使用位置参数或用户明确要求时才使用位置参数。
const tablesDB = new TablesDB(client);
// 创建数据库(仅限服务器端)
const db = await tablesDB.create({ databaseId: ID.unique(), name: 'My Database' });
// 创建表(仅限服务器端)
const col = await tablesDB.createTable({
databaseId: '[DATABASE_ID]',
tableId: ID.unique(),
name: 'My Table'
});
// 创建行
const doc = await tablesDB.createRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: ID.unique(),
data: { title: 'Hello World', content: 'Example content' }
});
// 使用查询列出行
const results = await tablesDB.listRows({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
queries: [Query.equal('status', 'active'), Query.limit(10)]
});
// 获取行
const row = await tablesDB.getRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]'
});
// 更新行
await tablesDB.updateRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]',
data: { title: 'Updated Title' }
});
// 删除行
await tablesDB.deleteRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]'
});
注意: 旧版
string类型已弃用。所有新列请使用明确的列类型。
| 类型 | 最大字符数 | 索引 | 存储 |
|---|---|---|---|
varchar | 16,383 | 完整索引(如果大小 ≤ 768) | 行内存储 |
text | 16,383 | 仅前缀索引 | 页外存储 |
mediumtext | 4,194,303 | 仅前缀索引 | 页外存储 |
longtext | 1,073,741,823 | 仅前缀索引 | 页外存储 |
varchar 存储在行内,并计入 64 KB 的行大小限制。适用于短小、需要索引的字段,如姓名、slug 或标识符。
text、mediumtext 和 longtext 存储在页外(行中仅保留一个 20 字节的指针),因此它们不消耗行大小预算。这些类型不需要指定 size。
// 使用明确的字符串列类型创建表 await tablesDB.createTable({ databaseId: '[DATABASE_ID]', tableId: ID.unique(), name: 'articles', columns: [ { key: 'title', type: 'varchar', size: 255, required: true }, // 行内存储,可完全索引 { key: 'summary', type: 'text', required: false }, // 页外存储,仅前缀索引 { key: 'body', type: 'mediumtext', required: false }, // 最多约 4 M 字符 { key: 'raw_data', type: 'longtext', required: false }, // 最多约 1 B 字符 ] });
import { Models } from 'appwrite';
// 服务器端:从 'node-appwrite' 导入
// 为你的行数据定义一个类型化接口
interface Todo {
title: string;
done: boolean;
priority: number;
}
// listRows 默认返回 Models.DocumentList<Models.Document>
// 使用类型转换或泛型来获得类型化结果
const results = await tablesDB.listRows({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
queries: [Query.equal('done', false)]
});
// 每个文档除了你的数据外,还包含内置字段
const doc = results.documents[0];
doc.$id; // string — 唯一的行 ID
doc.$createdAt; // string — ISO 8601 创建时间戳
doc.$updatedAt; // string — ISO 8601 更新时间戳
doc.$permissions; // string[] — 权限字符串
doc.$databaseId; // string
doc.$collectionId; // string
// 常见的模型类型
// Models.User<Preferences> — 用户账户
// Models.Session — 身份验证会话
// Models.File — 存储文件元数据
// Models.Team — 团队对象
// Models.Execution — 函数执行结果
// Models.DocumentList<T> — 带总数统计的分页列表
// 过滤
Query.equal('field', 'value') // field == value(或传递数组用于 IN 查询)
Query.notEqual('field', 'value') // field != value
Query.lessThan('field', 100) // field < value
Query.lessThanEqual('field', 100) // field <= value
Query.greaterThan('field', 100) // field > value
Query.greaterThanEqual('field', 100) // field >= value
Query.between('field', 1, 100) // 1 <= field <= 100
Query.isNull('field') // field 为 null
Query.isNotNull('field') // field 不为 null
Query.startsWith('field', 'prefix') // 字符串以 prefix 开头
Query.endsWith('field', 'suffix') // 字符串以 suffix 结尾
Query.contains('field', 'substring') // 字符串/数组包含 value
Query.search('field', 'keywords') // 全文搜索(需要全文索引)
// 排序
Query.orderAsc('field') // 升序排序
Query.orderDesc('field') // 降序排序
// 分页
Query.limit(25) // 返回的最大行数(默认 25,最大 100)
Query.offset(0) // 跳过 N 行
Query.cursorAfter('[ROW_ID]') // 在此行 ID 之后分页(适用于大型数据集的首选方法)
Query.cursorBefore('[ROW_ID]') // 在此行 ID 之前分页
// 选择字段
Query.select(['field1', 'field2']) // 仅返回指定字段
// 逻辑运算
Query.or([Query.equal('a', 1), Query.equal('b', 2)]) // OR 条件
Query.and([Query.greaterThan('age', 18), Query.lessThan('age', 65)]) // 显式 AND(默认情况下查询是 AND 关系)
const storage = new Storage(client);
// 上传文件(客户端 — 来自文件输入)
const file = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: document.getElementById('file-input').files[0]
});
// 上传文件(服务器端 — 来自路径)
import { InputFile } from 'node-appwrite/file';
const file2 = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: InputFile.fromPath('/path/to/file.png', 'file.png')
});
// 列出文件
const files = await storage.listFiles({ bucketId: '[BUCKET_ID]' });
// 获取文件预览(图片)
const preview = storage.getFilePreview({
bucketId: '[BUCKET_ID]',
fileId: '[FILE_ID]',
width: 300,
height: 300
});
// 下载文件
const download = await storage.getFileDownload({
bucketId: '[BUCKET_ID]',
fileId: '[FILE_ID]'
});
// 删除文件
await storage.deleteFile({ bucketId: '[BUCKET_ID]', fileId: '[FILE_ID]' });
import { InputFile } from 'node-appwrite/file';
InputFile.fromPath('/path/to/file.png', 'file.png') // 来自文件系统路径
InputFile.fromBuffer(buffer, 'file.png') // 来自 Buffer
InputFile.fromStream(readableStream, 'file.png', size) // 来自 ReadableStream(需要 size 参数,单位为字节)
InputFile.fromPlainText('Hello world', 'hello.txt') // 来自字符串内容
const teams = new Teams(client);
// 创建团队
const team = await teams.create({ teamId: ID.unique(), name: 'Engineering' });
// 列出团队
const list = await teams.list();
// 创建成员资格(通过邮箱邀请用户)
const membership = await teams.createMembership({
teamId: '[TEAM_ID]',
roles: ['editor'],
email: 'user@example.com',
});
// 列出成员资格
const members = await teams.listMemberships({ teamId: '[TEAM_ID]' });
// 更新成员资格角色
await teams.updateMembership({
teamId: '[TEAM_ID]',
membershipId: '[MEMBERSHIP_ID]',
roles: ['admin'],
});
// 删除团队
await teams.delete({ teamId: '[TEAM_ID]' });
基于角色的访问控制: 在设置权限时,使用
Role.team('[TEAM_ID]')表示所有团队成员,或使用Role.team('[TEAM_ID]', 'editor')表示特定的团队角色。
import { Realtime, Channel } from 'appwrite';
const realtime = new Realtime(client);
// 订阅行变更
const subscription = await realtime.subscribe(
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row(),
(response) => {
console.log(response.events); // 例如 ['tablesdb.*.tables.*.rows.*.create']
console.log(response.payload); // 受影响的资源
}
);
// 订阅特定行
await realtime.subscribe(
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row('[ROW_ID]'),
(response) => { /* ... */ }
);
// 订阅多个频道
await realtime.subscribe([
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row(),
Channel.bucket('[BUCKET_ID]').file(),
], (response) => { /* ... */ });
// 取消订阅
await subscription.close();
可用频道:
| 频道 | 描述 |
|---|---|
account | 已认证用户账户的变更 |
tablesdb.[DB_ID].tables.[TABLE_ID].rows | 表中的所有行 |
tablesdb.[DB_ID].tables.[TABLE_ID].rows.[ROW_ID] | 特定行 |
buckets.[BUCKET_ID].files | 存储桶中的所有文件 |
buckets.[BUCKET_ID].files.[FILE_ID] | 特定文件 |
teams | 用户所属团队的变更 |
teams.[TEAM_ID] | 特定团队的变更 |
memberships | 用户团队成员资格的变更 |
memberships.[MEMBERSHIP_ID] | 特定成员资格 |
functions.[FUNCTION_ID].executions | 函数执行的更新 |
response 对象包含:events(事件字符串数组)、payload(受影响的资源)、channels(匹配的频道)和 timestamp(ISO 8601 时间戳)。
const functions = new Functions(client);
// 执行函数
const execution = await functions.createExecution({
functionId: '[FUNCTION_ID]',
body: JSON.stringify({ key: 'value' })
});
// 列出执行记录
const executions = await functions.listExecutions({ functionId: '[FUNCTION_ID]' });
部署你自己的 Appwrite 函数时,入口点文件必须导出一个默认的异步函数:
// src/main.js(或 src/main.ts)
export default async ({ req, res, log, error }) => {
// 请求属性
// req.body — 原始请求体(字符串)
// req.bodyJson — 解析后的 JSON 请求体(对象,如果不是 JSON 则为 undefined)
// req.headers — 请求头(对象)
// req.method — HTTP 方法(GET, POST, PUT, DELETE, PATCH)
// req.path — URL 路径(例如 '/hello')
// req.query — 解析后的查询参数(对象)
// req.queryString — 原始查询字符串
log('Processing request: ' + req.method + ' ' + req.path);
if (req.method === 'GET') {
return res.json({ message: 'Hello from Appwrite Function!' });
}
const data = req.bodyJson;
if (!data?.name) {
error('Missing name field');
return res.json({ error: 'Name is required' }, 400);
}
// 响应方法
return res.json({ success: true }); // JSON(自动设置 Content-Type)
// return res.text('Hello'); // 纯文本
// return res.empty(); // 204 No Content
// return res.redirect('https://example.com'); // 302 重定向
// return res.send('data', 200, { 'X-Custom': '1' }); // 自定义请求体、状态码、请求头
};
SSR 应用(Next.js, SvelteKit, Nuxt, Remix, Astro)使用服务器 SDK(node-appwrite)来处理身份验证。你需要两个客户端:
管理员客户端 — 使用 API 密钥,创建会话,绕过速率限制(可重用的单例)
会话客户端 — 使用会话 Cookie,代表用户操作(每个请求创建,切勿共享)
import { Client, Account, OAuthProvider } from 'node-appwrite';
// 管理员客户端(可重用) const adminClient = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]') .setKey(process.env.APPWRITE_API_KEY);
// 会话客户端(每个请求创建) const sessionClient = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]');
const session = req.cookies['a_session_[PROJECT_ID]']; if (session) { sessionClient.setSession(session); }
app.post('/login', async (req, res) => {
const account = new Account(adminClient);
const session = await account.createEmailPasswordSession({
email: req.body.email,
password: req.body.password,
});
// Cookie 名称必须为 a_session_<PROJECT_ID>
res.cookie('a_session_[PROJECT_ID]', session.secret, {
httpOnly: true,
secure: true,
sameSite: 'strict',
expires: new Date(session.expire),
path: '/',
});
res.json({ success: true });
});
app.get('/user', async (req, res) => {
const session = req.cookies['a_session_[PROJECT_ID]'];
if (!session) return res.status(401).json({ error: 'Unauthorized' });
// 每个请求创建一个新的会话客户端
const sessionClient = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]')
.setSession(session);
const account = new Account(sessionClient);
const user = await account.get();
res.json(user);
});
// 步骤 1:重定向到 OAuth 提供者
app.get('/oauth', async (req, res) => {
const account = new Account(adminClient);
const redirectUrl = await account.createOAuth2Token({
provider: OAuthProvider.Github,
success: 'https://example.com/oauth/success',
failure: 'https://example.com/oauth/failure',
});
res.redirect(redirectUrl);
});
// 步骤 2:处理回调 — 将令牌交换为会话
app.get('/oauth/success', async (req, res) => {
const account = new Account(adminClient);
const session = await account.createSession({
userId: req.query.userId,
secret: req.query.secret,
});
res.cookie('a_session_[PROJECT_ID]', session.secret, {
httpOnly: true, secure: true, sameSite: 'strict',
expires: new Date(session.expire), path: '/',
});
res.json({ success: true });
});
Cookie 安全性: 始终使用
httpOnly、secure和sameSite: 'strict'来防止 XSS 攻击。Cookie 名称必须为a_session_<PROJECT_ID>。
转发用户代理: 调用
sessionClient.setForwardedUserAgent(req.headers['user-agent'])来记录最终用户的浏览器信息,用于调试和安全目的。
import { AppwriteException } from 'appwrite';
// 服务器端:从 'node-appwrite' 导入
try {
const doc = await tablesDB.getRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]',
});
} catch (err) {
if (err instanceof AppwriteException) {
console.log(err.message); // 人类可读的错误信息
console.log(err.code); // HTTP 状态码(数字)
console.log(err.type); // Appwrite 错误类型字符串(例如 'document_not_found')
console.log(err.response); // 完整的响应体(对象)
}
}
常见错误代码:
| 代码 | 含义 |
|---|---|
401 | 未授权 — 缺少或无效的会话/API 密钥 |
403 | 禁止访问 — 对此操作的权限不足 |
404 | 未找到 — 资源不存在 |
409 | 冲突 — 重复的 ID 或唯一约束冲突 |
429 | 速率限制 — 请求过多,退避后重试 |
Appwrite 使用权限字符串来控制对资源的访问。每个权限将一个操作(read、update、delete、create,或授予创建 + 更新 + 删除权限的 write)与一个角色目标配对。默认情况下,除非在文档/文件级别明确设置权限,或从集合/存储桶设置继承权限,否则没有用户拥有访问权限。权限是使用 Permission 和 Role 辅助函数构建的字符串数组。
import { Permission, Role } from 'appwrite';
// 服务器端:从 'node-appwrite' 导入
const doc = await tablesDB.createRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: ID.unique(),
data: { title: 'Hello World' },
permissions: [
Permission.read(Role.user('[USER_ID]')), // 特定用户可以读取
Permission.update(Role.user('[USER_ID]')), // 特定用户可以更新
Permission.read(Role.team('[TEAM_ID]')), // 所有团队成员可以读取
Permission.read(Role.any()), // 任何人(包括访客)可以读取
]
});
const file = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: document.getElementById('file-input').files[0],
permissions: [
Permission.read(Role.any()),
Permission.update(Role.user('[USER_ID]')),
Permission.delete(Role.user('[USER_ID]')),
]
});
何时设置权限: 当你需要每个资源的访问控制时,在文档/文件级别设置权限。如果集合中的所有文档共享相同的规则,则在集合/存储桶级别配置权限,并将文档权限留空。
常见错误:
- 忘记设置权限 — 资源对所有用户(包括创建者)都变得不可访问
Role.any()与write/update/delete一起使用 — 允许任何用户,包括未认证的访客,修改或删除资源- 在敏感数据上使用
Permission.read(Role.any())— 使资源公开可读
每周安装次数
58
代码仓库
GitHub 星标数
6
首次出现
2026年2月16日
安全审计
安装于
codex58
opencode58
gemini-cli57
github-copilot54
kimi-cli53
amp53
# Web
npm install appwrite
# React Native
npm install react-native-appwrite
# Node.js / Deno
npm install node-appwrite
// Web
import { Client, Account, TablesDB, Storage, ID, Query } from 'appwrite';
// React Native
import { Client, Account, TablesDB, Storage, ID, Query } from 'react-native-appwrite';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]');
import { Client, Users, TablesDB, Storage, Functions, ID, Query } from 'node-appwrite';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject(process.env.APPWRITE_PROJECT_ID)
.setKey(process.env.APPWRITE_API_KEY);
const account = new Account(client);
// Email signup
await account.create({
userId: ID.unique(),
email: 'user@example.com',
password: 'password123',
name: 'User Name'
});
// Email login
const session = await account.createEmailPasswordSession({
email: 'user@example.com',
password: 'password123'
});
// OAuth login (Web)
account.createOAuth2Session({
provider: OAuthProvider.Github,
success: 'https://example.com/success',
failure: 'https://example.com/fail',
scopes: ['repo', 'user'] // optional — provider-specific scopes
});
// Get current user
const user = await account.get();
// Logout
await account.deleteSession({ sessionId: 'current' });
Important:
createOAuth2Session()does not work on React Native. You must usecreateOAuth2Token()with deep linking instead.
Install the required dependencies:
npx expo install react-native-appwrite react-native-url-polyfill
npm install expo-auth-session expo-web-browser expo-linking
Set the URL scheme in your app.json:
{
"expo": {
"scheme": "appwrite-callback-[PROJECT_ID]"
}
}
import { Client, Account, OAuthProvider } from 'react-native-appwrite';
import { makeRedirectUri } from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]');
const account = new Account(client);
async function oauthLogin(provider: OAuthProvider) {
// Create deep link that works across Expo environments
const deepLink = new URL(makeRedirectUri({ preferLocalhost: true }));
const scheme = `${deepLink.protocol}//`; // e.g. 'exp://' or 'appwrite-callback-[PROJECT_ID]://'
// Get the OAuth login URL
const loginUrl = await account.createOAuth2Token({
provider,
success: `${deepLink}`,
failure: `${deepLink}`,
});
// Open browser and listen for the scheme redirect
const result = await WebBrowser.openAuthSessionAsync(`${loginUrl}`, scheme);
if (result.type !== 'success') return;
// Extract credentials from the redirect URL
const url = new URL(result.url);
const secret = url.searchParams.get('secret');
const userId = url.searchParams.get('userId');
// Create session with the OAuth credentials
await account.createSession({ userId, secret });
}
// Usage
await oauthLogin(OAuthProvider.Github);
await oauthLogin(OAuthProvider.Google);
const users = new Users(client);
// Create user
const user = await users.create({
userId: ID.unique(),
email: 'user@example.com',
password: 'password123',
name: 'User Name'
});
// List users
const list = await users.list({ queries: [Query.limit(25)] });
// Get user
const fetched = await users.get({ userId: '[USER_ID]' });
// Delete user
await users.delete({ userId: '[USER_ID]' });
Note: Use
TablesDB(not the deprecatedDatabasesclass) for all new code. Only useDatabasesif the existing codebase already relies on it or the user explicitly requests it.Tip: Prefer the object-params calling style (e.g.,
{ databaseId: '...' }) for all SDK method calls. Only use positional arguments if the existing codebase already uses them or the user explicitly requests it.
const tablesDB = new TablesDB(client);
// Create database (server-side only)
const db = await tablesDB.create({ databaseId: ID.unique(), name: 'My Database' });
// Create table (server-side only)
const col = await tablesDB.createTable({
databaseId: '[DATABASE_ID]',
tableId: ID.unique(),
name: 'My Table'
});
// Create row
const doc = await tablesDB.createRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: ID.unique(),
data: { title: 'Hello World', content: 'Example content' }
});
// List rows with query
const results = await tablesDB.listRows({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
queries: [Query.equal('status', 'active'), Query.limit(10)]
});
// Get row
const row = await tablesDB.getRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]'
});
// Update row
await tablesDB.updateRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]',
data: { title: 'Updated Title' }
});
// Delete row
await tablesDB.deleteRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]'
});
Note: The legacy
stringtype is deprecated. Use explicit column types for all new columns.
| Type | Max characters | Indexing | Storage |
|---|---|---|---|
varchar | 16,383 | Full index (if size ≤ 768) | Inline in row |
text | 16,383 | Prefix only | Off-page |
mediumtext | 4,194,303 | Prefix only | Off-page |
longtext | 1,073,741,823 | Prefix only | Off-page |
varchar is stored inline and counts towards the 64 KB row size limit. Prefer for short, indexed fields like names, slugs, or identifiers.
text, mediumtext, and longtext are stored off-page (only a 20-byte pointer lives in the row), so they don't consume the row size budget. size is not required for these types.
// Create table with explicit string column types await tablesDB.createTable({ databaseId: '[DATABASE_ID]', tableId: ID.unique(), name: 'articles', columns: [ { key: 'title', type: 'varchar', size: 255, required: true }, // inline, fully indexable { key: 'summary', type: 'text', required: false }, // off-page, prefix index only { key: 'body', type: 'mediumtext', required: false }, // up to ~4 M chars { key: 'raw_data', type: 'longtext', required: false }, // up to ~1 B chars ] });
import { Models } from 'appwrite';
// Server-side: import from 'node-appwrite'
// Define a typed interface for your row data
interface Todo {
title: string;
done: boolean;
priority: number;
}
// listRows returns Models.DocumentList<Models.Document> by default
// Cast or use generics for typed results
const results = await tablesDB.listRows({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
queries: [Query.equal('done', false)]
});
// Each document includes built-in fields alongside your data
const doc = results.documents[0];
doc.$id; // string — unique row ID
doc.$createdAt; // string — ISO 8601 creation timestamp
doc.$updatedAt; // string — ISO 8601 update timestamp
doc.$permissions; // string[] — permission strings
doc.$databaseId; // string
doc.$collectionId; // string
// Common model types
// Models.User<Preferences> — user account
// Models.Session — auth session
// Models.File — storage file metadata
// Models.Team — team object
// Models.Execution — function execution result
// Models.DocumentList<T> — paginated list with total count
// Filtering
Query.equal('field', 'value') // field == value (or pass array for IN)
Query.notEqual('field', 'value') // field != value
Query.lessThan('field', 100) // field < value
Query.lessThanEqual('field', 100) // field <= value
Query.greaterThan('field', 100) // field > value
Query.greaterThanEqual('field', 100) // field >= value
Query.between('field', 1, 100) // 1 <= field <= 100
Query.isNull('field') // field is null
Query.isNotNull('field') // field is not null
Query.startsWith('field', 'prefix') // string starts with prefix
Query.endsWith('field', 'suffix') // string ends with suffix
Query.contains('field', 'substring') // string/array contains value
Query.search('field', 'keywords') // full-text search (requires full-text index)
// Sorting
Query.orderAsc('field') // sort ascending
Query.orderDesc('field') // sort descending
// Pagination
Query.limit(25) // max rows returned (default 25, max 100)
Query.offset(0) // skip N rows
Query.cursorAfter('[ROW_ID]') // paginate after this row ID (preferred for large datasets)
Query.cursorBefore('[ROW_ID]') // paginate before this row ID
// Selection
Query.select(['field1', 'field2']) // return only specified fields
// Logical
Query.or([Query.equal('a', 1), Query.equal('b', 2)]) // OR condition
Query.and([Query.greaterThan('age', 18), Query.lessThan('age', 65)]) // explicit AND (queries are AND by default)
const storage = new Storage(client);
// Upload file (client-side — from file input)
const file = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: document.getElementById('file-input').files[0]
});
// Upload file (server-side — from path)
import { InputFile } from 'node-appwrite/file';
const file2 = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: InputFile.fromPath('/path/to/file.png', 'file.png')
});
// List files
const files = await storage.listFiles({ bucketId: '[BUCKET_ID]' });
// Get file preview (image)
const preview = storage.getFilePreview({
bucketId: '[BUCKET_ID]',
fileId: '[FILE_ID]',
width: 300,
height: 300
});
// Download file
const download = await storage.getFileDownload({
bucketId: '[BUCKET_ID]',
fileId: '[FILE_ID]'
});
// Delete file
await storage.deleteFile({ bucketId: '[BUCKET_ID]', fileId: '[FILE_ID]' });
import { InputFile } from 'node-appwrite/file';
InputFile.fromPath('/path/to/file.png', 'file.png') // from filesystem path
InputFile.fromBuffer(buffer, 'file.png') // from Buffer
InputFile.fromStream(readableStream, 'file.png', size) // from ReadableStream (size in bytes required)
InputFile.fromPlainText('Hello world', 'hello.txt') // from string content
const teams = new Teams(client);
// Create team
const team = await teams.create({ teamId: ID.unique(), name: 'Engineering' });
// List teams
const list = await teams.list();
// Create membership (invite a user by email)
const membership = await teams.createMembership({
teamId: '[TEAM_ID]',
roles: ['editor'],
email: 'user@example.com',
});
// List memberships
const members = await teams.listMemberships({ teamId: '[TEAM_ID]' });
// Update membership roles
await teams.updateMembership({
teamId: '[TEAM_ID]',
membershipId: '[MEMBERSHIP_ID]',
roles: ['admin'],
});
// Delete team
await teams.delete({ teamId: '[TEAM_ID]' });
Role-based access: Use
Role.team('[TEAM_ID]')for all team members orRole.team('[TEAM_ID]', 'editor')for a specific team role when setting permissions.
import { Realtime, Channel } from 'appwrite';
const realtime = new Realtime(client);
// Subscribe to row changes
const subscription = await realtime.subscribe(
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row(),
(response) => {
console.log(response.events); // e.g. ['tablesdb.*.tables.*.rows.*.create']
console.log(response.payload); // the affected resource
}
);
// Subscribe to a specific row
await realtime.subscribe(
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row('[ROW_ID]'),
(response) => { /* ... */ }
);
// Subscribe to multiple channels
await realtime.subscribe([
Channel.tablesdb('[DATABASE_ID]').table('[TABLE_ID]').row(),
Channel.bucket('[BUCKET_ID]').file(),
], (response) => { /* ... */ });
// Unsubscribe
await subscription.close();
Available channels:
| Channel | Description |
|---|---|
account | Changes to the authenticated user's account |
tablesdb.[DB_ID].tables.[TABLE_ID].rows | All rows in a table |
tablesdb.[DB_ID].tables.[TABLE_ID].rows.[ROW_ID] | A specific row |
buckets.[BUCKET_ID].files | All files in a bucket |
buckets.[BUCKET_ID].files.[FILE_ID] | A specific file |
teams |
The response object includes: events (array of event strings), payload (the affected resource), channels (channels matched), and timestamp (ISO 8601).
const functions = new Functions(client);
// Execute function
const execution = await functions.createExecution({
functionId: '[FUNCTION_ID]',
body: JSON.stringify({ key: 'value' })
});
// List executions
const executions = await functions.listExecutions({ functionId: '[FUNCTION_ID]' });
When deploying your own Appwrite Function, the entry point file must export a default async function:
// src/main.js (or src/main.ts)
export default async ({ req, res, log, error }) => {
// Request properties
// req.body — raw request body (string)
// req.bodyJson — parsed JSON body (object, or undefined if not JSON)
// req.headers — request headers (object)
// req.method — HTTP method (GET, POST, PUT, DELETE, PATCH)
// req.path — URL path (e.g. '/hello')
// req.query — parsed query parameters (object)
// req.queryString — raw query string
log('Processing request: ' + req.method + ' ' + req.path);
if (req.method === 'GET') {
return res.json({ message: 'Hello from Appwrite Function!' });
}
const data = req.bodyJson;
if (!data?.name) {
error('Missing name field');
return res.json({ error: 'Name is required' }, 400);
}
// Response methods
return res.json({ success: true }); // JSON (sets Content-Type automatically)
// return res.text('Hello'); // plain text
// return res.empty(); // 204 No Content
// return res.redirect('https://example.com'); // 302 Redirect
// return res.send('data', 200, { 'X-Custom': '1' }); // custom body, status, headers
};
SSR apps (Next.js, SvelteKit, Nuxt, Remix, Astro) use the server SDK (node-appwrite) to handle auth. You need two clients:
Admin client — uses an API key, creates sessions, bypasses rate limits (reusable singleton)
Session client — uses a session cookie, acts on behalf of a user (create per-request, never share)
import { Client, Account, OAuthProvider } from 'node-appwrite';
// Admin client (reusable) const adminClient = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]') .setKey(process.env.APPWRITE_API_KEY);
// Session client (create per-request) const sessionClient = new Client() .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]');
const session = req.cookies['a_session_[PROJECT_ID]']; if (session) { sessionClient.setSession(session); }
app.post('/login', async (req, res) => {
const account = new Account(adminClient);
const session = await account.createEmailPasswordSession({
email: req.body.email,
password: req.body.password,
});
// Cookie name must be a_session_<PROJECT_ID>
res.cookie('a_session_[PROJECT_ID]', session.secret, {
httpOnly: true,
secure: true,
sameSite: 'strict',
expires: new Date(session.expire),
path: '/',
});
res.json({ success: true });
});
app.get('/user', async (req, res) => {
const session = req.cookies['a_session_[PROJECT_ID]'];
if (!session) return res.status(401).json({ error: 'Unauthorized' });
// Create a fresh session client per request
const sessionClient = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('[PROJECT_ID]')
.setSession(session);
const account = new Account(sessionClient);
const user = await account.get();
res.json(user);
});
// Step 1: Redirect to OAuth provider
app.get('/oauth', async (req, res) => {
const account = new Account(adminClient);
const redirectUrl = await account.createOAuth2Token({
provider: OAuthProvider.Github,
success: 'https://example.com/oauth/success',
failure: 'https://example.com/oauth/failure',
});
res.redirect(redirectUrl);
});
// Step 2: Handle callback — exchange token for session
app.get('/oauth/success', async (req, res) => {
const account = new Account(adminClient);
const session = await account.createSession({
userId: req.query.userId,
secret: req.query.secret,
});
res.cookie('a_session_[PROJECT_ID]', session.secret, {
httpOnly: true, secure: true, sameSite: 'strict',
expires: new Date(session.expire), path: '/',
});
res.json({ success: true });
});
Cookie security: Always use
httpOnly,secure, andsameSite: 'strict'to prevent XSS. The cookie name must bea_session_<PROJECT_ID>.
Forwarding user agent: Call
sessionClient.setForwardedUserAgent(req.headers['user-agent'])to record the end-user's browser info for debugging and security.
import { AppwriteException } from 'appwrite';
// Server-side: import from 'node-appwrite'
try {
const doc = await tablesDB.getRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: '[ROW_ID]',
});
} catch (err) {
if (err instanceof AppwriteException) {
console.log(err.message); // human-readable error message
console.log(err.code); // HTTP status code (number)
console.log(err.type); // Appwrite error type string (e.g. 'document_not_found')
console.log(err.response); // full response body (object)
}
}
Common error codes:
| Code | Meaning |
|---|---|
401 | Unauthorized — missing or invalid session/API key |
403 | Forbidden — insufficient permissions for this action |
404 | Not found — resource does not exist |
409 | Conflict — duplicate ID or unique constraint violation |
429 | Rate limited — too many requests, retry after backoff |
Appwrite uses permission strings to control access to resources. Each permission pairs an action (read, update, delete, create, or write which grants create + update + delete) with a role target. By default, no user has access unless permissions are explicitly set at the document/file level or inherited from the collection/bucket settings. Permissions are arrays of strings built with the Permission and Role helpers.
import { Permission, Role } from 'appwrite';
// Server-side: import from 'node-appwrite'
const doc = await tablesDB.createRow({
databaseId: '[DATABASE_ID]',
tableId: '[TABLE_ID]',
rowId: ID.unique(),
data: { title: 'Hello World' },
permissions: [
Permission.read(Role.user('[USER_ID]')), // specific user can read
Permission.update(Role.user('[USER_ID]')), // specific user can update
Permission.read(Role.team('[TEAM_ID]')), // all team members can read
Permission.read(Role.any()), // anyone (including guests) can read
]
});
const file = await storage.createFile({
bucketId: '[BUCKET_ID]',
fileId: ID.unique(),
file: document.getElementById('file-input').files[0],
permissions: [
Permission.read(Role.any()),
Permission.update(Role.user('[USER_ID]')),
Permission.delete(Role.user('[USER_ID]')),
]
});
When to set permissions: Set document/file-level permissions when you need per-resource access control. If all documents in a collection share the same rules, configure permissions at the collection/bucket level and leave document permissions empty.
Common mistakes:
- Forgetting permissions — the resource becomes inaccessible to all users (including the creator)
Role.any()withwrite/update/delete— allows any user, including unauthenticated guests, to modify or remove the resourcePermission.read(Role.any())on sensitive data — makes the resource publicly readable
Weekly Installs
58
Repository
GitHub Stars
6
First Seen
Feb 16, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex58
opencode58
gemini-cli57
github-copilot54
kimi-cli53
amp53
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
66,100 周安装
| Changes to teams the user belongs to |
teams.[TEAM_ID] | Changes to a specific team |
memberships | Changes to the user's team memberships |
memberships.[MEMBERSHIP_ID] | A specific membership |
functions.[FUNCTION_ID].executions | Execution updates for a function |