node-appwrite

library26.1.0jsnpmunverified

Official Node.js SDK for Appwrite, an open-source backend-as-a-service platform that simplifies common backend tasks like authentication, database, storage, and serverless functions via a REST API. Current version 26.1.0 supports Appwrite server 1.9.x. Released weekly, with major versions aligning to server API updates. Key differentiators: self-hosted, full control over data, built-in permissions and security, real-time capabilities, and cross-platform SDKs. TypeScript types are included. ESM and CJS dual support. Over 150k weekly npm downloads.

backend

npm install node-appwrite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-APPWRITE

node-appwrite

backendjavascriptv26.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ import { Client } from 'node-appwrite'

✗ import Client from 'node-appwrite'

Named export, not default.

Users

✓ import { Users } from 'node-appwrite'

✗ const Users = require('node-appwrite').Users

CJS require works but ESM import recommended. The SDK ships both ESM and CJS.

✓ import { ID } from 'node-appwrite'

✗ import { ID } from 'node-appwrite/lib/services'

Do not deep import; all exports are at package root.

Enum types (e.g., ExecutionMethod)

✓ import { ExecutionMethod } from 'node-appwrite'

✗ import { ExecutionMethod } from 'node-appwrite/enums'

Enums are re-exported from root, not from a separate module.

Initializes the client, creates a Users service, and creates a new user with unique ID.

import { Client, Users, ID } from 'node-appwrite'; const client = new Client(); client .setEndpoint('https://[HOSTNAME_OR_IP]/v1') .setProject('PROJECT_ID') .setKey('API_KEY'); const users = new Users(client); async function createUser() { try { const user = await users.create( ID.unique(), 'user@example.com', '+1234567890', 'password123', 'Walter O\'Brien' ); console.log('User created:', user); } catch (error) { console.error('Error creating user:', error); } } createUser();

Debug

Known issues

breakingIn v21, Client.setKey() was renamed from Client.setApiKey(). Using setApiKey() will throw a type error in TypeScript, but in JavaScript it will silently fail (function not exist).

fix

Replace .setApiKey(key) with .setKey(key)

affects: >=21.0.0

breakingIn v26, the previously deprecated ID.unique() was removed. ID.unique() is no longer available. Use ID.custom() with a unique string or generate your own.

fix

Update code to use async/await or .then() (promises still supported). Callback patterns (success, error) are no longer accepted.

affects: >=25.0.0

deprecatedClient.setSelfSigned() is deprecated since v23. Use .setSelfSigned(false) with a valid certificate or disable self-signed in production.

fix

Remove .setSelfSigned() calls. For development, use environment variable APPWRITE_SELF_SIGNED=1 or set via client configuration.

affects: >=23.0.0

gotchaWhen using TypeScript, service methods that accept generic types (e.g., Databases.listDocuments<T>()) require the generic type to be passed explicitly because TypeScript cannot infer it from the response body alone.

fix

Always provide generic parameter: db.listDocuments<MyType>('collectionId')

affects: *

gotchaIn Node.js environments, the SDK defaults to using cross-fetch for HTTP requests. This can conflict with custom fetch polyfills or global fetch in newer Node versions, causing inexplicable SSL errors.

fix

Set the environment variable NODE_APPWRITE_FETCH to 'native' to use the built-in fetch in Node 18+ and avoid conflicts.

affects: >=18.0.0

Errors

Common errors & fixes

Error: AppwriteException: Project not found (404)

Incorrect project ID or endpoint URL when initializing the client.

fix

Verify .setEndpoint() and .setProject() values. Ensure project ID is from Appwrite console (not project name).

TypeError: Cannot read properties of undefined (reading 'create')

Service instantiated before Client is ready or imported incorrectly (e.g., using Users class without importing).

fix

Ensure Client is instantiated and configured before creating services: const users = new Users(client);

Error: Network request failed: connect ECONNREFUSED [::1]:443

Local Appwrite server not running or incorrect endpoint (e.g., using https://localhost instead of http://localhost or wrong port).

fix

Check Appwrite server is running and endpoint matches: use http://localhost/v1 for local dev without SSL.

Error: AppwriteException: Unauthorized (401)

API key missing, expired, or does not have required permissions for the operation.

fix

Generate a new API key in Appwrite console with appropriate scopes, and pass it via .setKey(key).

Upgrade

Version history

26.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

Resources

githubhttps://github.com/appwrite/sdk-for-node ↗

packagenode-appwrite ↗

homepagehttps://appwrite.io/support ↗