node-appwrite

node-appwrite is the official server-side Node.js SDK for Appwrite, the open-source backend-as-a-service platform. It wraps Appwrite’s REST API in a typed TypeScript client covering databases, authentication, storage, functions, messaging, and more, so server code can call Appwrite services without hand-rolling HTTP requests or juggling JSON payloads.

The SDK is auto-generated from Appwrite’s shared SDK Generator, keeping it tightly versioned to specific Appwrite server releases — this build targets Appwrite 1.9.x server APIs. It ships CommonJS and ESM builds with full TypeScript typings, big-integer-safe JSON handling via json-bigint, and generic-typed document methods so applications can bring their own document models for full type safety.

What You Get

• A typed Client class configured with your Appwrite endpoint, project ID, and API key for authenticated server-to-server requests.
• 29 service classes (Account, Databases, Storage, Functions, Users, Teams, Messaging, and more) mapping 1:1 to Appwrite’s REST API surface.
• Query, Permission, Role, and ID helper classes for building Appwrite database queries and access-control rules without hand-writing query strings.
• Generic-typed document methods (listDocuments<T>, getDocument<T>) for full TypeScript type safety against your own data models.
• Chunked file upload support with progress callbacks via the InputFile helper for large file uploads to Appwrite Storage.

Common Use Cases

• Server-side auth flows - verifying sessions and managing users from a Node.js backend using the Account and Users services.
• Custom backend logic - reading and writing Appwrite Database documents from an existing Express or Next.js API layer.
• File upload pipelines - streaming large files into Appwrite Storage with chunked uploads and progress tracking.
• Appwrite Functions runtimes - calling other Appwrite services from within a deployed Appwrite Function’s Node.js runtime.

Under The Hood

Architecture The SDK is a generated facade over Appwrite’s REST API: client.ts holds a single low-level Client class that owns endpoint/project/key configuration, request signing, chunked-upload handling, and error wrapping into a typed AppwriteException; each of the 29 files under src/services/ (account.ts, databases.ts, storage.ts, functions.ts, etc.) is a thin class constructed with that shared Client and exposes async methods mapping 1:1 to REST endpoints. Standalone helper modules — query.ts, permission.ts, role.ts, id.ts — build Appwrite’s query/permission string syntax with no dependency on Client at all. Data flows caller → service method → Client.call() → an undici fetch → bigint-safe JSON parsing → typed Models.* response. Because every service funnels through the same Client, changes to core request/error handling ripple across all services, while each service module itself is fully isolated.

Tech Stack Written in TypeScript 5.9 and built with tsup (esbuild-based) into dual CommonJS/ESM output plus .d.ts/.d.mts declarations, configured via tsup.config.ts and package.json conditional exports. HTTP requests go through undici (Node’s own fetch implementation) rather than axios or node-fetch. Responses are parsed with json-bigint and a custom reviver so 64-bit integers from Appwrite round-trip without losing precision the way native JSON.parse would. Tests run on Jest 30, linting on ESLint 10 with typescript-eslint, formatting via Prettier. The package has no runtime dependency on any database or web framework — it is purely a client.

Code Quality The test/ directory mirrors src/services/ file-for-file (29 service test files), plus dedicated unit tests for query, permission, role, id, client, and operator — broad, table-driven test coverage rather than a handful of smoke tests. TypeScript throughout gives compile-time safety on every method signature, and errors are centralized into a single AppwriteException type instead of being thrown ad hoc. ESLint plus Prettier enforce consistent style, and the shallow single-branch clone doesn’t surface CI config, though the project’s active release cadence suggests automated checks run upstream.

API Design Because the client is generated 1:1 from Appwrite’s own API spec, method names and argument ordering stay consistent across all 29 services, so learning one service transfers directly to the next. Configuration reads as a fluent chain (new Client().setEndpoint().setProject().setKey()), and generic-typed document methods (listDocuments<T>, getDocument<T>) let TypeScript consumers plug in their own model interfaces for compile-time-checked database access, with a documented JSDoc-typedef fallback for plain JavaScript users. A separate ./file export path keeps the InputFile chunked-upload helper tree-shakeable from the rest of the client. The tradeoff of a generated SDK is that query/permission construction leans on builder classes (Query, Permission, Role) rather than a more fluent query DSL, but the pattern is applied uniformly everywhere it’s needed.