appwrite/sdk-for-web

Appwrite Web SDK

This SDK targets Appwrite server version 2.7.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 when APIs differ.

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 Web 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

Installation

npm

npm install appwrite

Import the modules you need. The package ships ES modules, CommonJS and TypeScript types:

import { Client, Account } from 'appwrite';

CDN

Every release is published to https://sdk.appwrite.io/web/29.3.0-rc.1/.

ES modules

Each service, helper and enum is its own module, so the browser downloads only what you import. A service is served under its name in kebab case, such as TablesDB from tables-db.js, and enums under enums/, such as OAuthProvider from enums/o-auth-provider.js. index.js re-exports everything, so importing it loads every service:

<script type="module">
    import { Client } from 'https://sdk.appwrite.io/web/29.3.0-rc.1/client.js';
    import { Account } from 'https://sdk.appwrite.io/web/29.3.0-rc.1/account.js';
    import { OAuthProvider } from 'https://sdk.appwrite.io/web/29.3.0-rc.1/enums/o-auth-provider.js';
</script>

Script tag

Add the script before any code that uses the SDK. It exposes every export on the global Appwrite object:

<script src="https://sdk.appwrite.io/web/29.3.0-rc.1/sdk.min.js"></script>
<script>
    const { Client, Account } = Appwrite;
</script>

Subresource integrity

integrity.json in the same directory maps each .js file to its sha384- hash. An integrity attribute checks only the file it is set on. sdk.min.js is a single file, so its hash as the integrity attribute, together with crossorigin="anonymous", covers the whole SDK. ES modules import other modules and shared chunks, so supply their hashes through the integrity field of an import map to cover those too.

jsDelivr

The script tag build is also available from jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>

Getting started

Add a Web platform

In the Appwrite Console, open your project and under Add a platform choose Web app. Enter the hostname your app runs on: localhost for local development, and your production domain once you deploy. Appwrite only accepts browser requests from hostnames registered as platforms, so a missing hostname shows up as a CORS error.

Initialize the client

Copy your endpoint and project ID from your project's Settings page.

import { Client } from 'appwrite';

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

For a self-hosted Appwrite, use https://<HOSTNAME>/v1 as the endpoint.

Make your first request

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 for every service and method.

import { Account, ID } from 'appwrite';

const account = new Account(client);

const user = await account.create({
    userId: ID.unique(),
    email: '[email protected]',
    password: 'password',
    name: "Walter O'Brien",
});

console.log(user);

Sign in with OAuth

Enable the provider in the Console under Auth > Settings, then redirect the user to it. The success and failure URLs must be on a hostname you registered as a platform.

import { Account, OAuthProvider } from 'appwrite';

const account = new Account(client);

account.createOAuth2Session({
    provider: OAuthProvider.Github,
    success: 'https://example.com/success',
    failure: 'https://example.com/failure',
});

Type safety with models

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

import { TablesDB, type Models } from 'appwrite';

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

const tablesDB = new TablesDB(client);

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

In JavaScript, the same types are available through JSDoc:

import { TablesDB } from 'appwrite';

const tablesDB = new TablesDB(client);

/**
 * @typedef {import('appwrite').Models.Row & {
 *     name: string,
 *     author: string,
 *     isCheckedOut: boolean,
 * }} Book
 */

/** @type {import('appwrite').Models.RowList<Book>} */
const result = await tablesDB.listRows({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
});

The Appwrite CLI can generate these interfaces from your database schema with appwrite types. See type generation.

Error handling

Failed requests throw an AppwriteException with message, code, type and response properties.

import { AppwriteException } from 'appwrite';

try {
    const user = await account.get();
    console.log(user);
} catch (error) {
    if (error instanceof AppwriteException) {
        console.error(error.code, error.type, error.message);
    }
}

The response codes page lists every error type.

Learn more

• Web quick start
• Appwrite docs
• Discord community
• Web playground

Contribution

This library is auto-generated by the Appwrite SDK Generator. To learn more about how you can help us improve this SDK, please check the contribution guide before sending a pull-request.

License

Please see the BSD-3-Clause license file for more information.