# Appwrite Cheatsheet for Next.js with TypeScript > ℹ️ **Version Compatibility**: Tested with Appwrite v1.4.x and Next.js 14.0.x ## Table of Contents - [Introduction](#introduction) - [Getting Started](#getting-started) - [Installation & Setup](#installation--setup) - [Authentication](#authentication) - [Database Operations](#database-operations) - [File Storage](#file-storage) - [Realtime Subscriptions](#realtime-subscriptions) - [Next.js Integration](#nextjs-integration) - [Custom React Hooks](#custom-react-hooks) - [Error Handling](#error-handling) - [Security Best Practices](#security-best-practices) - [Troubleshooting](#troubleshooting) - [Environment Setup](#environment-setup) ## Introduction Appwrite is a Backend-as-a-Service (BaaS) that integrates well with Next.js applications. This cheatsheet focuses on the essential knowledge needed when using Appwrite with a Next.js React TypeScript application. ## Getting Started Quick setup to get your Next.js app connected to Appwrite: 1. **Create Appwrite Project**: - Sign up at [cloud.appwrite.io](https://cloud.appwrite.io) - Create a new project - Note your Project ID 2. **Connect Your App**: ```bash npm install appwrite ``` 3. **Minimal Setup**: ```typescript // src/lib/appwrite.ts import { Client, Account, Databases } from 'appwrite'; const client = new Client() .setEndpoint('https://cloud.appwrite.io/v1') .setProject(process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID || ''); export const account = new Account(client); export const databases = new Databases(client); ``` 4. **First Query**: ```typescript // Example: Get user and fetch data const user = await account.get(); const documents = await databases.listDocuments( 'YOUR_DATABASE_ID', 'YOUR_COLLECTION_ID' ); ``` ## Installation & Setup ```bash npm install appwrite ``` ### Basic Setup for Next.js ```typescript // src/lib/appwrite.ts import { Client, Account, Databases, Storage, Functions, ID, Query } from 'appwrite'; // Initialize Client const client = new Client() .setEndpoint('https://cloud.appwrite.io/v1') // Your Appwrite endpoint .setProject(process.env.NEXT_PUBLIC_APPWRITE_PROJECT_ID || ''); // Initialize Services export const account = new Account(client); export const databases = new Databases(client); export const storage = new Storage(client); export const functions = new Functions(client); // Export utilities export { ID, Query }; ``` ## Authentication ### 🔑 Authentication Overview | Method | Client/Server | Description | |--------|---------------|-------------| | Email/Password | Client | Standard authentication | | OAuth | Client | Social login (Google, GitHub, etc.) | | Magic URL | Client | Passwordless email link | | Phone | Client | SMS verification | | JWT | Server | API access with custom JWT | | API Key | Server | Server-to-server secure access | ### User Registration ```typescript import { account, ID } from '@/lib/appwrite'; /** * Register a new user with email and password * @returns The created user object */ async function registerUser(email: string, password: string, name: string) { try { const user = await account.create( ID.unique(), email, password, name ); return user; } catch (error) { console.error('Error registering user:', error); throw error; } } ``` ### User Login ```typescript import { account } from '@/lib/appwrite'; async function loginUser(email: string, password: string) { try { const session = await account.createEmailSession(email, password); return session; } catch (error) { console.error('Error logging in:', error); throw error; } } ``` ### Login with React Hook ```typescript 'use client'; import { useState } from 'react'; import { account } from '@/lib/appwrite'; import { useRouter } from 'next/navigation'; export function useLogin() { const [isLoading, setIsLoading] = useState(false); const [error, setError] = useState(null); const router = useRouter(); const login = async (email: string, password: string) => { setIsLoading(true); setError(null); try { await account.createEmailSession(email, password); router.push('/dashboard'); return true; } catch (err: any) { setError(err.message || 'Login failed'); return false; } finally { setIsLoading(false); } }; return { login, isLoading, error }; } ``` ### OAuth Authentication ```typescript import { account } from '@/lib/appwrite'; /** * Initiate OAuth login flow * @param provider OAuth provider ('google', 'github', 'facebook', etc.) */ function loginWithOAuth(provider: string) { account.createOAuth2Session(provider, `${window.location.origin}/auth-success`, // Success URL `${window.location.origin}/auth-failure` // Failure URL ); } // Usage: loginWithOAuth('google'); ``` ### Get Current User ```typescript import { account } from '@/lib/appwrite'; /** * Retrieves the current logged-in user * @returns User object or null if not logged in */ async function getCurrentUser() { try { const user = await account.get(); return user; } catch (error) { console.error('Error getting current user:', error); return null; // User is not logged in } } ``` ### User Logout ```typescript import { account } from '@/lib/appwrite'; async function logoutUser() { try { await account.deleteSession('current'); return true; } catch (error) { console.error('Error logging out:', error); throw error; } } ``` ## Database Operations ### Types for Documents ```typescript // Example of a strongly-typed document interface Product { $id: string; $createdAt: string; $updatedAt: string; name: string; price: number; description: string; inStock: boolean; categories: string[]; } // Usage with typed results const product = await databases.getDocument( databaseId, collectionId, productId ); // Now TS knows product.name is a string and product.price is a number console.log(`${product.name}: $${product.price.toFixed(2)}`); ``` ### Creating a Document ```typescript import { databases, ID } from '@/lib/appwrite'; async function createDocument>( databaseId: string, collectionId: string, data: Omit ) { try { return await databases.createDocument( databaseId, collectionId, ID.unique(), data ); } catch (error) { console.error('Error creating document:', error); throw error; } } ``` ### Retrieving a Document ```typescript import { databases } from '@/lib/appwrite'; async function getDocument( databaseId: string, collectionId: string, documentId: string ) { try { return await databases.getDocument( databaseId, collectionId, documentId ); } catch (error) { console.error('Error fetching document:', error); throw error; } } ``` ### Listing Documents with Query ```typescript import { databases, Query } from '@/lib/appwrite'; async function listDocuments( databaseId: string, collectionId: string, filters: any[] = [] ) { try { const response = await databases.listDocuments( databaseId, collectionId, filters ); return response.documents; } catch (error) { console.error('Error listing documents:', error); throw error; } } // Usage // const products = await listDocuments( // 'database_id', // 'products', // [ // Query.equal('inStock', true), // Query.greaterThan('price', 500), // Query.limit(10) // ] // ); ``` ### Updating a Document ```typescript import { databases } from '@/lib/appwrite'; async function updateDocument( databaseId: string, collectionId: string, documentId: string, data: Partial> ) { try { return await databases.updateDocument( databaseId, collectionId, documentId, data ); } catch (error) { console.error('Error updating document:', error); throw error; } } ``` ### Deleting a Document ```typescript import { databases } from '@/lib/appwrite'; async function deleteDocument( databaseId: string, collectionId: string, documentId: string ) { try { await databases.deleteDocument(databaseId, collectionId, documentId); return true; } catch (error) { console.error('Error deleting document:', error); throw error; } } ``` ## Common Query Methods | Query Method | Description | Example | |--------------|-------------|---------| | `equal` | Equal comparison | `Query.equal('status', 'active')` | | `notEqual` | Not equal comparison | `Query.notEqual('status', 'archived')` | | `lessThan` | Less than comparison | `Query.lessThan('price', 100)` | | `greaterThan` | Greater than comparison | `Query.greaterThan('rating', 4)` | | `search` | Full-text search | `Query.search('title', 'nextjs')` | | `orderDesc` | Order descending | `Query.orderDesc('createdAt')` | | `orderAsc` | Order ascending | `Query.orderAsc('name')` | | `limit` | Limit results | `Query.limit(20)` | | `offset` | Offset results | `Query.offset(20)` | ## File Storage ### 📁 Upload File ```typescript import { storage, ID } from '@/lib/appwrite'; /** * Upload a file to Appwrite Storage * @returns The uploaded file data */ async function uploadFile(bucketId: string, file: File) { try { return await storage.createFile( bucketId, ID.unique(), file ); } catch (error) { console.error('Error uploading file:', error); throw error; } } ``` ### Get File Preview URL ```typescript import { storage } from '@/lib/appwrite'; /** * Get a preview URL for an image with optional resizing */ function getFilePreview( bucketId: string, fileId: string, width?: number, height?: number ) { return storage.getFilePreview( bucketId, fileId, width, height ); } // Usage // Profile

