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
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
<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.
<User />
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}
|
object
logout
success.logout
failure.logoutFrom
success.logoutFrom
failure.logoutAll
success.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>
<Create />
let:actions
| Name | Description |
| --- | --- |
| create(email, password, name)
| Creates a user. email
and password
are required - @type - {string}
. name
is optional - @type - {string}
|
create
success.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>
<Preferences />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reloads preferences. |
| update(prefs)
| Update preferences. prefs
- @type - {object}
|
reload
success.reload
failure.update
success.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>
<RecoverPassword />
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}
. |
reload
success.reload
failure.update
success.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>
<Update />
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}
|
name
success.name
failure.email
success.email
failure.password
success.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>
<Verification />
Creates and automatically validates user email verification.
url
of type string for action create
should be where your app is hosted or localhost
.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
. |
create
success.create
failure.complete
success.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.
<AuthEmail />
authorize
success.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>
<AuthOAuth2 />
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>
<CreateAnonymousSession />
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>
<CreateJWT />
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>
<MagicURL />
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.
<Browser />
@type - {string}
@type - {number}
@type - {string}
@type - {string}
@type - {URL}
<script>
import { Browser } from 'metawrite';
</script>
<Browser code="firefox" let:src>
<img src={String(src)} alt="Browser" />
</Browser>
<CreditCard />
@type - {string}
@type - {number}
@type - {string}
@type - {string}
@type - {URL}
<script>
import { CreditCard } from 'metawrite';
</script>
<CreditCard code="amex" let:src>
<img src={String(src)} alt="card" />
</CreditCard>
<Favicon />
@type - {string}
@type - {URL}
<script>
import { Favicon } from 'metawrite';
const url = window.location.href;
</script>
<Favicon {url} let:src>
<img src={String(src)} alt="favicon" />
</Favicon>
<Flag />
@type - {string}
@type - {number}
@type - {string}
@type - {string}
@type - {URL}
<script>
import { Flag } from 'metawrite';
</script>
<Flag code="canada" let:src>
<img src={String(src)} alt="flag" />
</Flag>
<Image />
@type - {string}
@type - {number}
@type - {number}
@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>
<QR />
@type - {string}
@type - {optional}
@type - {number}
@type - {boolean}
@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.
<Collection />
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[]}
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}
. |
<script>
import { Collection } from "metawrite";
</script>
<Collection collectionId="5f56a3035a01f" let:documents>
You have {documents.length} documents.
</Collection>
<Document />
@type - {string}
@type - {string}
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
| update(data)
| Updates a Document. data
- @type - {object}
|
| remove()
| Removes a Document. |
<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.
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.
<Storage />
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>
<FileList />
@type - {string}
@type - {string}
@type - {number}
@type - {number}
@type - {string}
@type - {string}
@type - {string}
=> write "ASC"
or "DESC"
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>
<File />
@type - {string}
@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.
<Function />
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}
|
<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.
<Continents />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>
<Countries />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>
<Currencies />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>
<Languages />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>
<Locale />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
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>
<PhoneCodes />
let:actions
| Name | Description |
| --- | --- |
| reload()
| Reload. |
<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>