We 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
Top comments (4)
Wowsers the world is getting complicated. The name drew me in, I scanned the article, I clicked the Tutorial link and the Docs link and I scanned and read a fair bit and after all that I still have no clue what appwriter even is or why I'd be interested ... (though I do know how to install it ;-)
As complicated as the world has become, I still have to class that, a marketing fail. Sorry. Of course I'm generous and will simply assume it's marketed at a different demography than mine (clueless to that we've just read).
Hehe, we are actually trying to make the world of development less complicated. Appwrite is an open source backend as a service that gives you a self-hosted alternative to Firebase/co.
Not much of an improvement as I don't even know what Firebase is ;-) And to be honest looking it up on-line I am not much closer ... even after reading their use cases, to understand what Firebase it even is ... As I said, the world is getting complicated, or stuff like this is pitched at an in crowd, folk who know what's going on. Here I am a mere mortal and I flick over these pages and am still wondering what there is here, what Firebase is, and what AppWriter is. What I can say is a clear link to use cases is a big boon. Next thing Google might try is writing some use cases that speak to me ;-).
Is this like all abut phone apps? Web apps? As in web site/pages? I'm none the wiser really. I see like Firebase can add on-line chat to my app, great, that actually speaks to me, but like can I plug that in to my Django website? IS it a phone app thing, or does it predicate me having written a web app in Firebase? none of these questions are ever close to being answered easily ... Just saying, the dev world has got weirdly complicated IMHO.
Do you have plans to provide appwrite hosting and when it will be ready for using?
Steps to use Firebase: 1. Register 2. Create database 3. Integrate with your App
Steps to use Appwrite: 1. Learn what is Docker 2. Install Docker 3. Learn how to install Appwrite 4. Install Appwrite 5. Integrate with your App 6. Lern how to host Docker in Cloud 7. Host Docker in Cloud. Only then you can say that you have back-end for your App in the Internent. And after all of that you need think about monitoring and deal with crashes.
But API looks nice. Thanks for product.