Get free $100 credits on DigitalOcean:
Join our Discord:
Metawrite is Appwrite SDK with ready to go components for Svelte
/ SvelteKit
This package is maintained by Increasio.
Note: versions
x.x.n
means some minor changes to package documentation or typings.versions
x.n.x
might include some minor breaking changes. See Release Notes.versions
n.x.x
might include some major breaking changes. See Release Notes.
The package is fully working and compatible with Appwrite Server 0.12, Web SDK 6, and SvelteKit. But people are currently facing difficulties with npm install metawrite
. We have ready and configured SvelteKit template that uses Metawrite and could be also used as Docker image like described here.
Please consider using template, this is temporary
Using NPM:
npm install metawrite
Using Yarn:
yarn add metawrite
- Support Us
- Documentation - Installation
- Table of contents
- Usage
- API
- Stack
You need a running instance of Appwrite to use this library. Go to https://appwrite.io/docs/installation for more instructions.
Psuedo Example
Handle multiple levels of async relational data (and their loading & fallback states) entirely from the Svelte markup.
<!-- 1. 💪 Appwrite App -->
<Appwrite {...config}>
<!-- 2. 😀 Get the current user if logged in -->
<User let:user>
<h1>Hello {user.name}!</h1>
<!-- 3. 📚 Get all the documents from a collection -->
<Collection collectionId="5f56a3035a01f" let:documents>
You have {documents.length} documents.
{#each documents as document}
<!-- 4. 📜 Get a document -->
<Document collectionId="5f56a3035a01f" documentId={document.$id} {document}>
Title: {document.title}
Text: {document.text}
...
Must be initialised and wrap every metawrite
component.
<script>
import { Appwrite } from 'metawrite';
const config = {
endpoint: 'http://localhost/v1',
project: 'demo',
locale: 'fr'
};
</script>
<Appwrite {...config}>...</Appwrite>
Name | Description |
---|---|
endpoint |
Your Appwrite endpoint. @type - {string} |
project |
Your project ID. @type - {string} |
locale |
Optional The users locale. @type - {string} |
realtime |
Optional Set Custom realtime endpoint. By default the same as endpoint . @type - {string} |
Registers a new account.
<script>
import { Create } from 'metawrite';
let email = '';
let password = '';
let name = '';
const success = (e) => {
//success callback
// `e` contains the user object
};
const failure = (e) => {
//failure callback
};
</script>
<Create let:actions on:success on:failure>
<input type="text" bind:value={email} />
<input type="password" bind:value={password} />
<input type="text" bind:value={name} />
<button on:click={actions.create(email, password, name)}>Register</button>
</Create>
let:actions object
Object with function.
Name | Description |
---|---|
create(email, password, name) |
Registers a new user. @type - {string} |
on:success
Triggers on successful register.
Name | Description |
---|---|
response |
Response |
on:failure
Triggers on failed register.
Name | Description |
---|---|
response |
Response |
Login via email and password.
<script>
import { AuthEmail } from 'metawrite';
let email = '';
let password = '';
const success = (e) => {
//success callback
// `e` contains the user object
};
const failure = (e) => {
//failure callback
};
</script>
<AuthEmail let:authorize on:success on:failure>
<input type="text" bind:value={email} />
<input type="text" bind:value={password} />
<button on:click={authorize(email, password)}>Login</button>
</AuthEmail>
let:authorize function
Initiates login.
Name | Description |
---|---|
email |
E-Mail. @type - {string} |
password |
Password. @type - {string} |
on:success
Triggers on successful login.
Name | Description |
---|---|
email |
E-Mail. @type - {string} |
on:failure
Triggers on failed login.
Name | Description |
---|---|
error |
Error object. |
Login via an OAuth2 provider.
<script>
import { AuthOAuth2 } from 'metawrite';
</script>
<AuthOAuth2
authProvider="google"
success="http://localhost:3000?success"
failure="http://localhost:3000?failure"
let:authorize
>
<button on:click={authorize}>Login Google</button>
</AuthOAuth2>
Name | Description |
---|---|
authProvider |
OAuth2 provider. @type - {string} |
success |
Success url. @type - {string} |
failure |
Failure url. @type - {string} |
let:authorize function
Requests current user to check if logged in.
<script>
import { User } from 'metawrite';
</script>
<User let:user>
<h1>Hello {user.name}!</h1>
<div>{user.email}</div>
<div slot="error">You are not logged in!</div>
</User>
let:user object
Get currently logged in user data.
Get a list of all the documents from a collection.
<script>
import { Collection } from 'metawrite';
</script>
<Collection collectionId="5f56a3035a01f" let:documents>
You have {documents.length} documents.
</Collection>
Name | Description |
---|---|
collectionId |
Collection unique ID. @type - {string} |
additional | same as here |
let:documents array
Array of documents.
let:actions object
Object with function.
Name | Description |
---|---|
reload() |
Re-fetch collection. |
create(data, read, write) |
Create a new Document in the collection. read /write is optional and current user by default @type - {string[]} . data is @type - {string} |
Get a document. If you pass the document
property with data from , there wont be any data requested.
<script>
import { Document } from 'metawrite';
</script>
<Document documentId="5f56a3asda01f" let:document>
Title: {document.title}
Text: {document.text}
</Document>
Name | Description |
---|---|
documentId |
Document unique ID. @type - {string} |
collectionId |
Collection unique ID. @type - {string} |
or | |
document |
Document passed from <Collection /> |
let:document object
A JSON object with the document data.
let:actions object
Object with function.
Name | Description |
---|---|
update(data) |
Update the document. data is @type - {string} |
remove() |
Deletes the document. |
reload() |
Re-fetch document. |
on:change
Triggers on update or remove login.
The Account components allow you to manage a user account.
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
logout() |
Logout current session. |
logoutAll() |
Logout from all session. |
logoutFrom(session) |
Logout from specific session. session is @type - {string} |
- let:user
object
- let:error
- on:success On user fetch success.
- on:failure On user fetch failure.
- on:successLogout On
logout
success. - on:failureLogout On
logout
failure. - on:successLogoutFrom On
logoutFrom
success. - on:failureLogoutFrom On
logoutFrom
failure. - on:successLogoutAll On
logoutAll
success. - on:failureLogoutAll On
logoutAll
failure.
<script>
import { User } from 'metawrite';
</script>
<User let:actions let:user>
<button on:click={actions.reload()}>Reload user data</button>
<button on:click={actions.get()}>Get logged in user data</button>
<button on:click={actions.logout()}>Log out from current session</button>
<button on:click={actions.logoutFrom('sessionId')}>Log out from specific session</button>
<button on:click={actions.logoutAll()}>Log out from all sessions</button>
<!-- If logged in -->
<p>Hi, {user.name}</p>
</User>
let:actions
Name | Description |
---|---|
create(email, password, name) |
Creates a user. email and password are required - @type - {string} . name is optional - @type - {string} |
- on:success On
create
success. - on:failure On
create
failure.
<script>
import { Create } from 'metawrite';
let name,
email,
password = '';
const success = (e) => {
// success callback
// `e` contains the user object
};
const failure = (e) => {
// failure callback
};
</script>
<Create let:actions on:success on:failure>
<input type="text" name="name" placeholder="name" bind:value={name} />
<input type="text" name="email" placeholder="email" bind:value={email} />
<input type="password" name="password" placeholder="password" bind:value={password} />
<button on:click={actions.create(name, email, password)}>Create Account</button>
</Create>
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reloads preferences. |
update(prefs) |
Update preferences. prefs - @type - {object} |
- on:success On init and
reload
success. - on:failure On init and
reload
failure. - on:successUpdate On
update
success. - on:failureUpdate On
update
failure.
<script>
import { Preferences } from 'metawrite';
let prefs = {
// You can pass only the specific settings you wish to update.
};
</script>
<Preferences let:actions>
<button
on:click={() => {
actions.update(prefs);
actions.reload();
}}>Update Preferences</button
>
</Preferences>
let:actions
Name | Description |
---|---|
recover(email, url) |
Recover password. email and url is required and @type - {string} . url is your page where you will handle secret with complete function. |
complete(user, secret, password, passwordAgain) |
Complete password recovery. user and secret are set automatically by metawrite , so you don’t have to set them. password and passwordAgain are required - @type - {string} . |
- on:successRecover On init and
reload
success. - on:failureRecover On init and
reload
failure. - on:successComplete On
update
success. - on:failureComplete On
update
failure.
<script>
import { RecoverPassword } from "metawrite";
const url = "http://localhost:3000/reset-password"; // URL that will point to the next step.
let email = '';
const successRecover = e => {
//success callback
// `e` contains the user object
};
const failureRecover = e => {
//failure callback
}
</script>
<!-- localhost/forgot-password -->
<RecoverPassword let:actions on:successRecover on:failureRecover>
<input name="email" type="text" bind:value={email, url} placeholder="Email" />
<button on:click{actions.recover(email)}>Recover Password</button>
</RecoverPassword>
<!-- Then on localhost/reset-password -->
<script>
import { RecoverPassword } from "metawrite";
let password, passwordAgain = '';
const successComplete = e => {
//success callback
// `e` contains the user object
};
const failureComplete = e => {
//failure callback
}
</script>
<RecoverPassword let:actions on:successComplete on:failureComplete>
<input type="password" name="password" bind:value{password} placeholder="Password" />
<input type="password" name="password" bind:value{passwordAgain} placeholder="Confirm Password" />
<button on:click{actions.complete(password, passwordAgain)}>Set New Password</button>
</RecoverPassword>
let:actions
Name | Description |
---|---|
name(name) |
Update name. All fields are required. @type - {string} |
email(email, password) |
Update email. All fields are required. @type - {string} |
password(password, oldPassword) |
Update password. All fields are required. @type - {string} |
- on:successName On
name
success. - on:failureName On
name
failure. - on:successEmail On
email
success. - on:failureEmail On
email
failure. - on:successPassword On
password
success. - on:failurePassword On
password
failure.
<script>
import { Update } from 'metawrite';
let name,
email,
password,
newPassword,
oldPassword = '';
</script>
<Update let:actions>
<button on:click={actions.name(name)}>This updates name</button>
<button on:click={actions.email(email, password)}>This updates email</button>
<button on:click={actions.password(newPassword, oldPassword)}>This updates password</button>
</Update>
Creates and automatically validates user email verification.
url
of type string for actioncreate
should be where your app is hosted orlocalhost
.- For
update
action you don't need to pass anything, the process is automated.
let:actions
Name | Description |
---|---|
create(url) |
Create Verification. url is what URL used to create verification link sent to your email inbox. @type - {string} |
update(user, secret) |
Complete Verification. user and secret are set automatically by metawrite . |
- on:successCreate On
create
success. - on:failureCreate On
create
failure. - on:successComplete On
complete
success. - on:failureComplete On
complete
failure.
<script>
import { Verification } from 'metawrite';
const url = window.location.href;
</script>
<Verification let:actions>
<button on:click={actions.create(url)} />
<button on:click={actions.update()}>Update email verification status</button>
</Verification>
The Auth components allow you to authenticate a user account.
- loading
- success
- error
- let:authorize(email, password)
- let:user
- let:error
- on:success On
authorize
success. - on:failure On
authorize
failure.
<script>
import { AuthEmail } from 'metawrite';
let email = '';
let password = '';
const success = (e) => {
//success callback
// `e` contains the user object
};
const failure = (e) => {
//failure callback
};
</script>
<AuthEmail let:authorize on:success on:failure>
<input type="text" bind:value={email} />
<input type="text" bind:value={password} />
<button on:click={authorize(email, password)}>Login</button>
</AuthEmail>
Name | Description |
---|---|
authProvider |
OAuth2 provider. @type - {string} |
success |
Success url. @type - {string} |
failure |
Failure url. @type - {string} |
#### Directives |
let:authorize()
<script>
import { AuthOAuth2 } from 'metawrite';
</script>
<AuthOAuth2
authProvider="google"
success="http://localhost:3000?success"
failure="http://localhost:3000?failure"
let:authorize
>
<button on:click={authorize}>Login Google</button>
</AuthOAuth2>
let:actions
Name | Description |
---|---|
create() |
Creates anonymous session. |
<script>
import { CreateAnonymousSession } from 'metawrite';
</script>
<CreateAnonymousSession let:actions>
<button on:click={actions.create}>Create Anonymous Session</button>
</CreateAnonymousSession>
Creates JWT token.
let:actions
Name | Description |
---|---|
create() |
Creates JWT token. |
<script>
import { CreateJWT } from 'metawrite';
</script>
<CreateJWT let:actions>
<button on:click={actions.create}>Create JWT token</button>
</CreateJWT>
let:actions
Name | Description |
---|---|
create(sessionId, email, url) |
Creates Magic URL Session. email is required, url is to point on complete step string , sessionId is not required |
complete() |
Validates and completes Magic URL Session. |
<script>
import { MagicURL } from "metawrite";
let email = ""
const url = "http://localhost:3000/page-to-complete"
const successCreate = (e) => {
console.log(e)
}
const failureCreate = (e) => {
console.log(e)
}
const successComplete = (e) => {
console.log(e)
}
const failureComplete = (e) => {
console.log(e)
}
</script>
<MagicURL let:actions on:successCreate on:successComplete on:failureCreate on:failureComplete>
<input type="email" name="email" placeholder="Email" bind:value={email} />
<button on:click={actions.create(email, url)}>Send login link</button>
<button on:click={actions.complete()}>Confirm Login</button>
</MagicURL>
The Avatar components aim to help you complete everyday tasks related to your app image, icons, and avatars.
- code - required
@type - {string}
- width - optional
@type - {number}
- height - optional
@type - {string}
- quality - optional
@type - {string}
- let:src Image link
@type - {URL}
<script>
import { Browser } from 'metawrite';
</script>
<Browser code="firefox" let:src>
<img src={String(src)} alt="Browser" />
</Browser>
- code - required
@type - {string}
- width - optional
@type - {number}
- height - optional
@type - {string}
- quality - optional
@type - {string}
- let:src Image link
@type - {URL}
<script>
import { CreditCard } from 'metawrite';
</script>
<CreditCard code="amex" let:src>
<img src={String(src)} alt="card" />
</CreditCard>
- url - required
@type - {string}
- let:src Image link
@type - {URL}
<script>
import { Favicon } from 'metawrite';
const url = window.location.href;
</script>
<Favicon {url} let:src>
<img src={String(src)} alt="favicon" />
</Favicon>
- code - required
@type - {string}
- width - optional
@type - {number}
- height - optional
@type - {string}
- quality - optional
@type - {string}
- let:src Image link
@type - {URL}
<script>
import { Flag } from 'metawrite';
</script>
<Flag code="canada" let:src>
<img src={String(src)} alt="flag" />
</Flag>
- url - required
@type - {string}
- width - optional
@type - {number}
- height - optional
@type - {number}
- let:src Image link
@type - {URL}
<script>
import { Image } from 'metawrite';
let url = 'https://increas.io/';
let width,
height = 100;
</script>
<Image {url} {width} {height} let:src>
<img src={String(src)} alt="someImage" />
</Image>
- text - required
@type - {string}
- size - optional
@type - {optional}
- margin - optional
@type - {number}
- download - optional
@type - {boolean}
- let:src Image link
@type - {URL}
<script>
import { QR } from 'metawrite';
let text = 'https://increas.io/'; // could be any text
let size = 500;
let margin = 1;
let download = false;
</script>
<QR {text} {size} {margin} {download} let:src>
<img src={String(src)} alt="QR Code" />
</QR>
The Database components allow you to create structured collections of documents, query and filter lists of documents, and manage an advanced set of read and write access permissions.
-
collectionId - required
@type - {string}
-
cache - optional, by default set to false
@type - {boolean}
query:
@type - {object}
-
queries - optional
@type - {string[]}
-
limit - optional
@type - {number}
-
offset - optional
@type - {number}
-
cursor - optional
@type - {string}
-
cursorDirection - optional
@type - {string}
-
orderAttributes - optional
@type - {string[]}
-
orderTypes - optional
@type - {string[]}
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
create(documentId, data, read, write) |
Creates a Document. data - @type - {string} .read /write is optional @type - {string[]} .documentId is optional, by default generates unique @type - {string} . |
- let:documents
- let:error
<script>
import { Collection } from "metawrite";
</script>
<Collection collectionId="5f56a3035a01f" let:documents>
You have {documents.length} documents.
</Collection>
- documentId - required
@type - {string}
- collectionId - required
@type - {string}
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
update(data) |
Updates a Document. data - @type - {object} |
remove() |
Removes a Document. |
- let:document
- let:error
<script>
import { Collection, Document } from 'metawrite';
const collectionId = '5f56a3035a01f';
</script>
<Collection {collectionId} let:documents>
You have {documents.length} documents:
{#each documents as document}
<Document {collectionId} documentId={document.$id} let:document let:actions>
Title: {document.title}
Text: {document.text}
<button on:click={() => {actions.remove()}}>Delete</button>
</Document>
{/each}
</Collection>
For more information about using Realtime in Appwrite see Realtime documentation.
Realtime allows you to listen to any events on the server-side in realtime using the subscribe method.
Instead of requesting new data via HTTP, the subscription will receive new data every time it changes, any connected client receives that update within milliseconds via a WebSocket connection.
This lets you build an interactive and responsive user experience by providing information from all of Appwrite's services in realtime.
- channels - required
string | string[]
let:payload - The payload from the subscription will contain following properties.
let:actions
Name | Description |
---|---|
subscribe() |
Subscribing to all updates related to one or more channels. |
unsubscribe() |
If you no longer want to receive updates from a subscription, you can unsubscribe so that your callbacks are no longer called. |
<script>
import { Realtime } from 'metawrite';
</script>
<Realtime channels="account" let:actions let:payload>
<h1>{payload.timestamp}</h1>
<button on:click={actions.subscribe()}>Subscribe to Account channel</button>
<button on:click={actions.unsubscribe()}>Unsubscribe from Account channel</button>
</Realtime>
The Storage components allow you to manage your project files. You can upload, view, download, and query all your project files.
let:actions
Name | Description |
---|---|
create(bucketId, fileId, file, read, write) |
Uploads a file. fileId is required @type - {string} , "unique()" will generate random unique id, but you can use custom.file is @type - {File} and required.read /write is @type - {string[]} and optional |
<script lang="ts">
import { Storage } from "metawrite"
// Required
let bucketId = "default"
let file: File;
let fileId = "unique()"; // this will generate random unique id, but you can use custom
// Optional
let read: string[];
let write: string[];
</script>
<Storage {file} let:actions>
<button on:click={actions.create(bucketId, fileId, file, read, write)}>Upload File</button>
</Storage>
- bucketId - required
@type - {string}
- search - optional
@type - {string}
- limit - optional
@type - {number}
- offset - optional
@type - {number}
- cursor - optional
@type - {string}
- cursorDirection - optional
@type - {string}
- orderType - optional
@type - {string}
=> write"ASC"
or"DESC"
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:files
- let:error
<script>
import { FileList } from "metawrite"
// Optional
let bucketId = 'default';
let search = '';
let limit = 10;
let offset = 0;
let orderType = 'ASC';
</script>
<FileList {bucketId} {search} {limit} {offset} {orderType}let:actions let:files>
{#each files as file}
<p>File: {file.name}</p>
{/each}
<button on:click={actions.reload()}>Reload</button>
</FileList>
- bucketId - it is your Bucket ID
@type - {string}
- fileId - it is File ID
@type - {string}
let:actions
Name | Description |
---|---|
download() |
Downloads file. |
view() |
Get file for View. |
preview(width, height, quality, background, output) |
Get file for preview. |
update(read, write) |
Updates a file. |
delete() |
Deletes a file. |
<script lang="ts">
import { File } from 'metawrite';
// Required
let bucketId: string;
let fileId: string;
// OPTIONAL
/** @type {number} */ let width;
/** @type {number} */ let height;
/** @type {string} */ let gravity;
/** @type {number} */ let quality;
/** @type {number} */ let borderWidth;
/** @type {string} */ let borderColor;
/** @type {number} */ let borderRadius;
/** @type {number} */ let opacity;
/** @type {number} */ let rotation;
/** @type {string} */ let background;
/** @type {string} */ let output;
/** @type {string[]} */ let read;
/** @type {string[]} */ let write;
</script>
<File {bucketId} {fileId} let:actions>
<button on:click={actions.download()}>Download File</button>
<button on:click={actions.view()}>File View</button>
<button on:click={actions.preview()}>Preview File</button>
<button on:click={actions.update(read, write)}>Update File</button>
<button on:click={actions.delete()}>Delete File</button>
</File>
The Functions service allows you to create custom behaviour that can be triggered by any supported Appwrite system events or by a predefined schedule.
Appwrite Cloud Functions lets you automatically run backend code in response to events triggered by Appwrite or by setting it to be executed in a predefined schedule. Your code is stored in a secure way on your Appwrite instance and is executed in an isolated environment.
You can learn more by following Appwrite's Cloud Functions tutorial.
let:actions
Name | Description |
---|---|
reload() |
Reload. |
create(functionId, data) |
Creates Execution. functionId is required, data could be empty string because optional. @type {string} |
create(functionId, executionId) |
Get Execution. Both parameters are required. @type {string} |
- let:executions
- error
<script>
import { Function } from 'metawrite';
let functionId = 'someExecution'; // required
let newFunctionId = '';
let data = 'String of custom data to send to function.'; // could be empty string because optional
</script>
<Function {functionId} {data} let:actions let:executions>
{#each executions as execution}
<p>
Execution ID: {execution.$id}, Function ID: {execution.functionId}, Date Created: {execution.dateCreated}
</p>
{/each}
<input type="text" name="functionId" placeholder="Function ID" bind:value={newFunctionId} />
<button on:click={actions.create(newFunctionId, data)}>Create Execution</button>
</Function>
The Locale components allow you to customize your app based on your users' location.
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:continents
- loading
- error
<script>
import { Continents } from 'metawrite';
</script>
<Continents let:actions let:continents>
<button on:click={actions.reload()}>Reload</button>
<p>There are {continents.sum} continents:</p>
{#each continents.continents as continent}
<p>{continent.name}, {continent.code}</p>
{/each}
</Continents>
- eu
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:countries
<script>
import { Countries } from 'metawrite';
let eu = true; // if you want to list only EU countries
</script>
<Countries let:actions let:countries>
<button on:click={actions.reload()}>Reload</button>
<p>There are {countries.sum} countries in the world:</p>
{#each countries.countries as country}
<p>{country.name}, {country.code}</p>
{/each}
</Countries>
<Countries {eu} let:actions let:countries>
<button on:click={actions.reload()}>Reload</button>
<p>There are {countries.sum} countries in EU:</p>
{#each countries.countries as country}
<p>{country.name}, {country.code}</p>
{/each}
</Countries>
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:currencies
<script>
import { Currencies } from 'metawrite';
</script>
<Currencies let:actions let:currencies>
<button on:click={actions.reload()}>Reload</button>
<p>There are {currencies.sum} currencies:</p>
{#each currencies.currencies as currency}
<p>{currency.symbol} - {currency.name} ({currency.code})</p>
{/each}
</Currencies>
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:languages
<script>
import { Languages } from 'metawrite';
</script>
<Languages let:actions let:languages>
<button on:click={actions.reload()}>Reload</button>
<p>There are {languages.sum} languages:</p>
{#each languages.languages as language}
<p>{language.name}, {language.code}></p>
{/each}
</Languages>
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:code
object
<script>
import { Locale } from 'metawrite';
</script>
<Locale let:actions let:code>
<h1>Active Session</h1>
<button on:click={actions.reload()}>Reload</button>
<p>Location: {code.country}, {code.continentCode}</p>
<p>IP: {code.ip}</p>
</Locale>
- loading
- error
let:actions
Name | Description |
---|---|
reload() |
Reload. |
- let:codes
<script>
import { PhoneCodes } from 'metawrite';
</script>
<PhoneCodes let:actions let:codes>
<button on:click={actions.reload()}>Reload</button>
<p>There are {codes.sum} phone codes:</p>
{#each codes.phones as phone}
<p>{phone.code} - {phone.countyName}></p>
{/each}
</PhoneCodes>