Torsten DittmannWe are very excited to announce the release of Appwrite's Web SDK version 5.0 with complete TypeScript coverage. It is now available on npm. With this version, each method will now return proper TypeScript definitions.
We hope this will help a lot of developers out there who are using our Web SDK in combination with TypeScript for building their applications. Having response definitions means you will know what method will return and what properties are available to you via autocomplete without leaving your IDE.
⚙️ Setup
First, you need to install the Appwrite SDK or upgrade it to the latest version via npm:
npm install appwrite@5.0.0
The next step is to import, instantiate and configure the SDK:
import { Appwrite } from "appwrite";
const sdk = new Appwrite();
sdk
.setEndpoint('http://localhost/v1')
.setProject('PROJECT_ID');
👥 Account
Let's start with the simplest example by getting the current user using the account.get() method. In previous versions of the SDK, this method returned a unknown type, but now you don't need to create your own definitions anymore, since the SDK will offer them out-of-the-box.
const user = await sdk.account.get();
The user object will now already contain all possible properties via a TypeScript definition. But there is more, since the User model also contains the prefs property containing all of the User's preferences. These can be set by the client, which means the SDK cannot provide you with typings yet.
Let's assume you store the users preferred theme for your application in their preferences. You will have Type like this:
type MyPreferences = {
theme: "light"|"dark";
}
The new SDK allows you to pass MyPreferences via a Generic - this allows you to pass your own structure to the method.
const user = await sdk.account.get<MyPreferences>();
The new user object returned from account.get() using a generic is now automatically extended by your MyPreferences on the prefs property.
Generics can be used on any method, which can return a data structure that is allowed to be extended by the developer like the User's preferences or documents from the Database service.
📀 Database
Talking about Database, let's move on to some examples how the new SDK can be used in combination with it.
Assuming we have a collection containing Movies with following type:
type Movie = {
title: string;
published: number;
genres: string[];
gotAnOscar: boolean;
};
These are all properties that can be set as rules in a collection, but by default documents in Appwrite come with values like $id, $permissions and $collection.
We can easily import the Models from the SDK and merge Movie with the Document type.
import type { Models } from "appwrite";
type Movie = {
title: string;
published: number;
genres: string[];
gotAnOscar: boolean;
} & Models.Document;
Now that we have all our TypeScript definitions in place, let's use them by retrieving a Document from the Database using database.getDocument(). We can use Generics to tell TypeScript to use our Movie type:
const avatar = await sdk.database.getDocument<Movie>('movies', 'avatar');
For example with using the database.listDocuments, which will have 2 pre-defined properties called sum and documents, the type passed as a generic will be used for documents:
const movies = await sdk.database.listDocuments<Movie>('movies');
movies.sum; // The sum of all documents.
movies.documents; // Will use an array of our Movie type.
This can also be used with the subscribe() method for real-time updates:
sdk.subscribe<Movie>('collection.movies', response => {
response.payload; // Will use the Movie type.
});
You can try it out by yourself using this StackBlitz.
The heavily improved TypeScript support of the new Web SDK allow you to kickstart the development of your Application and keep you focused without leaving your IDE.
If you have any issues or questions feel free to reach us on our discord.
📚 Learn more
You can use following resources to learn more and get help
