appwrite-typescript

Imported from Meldiron/getauthui (.agents/skills/appwrite-typescript/SKILL.md). Install upstream with npx skills add Meldiron/getauthui --skill appwrite-typescript. Copyright stays with the author.

Appwrite TypeScript SDK

Installation

# Web
npm install appwrite

# React Native
npm install react-native-appwrite

# Node.js / Deno
npm install node-appwrite

Setting Up the Client

Client-side (Web / React Native)

// 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]");

Server-side (Node.js / Deno)

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);

Code Examples

Authentication (client-side)

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" });

OAuth 2 Login (React Native)

Important: createOAuth2Session() does not work on React Native. You must use createOAuth2Token() with deep linking instead.

Setup

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]"
  }
}

OAuth Flow

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);

User Management (server-side)

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]" });

Database Operations

Note: Use TablesDB (not the deprecated Databases class) for all new code. Only use Databases if 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]",
});

String Column Types

Note: The legacy string type is deprecated. Use explicit column types for all new columns.

• 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
  ],
});

TypeScript Generics

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

Query Methods

// 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)

File Storage

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]" });

InputFile Factory Methods (server-side)

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

Teams

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 or Role.team('[TEAM_ID]', 'editor') for a specific team role when setting permissions.

Real-time Subscriptions (client-side)

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:

The response object includes: events (array of event strings), payload (the affected resource), channels (channels matched), and timestamp (ISO 8601).

Serverless Functions (server-side)

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]" });

Writing a Function Handler (Node.js runtime)

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
};

Server-Side Rendering (SSR) Authentication

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);
}

Email/Password Login

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 });
});

Authenticated Requests

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);
});

OAuth2 SSR Flow

// 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, and sameSite: 'strict' to prevent XSS. The cookie name must be a_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.

Error Handling

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:

Permissions & Roles (Critical)

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 row/file level or inherited from the table/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'

Database Row with Permissions

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
  ],
});

File Upload with Permissions

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 row/file-level permissions when you need per-resource access control. If all rows in a table share the same rules, configure permissions at the table/bucket level and leave row permissions empty.

Common mistakes:

• Forgetting permissions — the resource becomes inaccessible to all users (including the creator)
• Role.any() with write/update/delete — allows any user, including unauthenticated guests, to modify or remove the resource
• Permission.read(Role.any()) on sensitive data — makes the resource publicly readable