Padrões Appwrite
Guia Rápido: Use o Appwrite como seu BaaS open-source para autenticação, dados estruturados (TablesDB), armazenamento de arquivos, funções serverless e inscrições em tempo real. Sempre inicialize as classes de serviço a partir de uma instância
Clientcompartilhada, defina permissões explicitamente em cada linha (nada é acessível por padrão) e use o SDK do servidor (node-appwrite) com autenticação por chave de API apenas no backend.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo código deve seguir as convenções do projeto em CLAUDE.md (kebab-case, exports nomeados, ordenação de imports,
import type, constantes nomeadas)
(Você DEVE definir permissões explicitamente em cada linha e arquivo — o Appwrite concede NENHUM acesso por padrão, portanto omitir permissões torna os dados inacessíveis)
(Você DEVE usar node-appwrite com autenticação por chave de API no servidor e appwrite com autenticação por sessão no cliente — NUNCA exponha chaves de API em bundles do cliente)
(Você DEVE sempre verificar AppwriteException em cada chamada do SDK — o Appwrite lança exceções, NÃO retorna tuplas { data, error })
(Você DEVE usar ID.unique() para IDs gerados automaticamente — passar uma string bruta cria um ID personalizado, não um gerado automaticamente)
(Você DEVE usar a API TablesDB para novos projetos — a API legada de Databases/coleções/documentos está obsoleta e recebe apenas correções de segurança)
</critical_requirements>
Detecção automática: Appwrite, appwrite, node-appwrite, TablesDB, Account, Databases, Permission, Role, ID.unique, Query.equal, createEmailPasswordSession, realtime.subscribe, Channel.files, Channel.tablesdb, APPWRITE_FUNCTION
Quando usar:
- Configurar o SDK do cliente ou servidor Appwrite com TypeScript
- Implementar autenticação (email/senha, OAuth, URL mágica, OTP por telefone, sessões anônimas)
- Realizar CRUD em tabelas TablesDB (linhas, consultas, permissões)
- Enviar e servir arquivos de buckets Storage com controle de acesso
- Construir funções serverless acionadas por eventos, agendamentos ou HTTP
- Inscrever-se em mudanças em tempo real em linhas, arquivos ou eventos de conta
- Gerenciar associações de equipe e permissões baseadas em funções
Padrões principais cobertos:
- Inicialização do SDK do cliente e servidor com classes de serviço tipadas
- Fluxos de autenticação: cadastro, login, OAuth, URL mágica, gerenciamento de sessão
- Operações TablesDB com classe
Querypara filtragem, paginação, ordenação - Modelo de permissão:
Permission.read(Role.any()),Role.user(),Role.team() - Armazenamento: upload, download, pré-visualização com transformações de imagem, permissões de bucket
- Funções serverless:
export default async ({ req, res, log, error }) => {} - Inscrições em tempo real via helpers
Channelerealtime.subscribe()
Quando NÃO usar:
- Conexões diretas com banco de dados ou consultas SQL (Appwrite é apenas API, sem SQL bruto)
- Junções relacionais complexas entre muitas tabelas (Appwrite suporta relacionamentos, mas não junções SQL arbitrárias)
- Aplicações que exigem tempo real no lado do servidor (Appwrite Realtime é apenas SDK do cliente)
Recursos Detalhados:
- Para frameworks de decisão e anti-padrões, veja reference.md
Cliente e Consultas:
- examples/core.md — Configuração do cliente, CRUD TablesDB, tratamento de erros, permissões
Autenticação:
- examples/auth.md — Fluxos completos de autenticação, OAuth, URL mágica, sessões, equipes
Armazenamento e Funções:
- examples/storage.md — Upload, download, pré-visualizações, permissões de bucket
- examples/functions.md — Funções serverless, gatilhos, uso do SDK dentro de funções
Tempo Real:
- examples/realtime.md — Inscrições em canais, filtragem de eventos, limpeza
Filosofia
Appwrite é um backend-como-serviço open-source que fornece autenticação, banco de dados (TablesDB), armazenamento de arquivos, funções serverless e tempo real — tudo através de um SDK unificado. Pode ser auto-hospedado ou usado via Appwrite Cloud.
Princípios centrais:
- Seguro por padrão — Nada é acessível sem permissões explícitas. Cada linha e arquivo deve ter permissões definidas, ou será invisível para todos os usuários. Isso é o oposto de "aberto por padrão" — trate como uma etapa obrigatória, não um pensamento posterior.
- Arquitetura de classes de serviço — Todas as interações com o SDK passam por classes de serviço (
Account,TablesDB,Storage,Functions,Teams,Realtime) instanciadas a partir de umClientcompartilhado. Esse padrão é consistente entre SDKs do cliente e servidor. - Divisão em dois SDKs —
appwrite(cliente) usa autenticação baseada em sessão para navegadores.node-appwrite(servidor) usa autenticação por chave de API para backends. Eles compartilham a mesma forma de API, mas mecanismos de autenticação diferentes. Nunca os misture. - Exceções, não tuplas — Appwrite lança
AppwriteExceptionem caso de falha, não tuplas{ data, error }. Sempre envolva chamadas em try/catch. - TablesDB é o futuro — Appwrite 1.8 introduziu TablesDB (tabelas/linhas/colunas) como a API moderna. A API legada Databases (coleções/documentos/atributos) ainda funciona, mas está obsoleta. Novos recursos chegam apenas no TablesDB.
- Geração de IDs — Use
ID.unique()para IDs únicos gerados pelo servidor. Se você passar uma string diretamente, ela se torna um ID personalizado (que deve ser globalmente único dentro da tabela).
Quando usar Appwrite:
- BaaS open-source, auto-hospedável, com controle total sobre seus dados
- Projetos que precisam de autenticação, banco de dados, armazenamento e funções em uma plataforma
- Equipes que desejam um BaaS auto-hospedável sem dependência de fornecedor
- Aplicações que se beneficiam de permissões granulares em nível de documento/linha
Quando NÃO usar:
- Aplicações complexas com SQL pesado que exigem junções, visões e procedimentos armazenados
- Consumidores de tempo real no lado do servidor (Appwrite Realtime é apenas SDK do cliente — sem suporte ao SDK do servidor)
- Aplicações offline-first que exigem sincronização local (Appwrite não possui sincronização offline integrada)
Padrões Principais
Padrão 1: Configuração do SDK do Cliente (Navegador)
Inicialize o cliente Appwrite com endpoint e ID do projeto. Todas as classes de serviço compartilham uma única instância Client.
// lib/appwrite.ts
import { Client, Account, TablesDB, Storage, Realtime } from "appwrite";
const APPWRITE_ENDPOINT = process.env.APPWRITE_ENDPOINT!;
const APPWRITE_PROJECT_ID = process.env.APPWRITE_PROJECT_ID!;
const client = new Client()
.setEndpoint(APPWRITE_ENDPOINT)
.setProject(APPWRITE_PROJECT_ID);
export const account = new Account(client);
export const tablesDB = new TablesDB(client);
export const storage = new Storage(client);
export const realtime = new Realtime(client);
Por que é bom: Instância única do cliente compartilhada entre serviços, constantes nomeadas para configuração, exports nomeados para cada serviço, variáveis de ambiente mantêm a configuração fora do código
// RUIM: Configuração hardcoded, recriando clientes
import { Client, Account } from "appwrite";
const account = new Account(
new Client()
.setEndpoint("https://cloud.appwrite.io/v1") // Hardcoded
.setProject("abc123"), // ID do projeto hardcoded
);
Por que é ruim: Endpoint e ID do projeto hardcoded, novo Client por serviço desperdiça recursos, sem configuração compartilhada
Padrão 2: Configuração do SDK do Servidor (Node.js)
O SDK do servidor usa autenticação por chave de API — nunca exponha chaves de API em código do cliente.
// lib/appwrite-server.ts
import { Client, TablesDB, Users, Storage } from "node-appwrite";
const APPWRITE_ENDPOINT = process.env.APPWRITE_ENDPOINT!;
const APPWRITE_PROJECT_ID = process.env.APPWRITE_PROJECT_ID!;
const APPWRITE_API_KEY = process.env.APPWRITE_API_KEY!;
const client = new Client()
.setEndpoint(APPWRITE_ENDPOINT)
.setProject(APPWRITE_PROJECT_ID)
.setKey(APPWRITE_API_KEY);
export const tablesDB = new TablesDB(client);
export const users = new Users(client);
export const storage = new Storage(client);
Por que é bom: .setKey() para autenticação por chave de API (apenas servidor), serviço Users para gerenciamento de usuários administrador (não disponível no SDK do cliente), constantes nomeadas
Quando usar: Rotas de API, funções serverless, scripts de administração, webhooks. NUNCA importe este módulo de código do lado do cliente.
Padrão 3: Tratamento de Erros (AppwriteException)
O Appwrite lança AppwriteException — NÃO retorna tuplas { data, error }. Sempre use try/catch.
import { AppwriteException, type Models } from "appwrite";
async function getUser(): Promise<Models.User<Models.Preferences>> {
try {
return await account.get();
} catch (error) {
if (error instanceof AppwriteException) {
// error.message — mensagem legível
// error.code — código de status HTTP (401, 404, etc.)
// error.type — string do tipo de erro legível por máquina
throw new Error(`Erro Appwrite ${error.code}: ${error.message}`);
}
throw error;
}
}
Por que é bom: AppwriteException com tipo estrito fornece code, message, type; relança erros desconhecidos; tipo de retorno explícito usando namespace Models
// RUIM: Assumindo retorno de tupla { data, error }
const { data, error } = await account.get(); // ERRADO — Appwrite lança, não retorna tuplas
if (error) {
/* ... */
}
Por que é ruim: Appwrite NÃO retorna tuplas de erro — este código falhará silenciosamente porque account.get() ou retorna dados ou lança
Padrão 4: Operações TablesDB (CRUD)
Use TablesDB para todas as operações de banco de dados. IDs de linha são necessários para criação — use ID.unique() para geração automática.
Criar uma Linha
import { ID, Permission, Role } from "appwrite";
interface Todo {
title: string;
completed: boolean;
}
const DATABASE_ID = "main";
const TABLE_ID = "todos";
const row = await tablesDB.createRow<Todo>({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
rowId: ID.unique(),
data: {
title: "Comprar mantimentos",
completed: false,
},
permissions: [
Permission.read(Role.user(userId)),
Permission.update(Role.user(userId)),
Permission.delete(Role.user(userId)),
],
});
Listar Linhas com Consultas
import { Query } from "appwrite";
const PAGE_SIZE = 25;
const result = await tablesDB.listRows<Todo>({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
queries: [
Query.equal("completed", false),
Query.orderDesc("$createdAt"),
Query.limit(PAGE_SIZE),
],
});
// result.rows — array de linhas Todo
// result.total — total de correspondências
Atualizar uma Linha
const updated = await tablesDB.updateRow<Todo>({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
rowId: row.$id,
data: { completed: true },
});
Deletar uma Linha
await tablesDB.deleteRow({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
rowId: row.$id,
});
Por que é bom: Constantes nomeadas para IDs de banco de dados/tabela, ID.unique() para IDs gerados automaticamente, permissões definidas explicitamente na criação, classe Query para filtragem com tipo seguro, parâmetro de tipo genérico para formato da linha
Padrão 5: Modelo de Permissões
O Appwrite concede NENHUM acesso por padrão. Você deve definir permissões em cada linha e arquivo.
Sintaxe Permission + Role
import { Permission, Role } from "appwrite";
// Leitura pública, acesso total do proprietário
const publicReadPermissions = [
Permission.read(Role.any()),
Permission.update(Role.user(userId)),
Permission.delete(Role.user(userId)),
];
// Acesso de equipe
const teamPermissions = [
Permission.read(Role.team(teamId)),
Permission.update(Role.team(teamId, "admin")),
Permission.delete(Role.team(teamId, "owner")),
];
// Apenas usuários verificados
const verifiedOnlyPermissions = [Permission.read(Role.users("verified"))];
Helpers de Role Comuns
Role.any(); // Qualquer pessoa (incluindo convidados)
Role.guests(); // Apenas usuários não autenticados
Role.users(); // Todos os usuários autenticados
Role.users("verified"); // Apenas usuários verificados
Role.user(userId); // Usuário específico por ID
Role.team(teamId); // Todos os membros de uma equipe
Role.team(teamId, "admin"); // Membros da equipe com função "admin"
Role.member(membershipId); // Associação de equipe específica
Role.label("premium"); // Usuários com rótulo "premium"
Por que é bom: Permissões explícitas em cada recurso, helpers de role com tipo seguro, roles de equipe permitem acesso granular
// RUIM: Criar uma linha sem permissões
const row = await tablesDB.createRow({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
rowId: ID.unique(),
data: { title: "Segredo" },
// NENHUMA permissão definida — esta linha está INVISÍVEL para todos!
});
Por que é ruim: Sem permissões, a linha existe no banco de dados, mas NENHUM usuário pode ler, atualizar ou deletá-la (nem mesmo o criador) — este é o erro mais comum no Appwrite
Padrão 6: Fluxos de Autenticação
Use o serviço Account para todas as operações de autenticação.
Cadastro e Login com Email/Senha
import { ID, type Models } from "appwrite";
// Cadastro: criar conta + criar sessão (duas etapas)
const user = await account.create({
userId: ID.unique(),
email,
password,
name,
});
const session = await account.createEmailPasswordSession({ email, password });
// Login
const session = await account.createEmailPasswordSession({ email, password });
// Logout (dispositivo atual)
await account.deleteSession({ sessionId: "current" });
Por que é bom: Cadastro em duas etapas (criar conta + criar sessão), parâmetros de objeto para todas as chamadas do SDK, deleteSession({ sessionId: "current" }) apenas para o dispositivo atual
Veja examples/auth.md para fluxos completos de autenticação, incluindo OAuth, URL mágica, sessões anônimas, equipes e redefinição de senha.
Padrão 7: Operações de Armazenamento
Envie, baixe e pré-visualize arquivos com o serviço Storage.
import { ID, Permission, Role } from "appwrite";
const BUCKET_ID = "user-uploads";
const PREVIEW_WIDTH = 400;
const PREVIEW_HEIGHT = 300;
// Upload com permissões
await storage.createFile({
bucketId: BUCKET_ID,
fileId: ID.unique(),
file,
permissions: [
Permission.read(Role.user(userId)),
Permission.update(Role.user(userId)),
],
});
// Pré-visualização de imagem com transformações
const url = storage.getFilePreview({
bucketId: BUCKET_ID,
fileId: fileId,
width: PREVIEW_WIDTH,
height: PREVIEW_HEIGHT,
});
Por que é bom: Nomes de bucket como constantes, permissões definidas no upload, pré-visualização com transformações de imagem integradas para redimensionamento e corte
Veja examples/storage.md para padrões completos de upload, download, listagem e exclusão de arquivos.
Padrão 8: Funções Serverless
Funções Appwrite executam em resposta a eventos, agendamentos ou chamadas HTTP.
// src/functions/hello-world/index.ts
export default async ({ req, res, log, error }: any) => {
log("Função executando...");
try {
const { name } = JSON.parse(req.body || "{}");
return res.json({ message: `Olá, ${name || "mundo"}!` });
} catch (err) {
error("Falha ao processar requisição", err);
return res.json({ error: "Requisição inválida" }, 400);
}
};
Por que é bom: req e res para manipulação de entrada/saída HTTP, log e error para registro estruturado, try/catch para tratamento de erros
Veja examples/functions.md para padrões de funções com SDK do servidor, gatilhos de eventos, agendamentos e tarefas em segundo plano.
Padrão 9: Inscrições em Tempo Real
Use realtime.subscribe() com helpers Channel para reagir a mudanças em tempo real.
import { Channel } from "appwrite";
// Inscrever em mudanças em uma tabela específica
const unsubscribe = realtime.subscribe({
channels: [Channel.tablesdb({
databaseId: DATABASE_ID,
tableId: TABLE_ID,
})],
callback: (event) => {
console.log("Evento recebido:", event);
// event.events — array de strings de evento (ex: 'databases.*.collections.*.documents.*.create')
// event.payload — dados da linha
// event.channels — canais que dispararam o evento
},
});
// Inscrever em arquivos de bucket
const unsubscribeFiles = realtime.subscribe({
channels: [Channel.files(BUCKET_ID)],
callback: (event) => {
console.log("Arquivo mudou:", event.payload);
},
});
// Limpeza quando não for mais necessário
unsubscribe();
Por que é bom: Helpers Channel fornecem nomes de canal com tipo seguro, inscrições retornam função de cancelamento, evento inclui payload e metadados
Veja examples/realtime.md para filtragem de eventos, inscrições múltiplas, tratamento de erros e boas práticas de limpeza.
Padrão 10: Trabalhando com Equipes e Membros
Gerencie equipes e membros com o serviço Teams.
import { ID, Role, Permission } from "appwrite";
// Criar equipe
const team = await teams.create({
teamId: ID.unique(),
name: "Minha Equipe",
});
// Criar associação (convite)
const membership = await teams.createMembership({
teamId: team.$id,
email: "[email protected]",
roles: ["member"],
url: "https://meuapp.com/accept-invite",
});
// Listar equipes do usuário atual
const userTeams = await teams.list();
// Atualizar funções de membro
await teams.updateMembershipRoles({
teamId: team.$id,
membershipId: membership.$id,
roles: ["admin", "editor"],
});
Por que é bom: IDs únicos gerados automaticamente, suporte a múltiplas funções por membro, convites por email com URL personalizada para aceite
Padrão 11: Gerenciamento de Sessão e Persistência
Gerencie sessões de usuário explicitamente, especialmente para logouts e alternância de conta.
// Obter sessão atual
const session = await account.getSession({ sessionId: "current" });
// Listar todas as sessões do usuário
const sessions = await account.listSessions();
// Deletar sessão específica
await account.deleteSession({ sessionId: sessionId });
// Deletar todas as sessões (logout de todos os dispositivos)
await account.deleteSessions();
// Atualizar preferências do usuário
await account.updatePrefs({
prefs: {
theme: "dark",
language: "pt-BR",
},
});
Por que é bom: Controle granular sobre sessões, suporte a logout de dispositivo específico, persistência de configurações do usuário via updatePrefs
Padrão 12: Tratamento de Upload de Arquivos no Front-end
Use createFile com progresso de upload para melhor experiência do usuário.
import { ID } from "appwrite";
const BUCKET_ID = "user-uploads";
// Upload com callback de progresso
const response = await storage.createFile({
bucketId: BUCKET_ID,
fileId: ID.unique(),
file: selectedFile,
onProgress: (progress) => {
const percent = Math.round((progress.loaded / progress.total) * 100);
updateProgressBar(percent);
},
});
// Obter URL de download direto
const downloadUrl = storage.getFileDownload({
bucketId: BUCKET_ID,
fileId: response.$id,
});
// Obter URL de visualização (com transformações opcionais)
const previewUrl = storage.getFilePreview({
bucketId: BUCKET_ID,
fileId: response.$id,
width: 200,
height: 200,
gravity: "center",
quality: 80,
});
Por que é bom: Progresso de upload para feedback do usuário, URLs de download direto para compartilhamento, pré-visualizações com parâmetros de transformação (largura, altura, gravidade, qualidade)
Perguntas Frequentes
O que fazer se um dado não aparecer nas consultas?
Verifique se as permissões estão definidas corretamente. Se uma linha foi criada sem permissões, ela existe no banco de dados, mas é invisível para todas as consultas e solicitações de leitura. Use o SDK do servidor com uma chave de API para verificar e corrigir permissões.
Como migrar da API legada de Databases para TablesDB?
Consulte a documentação de migração do Appwrite. O skill fornece exemplos apenas para TablesDB, mas a API legada ainda funciona para sistemas existentes que requerem apenas correções de segurança.
Por que usar ID.unique() em vez de passar uma string?
ID.unique() gera um ID único globalmente no servidor, garantindo que não haja colisões. Se você passar uma string personalizada, ela deve ser única dentro do escopo da tabela/coleção, o que pode causar erros se não for gerenciada corretamente.
O Realtime funciona no lado do servidor?
Não. Appwrite Realtime é apenas SDK do cliente. Para funcionalidade de tempo real no servidor, use webhooks ou poling com o SDK do servidor.
Como proteger chaves de API?
Nunca coloque chaves de API em código do cliente. Use variáveis de ambiente no servidor (process.env.APPWRITE_API_KEY) e restrinja o escopo da chave API nas configurações do projeto Appwrite para os serviços necessários.
Boas Práticas e Checklists
Checklist de Configuração Inicial
- Endpoint e ID do projeto configurados via variáveis de ambiente
- SDK do cliente (
appwrite) instalado para front-end - SDK do servidor (
node-appwrite) instalado para back-end - Chave de API criada no console Appwrite com escopos mínimos
- Buckets de Storage criados com permissões de bucket apropriadas
- Tabelas TablesDB criadas com schema definido
- Provedores de autenticação configurados (email, OAuth, etc.)
Checklist de Operações CRUD
-
ID.unique()usado para novos registros (a menos que IDs personalizados sejam necessários) - Permissões definidas explicitamente em cada criação de linha/arquivo
- Chamadas do SDK envolvidas em try/catch para
AppwriteException - Consultas usam classe
Querypara filtragem e ordenação tipadas -
deleteSession({ sessionId: "current" })usado para logout de dispositivo específico
Checklist de Segurança
- Nenhuma chave de API exposta em código do cliente
- Permissões concedem apenas o acesso mínimo necessário
- Funções serverless validam entrada do usuário antes de processar
- Sessões expiradas ou inválidas são tratadas com redirect para login
- Dados sensíveis não são incluídos em respostas de erro
Exemplos de Anti-Padrões
Anti-Padrão 1: Compartilhar Instância do SDK
// RUIM: Usar a mesma instância de cliente para cliente e servidor
import { Client } from "appwrite";
import { Client as ServerClient } from "node-appwrite";
const client = new Client(); // Isso deve ser para navegador
// ... usando também para funções serverless
Solução: Manter SDKs separados (appwrite para cliente, node-appwrite para servidor) com instâncias de Client independentes.
Anti-Padrão 2: Ignorar Tratamento de Erros
// RUIM: Assumir que a chamada sempre funciona
const user = await account.get();
Solução: Sempre usar try/catch e verificar AppwriteException.
Anti-Padrão 3: Dados sem Permissões
// RUIM: Criar linha sem permissões
const row = await tablesDB.createRow({
databaseId: "main",
tableId: "items",
rowId: ID.unique(),
data: { name: "Item" },
// Sem permissions!
});
Solução: Sempre incluir permissions com Permission.read(Role.user(userId)) para garantir acesso ao criador.
Referências: