Skip to content

docs: refresh README #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChiragAgg5k merged 2 commits into from
Oct 17, 2026
Merged

docs: refresh README #178

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ffbdeb
Merge commit 'a8e771af9014c509e9f802c7320451e7fa0936e6' into dev
ChiragAgg5k Oct 17, 2026
f646a57
docs: refresh README
ChiragAgg5k Oct 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 99 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,192 +1,174 @@
# Appwrite Node.js SDK

![License](https://img.shields.io/github/license/appwrite/sdk-for-node.svg?style=flat-square)
![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg?style=flat-square)
![Version](https://img.shields.io/badge/api%20version-2.5.0-blue.svg?style=flat-square)
[![Build Status](https://img.shields.io/travis/com/appwrite/sdk-generator?style=flat-square)](https://travis-ci.com/appwrite/sdk-generator)
[![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite)
[![X Account](https://img.shields.io/badge/follow-%40appwrite-000000?logo=x&style=flat-square)](https://x.com/appwrite)
[![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord)

**This SDK targets Appwrite server version 2.5.x as shipped on Appwrite Cloud.** Self-hosted releases can lag behind Cloud — if you run an older self-hosted build, use a matching older SDK from [previous releases](https://github.com/appwrite/sdk-for-node/releases) when APIs differ.

> This is the Node.js SDK for integrating with Appwrite from your Node.js server-side code.
If you're looking to integrate from the browser, you should check [appwrite/sdk-for-web](https://github.com/appwrite/sdk-for-web)
> This is the Node.js SDK for integrating with Appwrite from your Node.js server-side code. If you're looking to integrate from the browser, you should check [appwrite/sdk-for-web](https://github.com/appwrite/sdk-for-web)

Appwrite is an open-source backend as a service server that abstracts and simplifies complex and repetitive development tasks behind a very simple to use REST API. Appwrite aims to help you develop your apps faster and in a more secure way. Use the Node.js SDK to integrate your app with the Appwrite server to easily start interacting with all of Appwrite backend APIs and tools. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)

![Appwrite](https://github.com/appwrite/appwrite/raw/main/public/images/github.png)

## Installation

To install via [NPM](https://www.npmjs.com/):
Requires Node.js 18.17 or later.

```bash
npm install node-appwrite --save
npm install node-appwrite
```

The package ships ES modules, CommonJS and TypeScript types:

## Getting Started
```js
import { Client, Users } from 'node-appwrite';
```

### Init your SDK
```js
const { Client, Users } = require('node-appwrite');
```

Initialize your SDK with your Appwrite server API endpoint and project ID which can be found in your project settings page and your new API secret Key project API keys section.
Deno can use the same package through its npm support:

```js
const sdk = require('node-appwrite');
```ts
import { Client, Users } from 'npm:node-appwrite';
```

## Getting started

### Initialize the client

Copy your endpoint and project ID from your project's **Settings** page. Create an API key under **API Keys** in the project sidebar and grant it only the scopes your code needs.

let client = new sdk.Client();
```js
import { Client } from 'node-appwrite';

client
.setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
.setProject('5df5acd0d48c2') // Your project ID
.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key
.setSelfSigned() // Use only on dev mode with a self-signed SSL cert
;
const client = new Client()
.setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
.setProject('<PROJECT_ID>')
.setKey('<API_KEY>');
```

### Make Your First Request
API keys bypass user permissions, so keep them on the server and out of source control. To act as a signed-in user instead, pass their session with `setSession()` or a JWT with `setJWT()`.

For a self-hosted Appwrite, use `https://<HOSTNAME>/v1` as the endpoint. If it serves a self-signed certificate during development, also call `.setSelfSigned(true)`.

### Make your first request

Once your SDK object is set, create any of the Appwrite service objects and choose any request to send. Full documentation for any service method you would like to use can be found in your SDK documentation or in the [API References](https://appwrite.io/docs) section.
Create a service from the client and call any of its methods. Every method takes a single object of named parameters and returns a promise. See the [API reference](https://appwrite.io/docs/references) for every service and method.

```js
let users = new sdk.Users(client);

let promise = users.create({
userId: sdk.ID.unique(),
email: "email@example.com",
phone: "+123456789",
password: "password",
name: "Walter O'Brien"
});
import { ID, Users } from 'node-appwrite';

const users = new Users(client);

promise.then(function (response) {
console.log(response);
}, function (error) {
console.log(error);
const user = await users.create({
userId: ID.unique(),
email: 'email@example.com',
phone: '+123456789',
password: 'password',
name: "Walter O'Brien",
});

console.log(user);
```

### Full Example
### Upload a file

File inputs are built with `InputFile`, imported from `node-appwrite/file`:

```js
const sdk = require('node-appwrite');

let client = new sdk.Client();

client
.setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
.setProject('5df5acd0d48c2') // Your project ID
.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key
.setSelfSigned() // Use only on dev mode with a self-signed SSL cert
;

let users = new sdk.Users(client);
let promise = users.create({
userId: sdk.ID.unique(),
email: "email@example.com",
phone: "+123456789",
password: "password",
name: "Walter O'Brien"
});
import { ID, Storage } from 'node-appwrite';
import { InputFile } from 'node-appwrite/file';

promise.then(function (response) {
console.log(response);
}, function (error) {
console.log(error);
const storage = new Storage(client);

const file = await storage.createFile({
bucketId: '<BUCKET_ID>',
fileId: ID.unique(),
file: InputFile.fromPath('/path/to/file.png', 'file.png'),
});
```

### Type Safety with Models
### Type safety with models

Methods that return rows, such as `listRows` and `getRow`, accept a type parameter for your own row shape:

The Appwrite Node SDK provides type safety when working with table rows through generic methods. Methods like `listRows`, `getRow`, and others accept a generic type parameter that allows you to specify your custom model type for full type safety.
```ts
import { TablesDB, type Models } from 'node-appwrite';

**TypeScript:**
```typescript
interface Book extends Models.Row {
name: string;
author: string;
releaseYear?: string;
category?: string;
genre?: string[];
isCheckedOut: boolean;
}

const tablesDB = new TablesDB(client);

try {
const result = await tablesDB.listRows<Book>({
databaseId: 'your-database-id',
tableId: 'your-table-id'
});

result.rows.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Now you have full type safety
});
} catch (error) {
console.error('Appwrite error:', error);
const result = await tablesDB.listRows<Book>({
databaseId: '<DATABASE_ID>',
tableId: '<TABLE_ID>',
});

for (const book of result.rows) {
console.log(`${book.name} by ${book.author}`);
}
```

**JavaScript (with JSDoc for type hints):**
```javascript
In JavaScript, the same types are available through JSDoc:

```js
/**
* @typedef {Object} Book
* @property {string} name
* @property {string} author
* @property {string} [releaseYear]
* @property {string} [category]
* @property {string[]} [genre]
* @property {boolean} isCheckedOut
* @typedef {import('node-appwrite').Models.Row & {
* name: string,
* author: string,
* isCheckedOut: boolean,
* }} Book
*/

const tablesDB = new TablesDB(client);

try {
/** @type {Models.RowList<Book>} */
const result = await tablesDB.listRows({
databaseId: 'your-database-id',
tableId: 'your-table-id'
});

result.rows.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Type hints available in IDE
});
} catch (error) {
console.error('Appwrite error:', error);
}
/** @type {import('node-appwrite').Models.RowList<Book>} */
const result = await tablesDB.listRows({
databaseId: '<DATABASE_ID>',
tableId: '<TABLE_ID>',
});
```

**Tip**: You can use the `appwrite types` command to automatically generate TypeScript interfaces based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
The [Appwrite CLI](https://github.com/appwrite/sdk-for-cli) can generate these interfaces from your database schema with `appwrite types`. See [type generation](https://appwrite.io/docs/products/databases/tablesdb/type-generation).

### Error Handling
### Error handling

The Appwrite Node SDK raises `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching `AppwriteException` and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
Failed requests throw an `AppwriteException` with `message`, `code`, `type` and `response` properties.

```js
let users = new sdk.Users(client);
import { AppwriteException } from 'node-appwrite';

try {
let res = await users.create({
userId: sdk.ID.unique(),
email: "email@example.com",
phone: "+123456789",
password: "password",
name: "Walter O'Brien"
});
} catch(e) {
console.log(e.message);
const user = await users.get({ userId: '<USER_ID>' });
console.log(user);
} catch (error) {
if (error instanceof AppwriteException) {
console.error(error.code, error.type, error.message);
}
}
```

The [response codes](https://appwrite.io/docs/apis/response-codes) page lists every error type.

### Learn more
You can use the following resources to learn more and get help
- 🚀 [Getting Started Tutorial](https://appwrite.io/docs/getting-started-for-server)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
- 💬 [Discord Community](https://appwrite.io/discord)
- 🚂 [Appwrite Node Playground](https://github.com/appwrite/playground-for-node)

- [Node.js quick start](https://appwrite.io/docs/quick-starts/node)
- [Appwrite docs](https://appwrite.io/docs)
- [Discord community](https://appwrite.io/discord)
- [Node.js playground](https://github.com/appwrite/playground-for-node)

## Contribution

This library is auto-generated by Appwrite custom [SDK Generator](https://github.com/appwrite/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/master/CONTRIBUTING.md) before sending a pull-request.
This library is auto-generated by the Appwrite [SDK Generator](https://github.com/appwrite/sdk-generator). To learn more about how you can help us improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/main/CONTRIBUTING.md) before sending a pull-request.

## License

Expand Down
Loading