Learning Objectives

Understand when to use server vs client Supabase clients
Perform CRUD operations with Supabase
Handle real-time subscriptions
Implement proper error handling
Use TypeScript for type-safe queries

1. Client Types Overview

Supabase provides different clients optimized for different contexts. Understanding when to use each client is crucial for building secure and performant applications.

Client Type	Use Case	Cookie Access	RLS
Browser Client	Client Components, real-time	Browser cookies	User context
Server Client	Server Components, Actions	Request cookies	User context
Admin Client	Server-only admin tasks	N/A	Bypasses RLS

When to Use Each

The following examples demonstrate the correct client to use in different Next.js contexts. Using the wrong client can lead to security issues or broken functionality.

// CLIENT COMPONENT - Use browser client
"use client";
import { createClient } from "@/lib/supabase/client";

export function ClientComponent() {
  const supabase = createClient();
  // Real-time, mutations, client-side data
}

// SERVER COMPONENT - Use server client
import { createClient } from "@/lib/supabase/server";

export default async function ServerComponent() {
  const supabase = await createClient();
  // Fetch data, protected routes, SSR
}

// SERVER ACTION / API ROUTE - Use server or admin client
import { createClient } from "@/lib/supabase/server";
import { createAdminClient } from "@/lib/supabase/admin";

export async function serverAction() {
  const supabase = await createClient(); // User context
  const adminSupabase = createAdminClient(); // Admin access
}

2. Fetching Data in Server Components

Server Components are ideal for initial data fetching because they run on the server, reducing client-side JavaScript and improving performance.

Basic Query

This example shows a basic query in a Server Component. The data is fetched on the server and rendered to HTML before being sent to the client.

// app/(dashboard)/products/page.tsx
import { createClient } from '@/lib/supabase/server'

interface Product {
  id: string
  name: string
  category: string
  provider: string
  status: string
}