``` ### Delete File ```typescript import { storage } from '@/lib/appwrite'; async function deleteFile(bucketId: string, fileId: string) { try { await storage.deleteFile(bucketId, fileId); return true; } catch (error) { console.error('Error deleting file:', error); throw error; } } ``` ## Realtime Subscriptions ### Subscribe to Document Changes ```typescript 'use client'; import { useEffect } from 'react'; import { client } from '@/lib/appwrite'; /** * React hook to subscribe to realtime document changes */ function useDocumentSubscription( databaseId: string, collectionId: string, documentId: string, callback: (payload: any) => void ) { useEffect(() => { const unsubscribe = client.subscribe( `databases.${databaseId}.collections.${collectionId}.documents.${documentId}`, callback ); // Cleanup subscription when component unmounts return () => { unsubscribe(); }; }, [databaseId, collectionId, documentId, callback]); } // Usage // useDocumentSubscription( // 'database_id', // 'products', // 'product_id', // (payload) => { // console.log('Document updated:', payload); // // Update UI with new data // } // ); ``` ## Next.js Integration ### Client vs Server Components | Feature | Client Component | Server Component | Notes | |---------|------------------|-----------------|-------| | Authentication | ✅ Full Support | ⚠️ Limited | Server components need API keys | | Realtime | ✅ Yes | ❌ No | Realtime requires client-side code | | File Upload | ✅ Yes | ❌ No | User interaction required | | Database CRUD | ✅ Yes | ✅ Yes | Server is better for initial data | | Functions | ✅ Yes | ✅ Yes | - | | Security | ⚠️ Exposed Keys | ✅ Secure | Use environment variables | ### Client Components ```typescript 'use client'; import { useState, useEffect } from 'react'; import { databases } from '@/lib/appwrite'; import { ErrorBoundary } from '@/components/ErrorBoundary'; // Recommended interface Product { $id: string; name: string; price: number; } export default function ProductList() { const [products, setProducts] = useState([]); const [loading, setLoading] = useState(true); useEffect(() => { async function fetchProducts() { try { const response = await databases.listDocuments( process.env.NEXT_PUBLIC_APPWRITE_DATABASE_ID!, 'products' ); setProducts(response.documents); } catch (error) { console.error('Error fetching products:', error); } finally { setLoading(false); } } fetchProducts(); }, []); if (loading) return

; return ( Something went wrong}>

Products

{product.name} - ${product.price}

); } ``` ### Server Components (Next.js 13+) ```typescript // src/lib/appwrite-server.ts - Server-side initialization import { Client, Databases } from 'node-appwrite'; // Initialize Server SDK const client = new Client() .setEndpoint('https://cloud.appwrite.io/v1') .setProject(process.env.APPWRITE_PROJECT_ID!) .setKey(process.env.APPWRITE_API_KEY!); export const databases = new Databases(client); ``` ```typescript // src/app/products/page.tsx import { databases } from '@/lib/appwrite-server'; import { notFound } from 'next/navigation'; interface Product { $id: string; name: string; price: number; } export default async function ProductsPage() { try { const response = await databases.listDocuments( process.env.APPWRITE_DATABASE_ID!, 'products' ); return (

Products

{product.name} - ${product.price}

); } catch (error) { console.error('Error fetching products:', error); return notFound(); } } ``` ### Authentication Check in App Router ```typescript // src/lib/auth-check.ts import { cookies } from 'next/headers'; import { Client, Account } from 'node-appwrite'; export async function getServerSession() { try { const cookieStore = cookies(); const appwriteSessionName = 'a_session_'; // Find the Appwrite session cookie const sessionCookies = cookieStore.getAll().filter(cookie => cookie.name.startsWith(appwriteSessionName) ); if (sessionCookies.length === 0) { return null; } // Initialize server-side Appwrite client const client = new Client() .setEndpoint('https://cloud.appwrite.io/v1') .setProject(process.env.APPWRITE_PROJECT_ID!) .setSelfSigned(true); // Only for self-hosted Appwrite // Forward cookies sessionCookies.forEach(cookie => { client.setHTTPCookie(cookie.name, cookie.value); }); const account = new Account(client); const user = await account.get(); return { user }; } catch (error) { console.error('Auth check error:', error); return null; } } ``` ### Protected Route in App Router ```typescript // src/app/dashboard/page.tsx import { getServerSession } from '@/lib/auth-check'; import { redirect } from 'next/navigation'; export default async function DashboardPage() { const session = await getServerSession(); if (!session) { redirect('/login'); } return (