export default async function ProductsPage() {
  const supabase = await createClient()

  const { data: products, error } = await supabase
    .from('products')
    .select('*')
    .eq('status', 'active')
    .order('display_order')

  if (error) {
    console.error('Error fetching products:', error)
    return <div>Error loading products</div>
  }

  return (
    <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
      {products?.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Query with Relations

Supabase supports nested selects to fetch related data in a single query. This is more efficient than making multiple round trips to the database.

// Fetch user with wallet
const { data: user } = await supabase
  .from("users")
  .select(
    `
    id,
    email,
    full_name,
    wallets (
      id,
      balance,
      currency
    )
  `
  )
  .eq("id", userId)
  .single();

// Result structure:
// {
//   id: 'user-uuid',
//   email: 'user@example.com',
//   full_name: 'John Doe',
//   wallets: [{ id: 'wallet-uuid', balance: 5000, currency: 'NGN' }]
// }

Fetch Single Record

Use the .single() modifier when you expect exactly one result. This returns an object instead of an array and throws an error if multiple rows match.

// Get single product by slug
const { data: product, error } = await supabase
  .from("products")
  .select("*")
  .eq("slug", "mtn-airtime")
  .single(); // Returns object instead of array

if (!product) {
  notFound(); // Next.js not found handler
}

Pagination

For large datasets, implement pagination using range queries. The count option with head: true efficiently retrieves the total without fetching all data.

// app/(dashboard)/transactions/page.tsx
interface TransactionsPageProps {
  searchParams: Promise<{ page?: string; limit?: string }>
}

export default async function TransactionsPage({
  searchParams
}: TransactionsPageProps) {
  const params = await searchParams
  const page = Number(params.page) || 1
  const limit = Number(params.limit) || 10
  const offset = (page - 1) * limit

  const supabase = await createClient()

  // Get total count
  const { count } = await supabase
    .from('transactions')
    .select('*', { count: 'exact', head: true })

  // Get paginated data
  const { data: transactions, error } = await supabase
    .from('transactions')
    .select(`
      *,
      product:products(name, provider)
    `)
    .order('created_at', { ascending: false })
    .range(offset, offset + limit - 1)

  const totalPages = Math.ceil((count || 0) / limit)

  return (
    <div>
      <TransactionList transactions={transactions} />
      <Pagination
        currentPage={page}
        totalPages={totalPages}
      />
    </div>
  )
}

3. Data Mutations in Server Actions

Server Actions provide a secure way to perform database mutations. They run on the server and can be called directly from Client Components.

Create Record

This server action creates a new product and revalidates the cache to reflect the changes. The revalidatePath function triggers a re-fetch of the specified route.

// app/actions/products.ts
"use server";

import { createClient } from "@/lib/supabase/server";
import { revalidatePath } from "next/cache";

export async function createProduct(formData: FormData) {
  const supabase = await createClient();

  const { data, error } = await supabase
    .from("products")
    .insert({
      name: formData.get("name") as string,
      slug: formData.get("slug") as string,
      category: formData.get("category") as string,
      provider: formData.get("provider") as string,
      min_amount: Number(formData.get("min_amount")),
      max_amount: Number(formData.get("max_amount")),
    })
    .select()
    .single();

  if (error) {
    return { error: error.message };
  }

  revalidatePath("/admin/products");
  return { data };
}

Update Record

This example shows how to update a wallet balance with validation. Always verify the user has permission and sufficient balance before processing financial operations.

// app/actions/wallet.ts
"use server";

import { createClient } from "@/lib/supabase/server";
import { revalidatePath } from "next/cache";

export async function updateWalletBalance(
  walletId: string,
  amount: number,
  type: "credit" | "debit"
) {
  const supabase = await createClient();

  // Get current balance
  const { data: wallet, error: fetchError } = await supabase
    .from("wallets")
    .select("balance")
    .eq("id", walletId)
    .single();

  if (fetchError || !wallet) {
    return { error: "Wallet not found" };
  }

  // Calculate new balance
  const newBalance =
    type === "credit" ? wallet.balance + amount : wallet.balance - amount;

  if (newBalance < 0) {
    return { error: "Insufficient balance" };
  }

  // Update balance
  const { data, error } = await supabase
    .from("wallets")
    .update({ balance: newBalance })
    .eq("id", walletId)
    .select()
    .single();

  if (error) {
    return { error: error.message };
  }

  revalidatePath("/dashboard");
  return { data };
}

Delete Record

Delete operations should always include proper authorization checks. This action deletes a beneficiary and revalidates the beneficiaries page.

"use server";

import { createClient } from "@/lib/supabase/server";

export async function deleteBeneficiary(beneficiaryId: string) {
  const supabase = await createClient();

  const { error } = await supabase
    .from("beneficiaries")
    .delete()
    .eq("id", beneficiaryId);

  if (error) {
    return { error: error.message };
  }

  revalidatePath("/dashboard/beneficiaries");
  return { success: true };
}

4. Client Component Data Fetching

Client Components use the browser client for fetching data after the initial page load. This is useful for interactive features and real-time updates.

Using useEffect

This pattern fetches data when the component mounts. It manages loading and error states to provide appropriate feedback to users.

// components/WalletBalance.tsx
'use client'

import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'

interface Wallet {
  id: string
  balance: number
  currency: string
}

export function WalletBalance({ userId }: { userId: string }) {
  const [wallet, setWallet] = useState<Wallet | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function fetchWallet() {
      const supabase = createClient()

      const { data, error } = await supabase
        .from('wallets')
        .select('id, balance, currency')
        .eq('user_id', userId)
        .single()

      if (error) {
        setError(error.message)
      } else {
        setWallet(data)
      }
      setLoading(false)
    }

    fetchWallet()
  }, [userId])

  if (loading) return <div className="animate-pulse">Loading...</div>
  if (error) return <div className="text-red-500">{error}</div>
  if (!wallet) return <div>No wallet found</div>

  return (
    <div className="bg-primary text-white p-6 rounded-xl">
      <p className="text-sm opacity-80">Balance</p>
      <p className="text-3xl font-bold">
        {wallet.currency} {wallet.balance.toLocaleString()}
      </p>
    </div>
  )
}

Custom Hook Pattern

Extracting data fetching logic into a custom hook promotes code reuse and keeps components clean. The refetch function allows manual data refresh.

// hooks/useWallet.ts
"use client";

import { useEffect, useState, useCallback } from "react";
import { createClient } from "@/lib/supabase/client";

interface Wallet {
  id: string;
  balance: number;
  currency: string;
}

export function useWallet(userId: string) {
  const [wallet, setWallet] = useState<Wallet | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  const fetchWallet = useCallback(async () => {
    setLoading(true);
    const supabase = createClient();

    const { data, error } = await supabase
      .from("wallets")
      .select("id, balance, currency")
      .eq("user_id", userId)
      .single();

    if (error) {
      setError(error.message);
      setWallet(null);
    } else {
      setWallet(data);
      setError(null);
    }
    setLoading(false);
  }, [userId]);

  useEffect(() => {
    fetchWallet();
  }, [fetchWallet]);

  return { wallet, loading, error, refetch: fetchWallet };
}

5. Real-time Subscriptions

Supabase provides real-time subscriptions that push database changes to connected clients instantly. This is perfect for live updates like transaction notifications.

Subscribe to Changes

This component subscribes to transaction changes and updates the UI automatically when new transactions are created or existing ones are modified.

// components/TransactionFeed.tsx
'use client'

import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import type { RealtimeChannel } from '@supabase/supabase-js'

interface Transaction {
  id: string
  amount: number
  type: string
  status: string
  created_at: string
}

export function TransactionFeed({ walletId }: { walletId: string }) {
  const [transactions, setTransactions] = useState<Transaction[]>([])

  useEffect(() => {
    const supabase = createClient()
    let channel: RealtimeChannel

    // Initial fetch
    async function fetchTransactions() {
      const { data } = await supabase
        .from('transactions')
        .select('*')
        .eq('wallet_id', walletId)
        .order('created_at', { ascending: false })
        .limit(10)

      if (data) setTransactions(data)
    }

    fetchTransactions()

    // Subscribe to new transactions
    channel = supabase
      .channel(`transactions:${walletId}`)
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'transactions',
          filter: `wallet_id=eq.${walletId}`,
        },
        (payload) => {
          console.log('New transaction:', payload.new)
          setTransactions((prev) => [payload.new as Transaction, ...prev])
        }
      )
      .on(
        'postgres_changes',
        {
          event: 'UPDATE',
          schema: 'public',
          table: 'transactions',
          filter: `wallet_id=eq.${walletId}`,
        },
        (payload) => {
          console.log('Updated transaction:', payload.new)
          setTransactions((prev) =>
            prev.map((t) =>
              t.id === (payload.new as Transaction).id
                ? (payload.new as Transaction)
                : t
            )
          )
        }
      )
      .subscribe()

    // Cleanup on unmount
    return () => {
      supabase.removeChannel(channel)
    }
  }, [walletId])

  return (
    <div className="space-y-2">
      {transactions.map((tx) => (
        <div key={tx.id} className="p-4 bg-white rounded-lg shadow">
          <div className="flex justify-between">
            <span className={tx.type === 'credit' ? 'text-green-600' : 'text-red-600'}>
              {tx.type === 'credit' ? '+' : '-'}{tx.amount.toLocaleString()}
            </span>
            <span className="text-gray-500 text-sm">
              {new Date(tx.created_at).toLocaleTimeString()}
            </span>
          </div>
        </div>
      ))}
    </div>
  )
}

Real-time Hook

Encapsulate real-time subscription logic in a reusable hook. This hook handles all event types (INSERT, UPDATE, DELETE) and cleans up subscriptions on unmount.

// hooks/useRealtimeTransactions.ts
"use client";

import { useEffect, useState } from "react";
import { createClient } from "@/lib/supabase/client";

export function useRealtimeTransactions(walletId: string) {
  const [transactions, setTransactions] = useState<any[]>([]);

  useEffect(() => {
    const supabase = createClient();

    // Subscribe to changes
    const channel = supabase
      .channel("transactions-realtime")
      .on(
        "postgres_changes",
        {
          event: "*", // Listen to all events
          schema: "public",
          table: "transactions",
          filter: `wallet_id=eq.${walletId}`,
        },
        (payload) => {
          if (payload.eventType === "INSERT") {
            setTransactions((prev) => [payload.new, ...prev]);
          } else if (payload.eventType === "UPDATE") {
            setTransactions((prev) =>
              prev.map((t) => (t.id === payload.new.id ? payload.new : t))
            );
          } else if (payload.eventType === "DELETE") {
            setTransactions((prev) =>
              prev.filter((t) => t.id !== payload.old.id)
            );
          }
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [walletId]);

  return transactions;
}

6. Advanced Query Patterns

Supabase's query builder supports complex filtering, aggregation, and upsert operations. These patterns handle common data access scenarios.

Filtering

Build complex queries using chainable filter methods. The or() method accepts a comma-separated string of conditions for disjunctive queries.

const supabase = await createClient();

// Multiple conditions
const { data } = await supabase
  .from("transactions")
  .select("*")
  .eq("wallet_id", walletId)
  .eq("status", "completed")
  .gte("amount", 1000)
  .lte("amount", 10000)
  .order("created_at", { ascending: false });

// OR conditions
const { data: products } = await supabase
  .from("products")
  .select("*")
  .or("category.eq.airtime,category.eq.data");

// IN clause
const { data: selectedProducts } = await supabase
  .from("products")
  .select("*")
  .in("provider", ["MTN", "Airtel", "Glo"]);

// Text search
const { data: searchResults } = await supabase
  .from("products")
  .select("*")
  .ilike("name", `%${searchTerm}%`);

// Date range
const { data: monthlyTx } = await supabase
  .from("transactions")
  .select("*")
  .gte("created_at", startOfMonth)
  .lte("created_at", endOfMonth);

Aggregations with RPC

For complex aggregations, create PostgreSQL functions and call them via RPC. This keeps business logic in the database and reduces data transfer.

-- Create a function in Supabase SQL Editor
CREATE OR REPLACE FUNCTION get_transaction_summary(wallet_uuid UUID)
RETURNS TABLE (
  total_credit DECIMAL,
  total_debit DECIMAL,
  transaction_count BIGINT
) AS $$
BEGIN
  RETURN QUERY
  SELECT
    COALESCE(SUM(CASE WHEN type = 'credit' THEN amount ELSE 0 END), 0) as total_credit,
    COALESCE(SUM(CASE WHEN type = 'debit' THEN amount ELSE 0 END), 0) as total_debit,
    COUNT(*) as transaction_count
  FROM transactions
  WHERE wallet_id = wallet_uuid
    AND status = 'completed';
END;
$$ LANGUAGE plpgsql;

Call the database function from your Next.js application using the rpc method.

// Call the function from Next.js
const { data, error } = await supabase.rpc("get_transaction_summary", {
  wallet_uuid: walletId,
});

Upsert (Insert or Update)

Upsert creates a record if it does not exist, or updates it if it does. Specify the conflict column(s) to determine uniqueness.

// Create or update beneficiary
const { data, error } = await supabase
  .from("beneficiaries")
  .upsert(
    {
      user_id: userId,
      account_number: phoneNumber,
      category: "airtime",
      name: beneficiaryName,
      provider: "MTN",
    },
    {
      onConflict: "user_id,account_number,category", // Unique constraint
    }
  )
  .select()
  .single();

7. Error Handling Patterns

Robust error handling improves user experience and makes debugging easier. Create a centralized error handling system for Supabase errors.

Comprehensive Error Handling

This error handling utility maps Supabase error codes to user-friendly messages and logs details for debugging.

// lib/supabase/errors.ts
export class SupabaseError extends Error {
  code: string;
  details: string | null;
  hint: string | null;

  constructor(error: any) {
    super(error.message);
    this.name = "SupabaseError";
    this.code = error.code;
    this.details = error.details;
    this.hint = error.hint;
  }
}

export function handleSupabaseError(error: any): never {
  // Log for debugging
  console.error("Supabase error:", {
    message: error.message,
    code: error.code,
    details: error.details,
  });

  // Map to user-friendly messages
  const errorMessages: Record<string, string> = {
    "23505": "This record already exists",
    "23503": "Referenced record not found",
    "23514": "Data validation failed",
    "42501": "Permission denied",
    PGRST116: "Record not found",
  };

  const message = errorMessages[error.code] || error.message;
  throw new SupabaseError({ ...error, message });
}

Using in Server Actions

Apply the error handler in your server actions to provide consistent error responses.

"use server";

import { handleSupabaseError } from "@/lib/supabase/errors";

export async function createTransaction(data: TransactionInput) {
  const supabase = await createClient();

  const { data: result, error } = await supabase
    .from("transactions")
    .insert(data)
    .select()
    .single();

  if (error) {
    handleSupabaseError(error);
  }

  return result;
}

8. Type-Safe Queries with Generated Types

Generated types from the Supabase CLI provide compile-time type checking for all database operations, catching errors before they reach production.

Setup Type Generation

Run this command whenever your database schema changes to regenerate types.

# Generate types from your Supabase project
supabase gen types typescript --project-id your-project-id > lib/supabase/database.types.ts

Using Types

The generated types include Row, Insert, and Update variations for each table, covering all CRUD operation needs.

// lib/supabase/database.types.ts (generated)
export type Database = {
  public: {
    Tables: {
      products: {
        Row: {
          id: string;
          name: string;
          category: string;
          // ... all columns
        };
        Insert: {
          id?: string;
          name: string;
          category: string;
          // ... required for insert
        };
        Update: {
          id?: string;
          name?: string;
          category?: string;
          // ... all optional for update
        };
      };
      // ... other tables
    };
  };
};

Pass the Database type to your client to enable full IntelliSense support and type checking.

// Type-safe client
import { createBrowserClient } from "@supabase/ssr";
import { Database } from "./database.types";

export function createClient() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

// Now queries are fully typed
const supabase = createClient();
const { data } = await supabase
  .from("products") // Autocomplete table names
  .select("id, name, category") // Type-checked columns
  .eq("status", "active"); // Type-checked values

9. Combining Server and Client Patterns

The best applications combine server-side initial data fetching with client-side real-time updates. This pattern provides fast initial loads with live updates.

Server-Side Initial Load, Client-Side Updates

The server component fetches initial data for fast page loads, then passes it to a client component that sets up real-time subscriptions for live updates.

// app/(dashboard)/wallet/page.tsx (Server Component)
import { createClient } from '@/lib/supabase/server'
import { WalletClient } from './wallet-client'

export default async function WalletPage() {
  const supabase = await createClient()

  // Initial data fetch on server
  const { data: wallet } = await supabase
    .from('wallets')
    .select('*')
    .single()

  const { data: transactions } = await supabase
    .from('transactions')
    .select('*')
    .order('created_at', { ascending: false })
    .limit(10)

  // Pass to client component for real-time updates
  return (
    <WalletClient
      initialWallet={wallet}
      initialTransactions={transactions || []}
    />
  )
}

The client component receives initial data as props and subscribes to real-time changes for continuous updates.

// app/(dashboard)/wallet/wallet-client.tsx
'use client'

import { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'

interface WalletClientProps {
  initialWallet: Wallet
  initialTransactions: Transaction[]
}

export function WalletClient({
  initialWallet,
  initialTransactions
}: WalletClientProps) {
  const [wallet, setWallet] = useState(initialWallet)
  const [transactions, setTransactions] = useState(initialTransactions)

  // Set up real-time subscription for updates
  useEffect(() => {
    const supabase = createClient()

    const channel = supabase
      .channel('wallet-updates')
      .on('postgres_changes', {
        event: '*',
        schema: 'public',
        table: 'wallets',
        filter: `id=eq.${wallet.id}`,
      }, (payload) => {
        setWallet(payload.new as Wallet)
      })
      .on('postgres_changes', {
        event: 'INSERT',
        schema: 'public',
        table: 'transactions',
        filter: `wallet_id=eq.${wallet.id}`,
      }, (payload) => {
        setTransactions(prev => [payload.new as Transaction, ...prev])
      })
      .subscribe()

    return () => {
      supabase.removeChannel(channel)
    }
  }, [wallet.id])

  return (
    <div>
      <WalletBalance balance={wallet.balance} />
      <TransactionList transactions={transactions} />
    </div>
  )
}

10. Best Practices Summary

Following these best practices ensures secure, efficient, and maintainable Supabase integrations.

Do's

These patterns represent recommended approaches that improve security and performance.

// 1. Always handle errors
const { data, error } = await supabase.from("table").select("*");
if (error) {
  // Handle error appropriately
}

// 2. Use .single() for unique queries
const { data: user } = await supabase
  .from("users")
  .select("*")
  .eq("id", userId)
  .single();

// 3. Select only needed columns
const { data } = await supabase
  .from("transactions")
  .select("id, amount, status"); // Not select('*')

// 4. Clean up subscriptions
useEffect(() => {
  const channel = supabase.channel("...");
  // ...
  return () => supabase.removeChannel(channel);
}, []);

// 5. Use server client in Server Components
const supabase = await createClient(); // Server client

Don'ts

Avoid these common mistakes that can lead to security vulnerabilities or application errors.

// 1. Don't expose service role key to client
// WRONG: Using admin client in client component

// 2. Don't forget to await cookie-based client
// WRONG: const supabase = createClient() in server component
// RIGHT: const supabase = await createClient()

// 3. Don't make unnecessary queries
// WRONG: Fetching full user object when you only need name

// 4. Don't ignore TypeScript types
// Use generated types for type safety

Additional Resources

Next Lesson: Row Level Security