Dashboard

Welcome, {session.user.name}

{/* Dashboard content */}

); } ``` ## Error Handling ```typescript import { AppwriteException } from 'appwrite'; /** * Convert Appwrite errors into user-friendly messages */ export function handleAppwriteError(error: unknown): string { if (error instanceof AppwriteException) { switch (error.code) { case 401: return 'Authentication required. Please login.'; case 404: return 'Resource not found.'; case 409: return 'Resource already exists.'; case 429: return 'Too many requests. Please try again later.'; default: return error.message || 'An unknown error occurred'; } } return 'An unexpected error occurred'; } // Usage // try { // await createDocument(...); // } catch (error) { // const errorMessage = handleAppwriteError(error); // setError(errorMessage); // } ``` ## Security Best Practices ### 🔒 Security Tips 1. **Keep API Keys Secure** - Never expose API keys in client-side code - Use environment variables and access them only in server components - Implement proper CORS settings in your Appwrite console 2. **Use Proper Permissions** - Define granular collection permissions (read/write/update/delete) - Use collection-level security to filter documents by user ID - Consider adding a document attribute `userId` and create matching rules 3. **Validate User Input** - Always validate data on both client and server - Create validation functions for sensitive operations 4. **Implement Rate Limiting** ```typescript // Example of client-side throttling import { throttle } from 'lodash'; const throttledSearch = throttle(async (query) => { // Perform search operation const results = await searchDocuments(query); return results; }, 1000); // Max one request per second ``` 5. **Sessions & Authentication** - Set appropriate session durations - Implement refresh token patterns for long-lived sessions - Consider MFA for sensitive applications ## Troubleshooting ### 🔧 Common Issues and Solutions #### "Invalid Project ID" Error - **Problem**: SDK operations fail with project ID errors - **Solution**: Verify your Project ID in the Appwrite console and ensure environment variables are loaded correctly #### Authentication Issues - **Problem**: Users get logged out unexpectedly - **Solution**: Check CORS settings in Appwrite console, ensure domains match exactly #### "Permission Denied" Errors - **Problem**: Database queries fail with permission errors - **Solution**: 1. Check collection permissions in Appwrite console 2. Verify the user has appropriate role assignments 3. Check document security attributes match the user #### API Key Limitations - **Problem**: Server operations fail despite valid API key - **Solution**: Ensure API key has appropriate scopes for the operations #### Next.js Data Fetching Issues - **Problem**: Server components can't access Appwrite data - **Solution**: Use the node-appwrite SDK with API keys for server components #### Realtime Updates Not Working - **Problem**: Subscriptions don't receive updates - **Solution**: ```typescript // Verify subscription path format const channelId = `databases.${databaseId}.collections.${collectionId}.documents`; // Use wildcard for all documents in collection const unsubscribe = client.subscribe(channelId, response => { console.log('Received update:', response); }); ``` ## Environment Setup ### .env.local ``` # Client-side variables (accessible in browser) NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 NEXT_PUBLIC_APPWRITE_PROJECT_ID=your-project-id NEXT_PUBLIC_APPWRITE_DATABASE_ID=your-database-id NEXT_PUBLIC_APPWRITE_STORAGE_BUCKET_ID=your-bucket-id # Server-side only variables (not exposed to browser) APPWRITE_API_KEY=your-api-key APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 APPWRITE_PROJECT_ID=your-project-id APPWRITE_DATABASE_ID=your-database-id ``` ## Custom React Hooks ### useAuth Hook ```typescript 'use client'; import { useState, useEffect, createContext, useContext } from 'react'; import { account, ID } from '@/lib/appwrite'; interface User { $id: string; name: string; email: string; // Add other user properties } interface AuthContextType { user: User | null; loading: boolean; login: (email: string, password: string) => Promise; logout: () => Promise; register: (email: string, password: string, name: string) => Promise; } const AuthContext = createContext(undefined); export function AuthProvider({ children }: { children: React.ReactNode }) { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); useEffect(() => { // Check if user is logged in const checkUser = async () => { try { const currentUser = await account.get(); setUser(currentUser); } catch (error) { setUser(null); } finally { setLoading(false); } }; checkUser(); }, []); const login = async (email: string, password: string) => { await account.createEmailSession(email, password); const loggedInUser = await account.get(); setUser(loggedInUser); }; const logout = async () => { await account.deleteSession('current'); setUser(null); }; const register = async (email: string, password: string, name: string) => { await account.create(ID.unique(), email, password, name); await login(email, password); }; return ( {children} ); } export function useAuth() { const context = useContext(AuthContext); if (context === undefined) { throw new Error('useAuth must be used within an AuthProvider'); } return context; } ``` ### useDatabase Hook ```typescript 'use client'; import { useState } from 'react'; import { databases, ID } from '@/lib/appwrite'; export function useDatabase(databaseId: string, collectionId: string) { const [loading, setLoading] = useState(false); const [error, setError] = useState(null); const getDocument = async (documentId: string): Promise => { setLoading(true); setError(null); try { const response = await databases.getDocument( databaseId, collectionId, documentId ); return response; } catch (err: any) { setError(err.message); return null; } finally { setLoading(false); } }; const listDocuments = async (queries: any[] = []): Promise => { setLoading(true); setError(null); try { const response = await databases.listDocuments( databaseId, collectionId, queries ); return response.documents; } catch (err: any) { setError(err.message); return []; } finally { setLoading(false); } }; const createDocument = async (data: any): Promise => { setLoading(true); setError(null); try { const response = await databases.createDocument( databaseId, collectionId, ID.unique(), data ); return response; } catch (err: any) { setError(err.message); return null; } finally { setLoading(false); } }; const updateDocument = async (documentId: string, data: any): Promise => { setLoading(true); setError(null); try { const response = await databases.updateDocument( databaseId, collectionId, documentId, data ); return response; } catch (err: any) { setError(err.message); return null; } finally { setLoading(false); } }; const deleteDocument = async (documentId: string): Promise => { setLoading(true); setError(null); try { await databases.deleteDocument( databaseId, collectionId, documentId ); return true; } catch (err: any) { setError(err.message); return false; } finally { setLoading(false); } }; return { getDocument, listDocuments, createDocument, updateDocument, deleteDocument, loading, error, }; } ``` ### Data Flow Diagram ``` ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ │ │ Next.js App │────▶│ Appwrite │────▶│ Database │ │ │◀────│ Services │◀────│ Storage │ │ │ │ │ │ Auth │ └────────────────┘ └────────────────┘ └────────────────┘ │ ▲ │ │ │ │ ▼ │ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ Client │ │ Server │ │ Components │ │ Components │ │ │ │ │ └────────────────┘ └────────────────┘ ```

Posts

postgresSQL notes

appwrite notes

Networks notes