server-actions-patterns

Server Actions & Services Patterns

Next.js "use server" Restrictions

Critical Rule: Only Async Functions in "use server" Files

❌ Never export classes from "use server" files

// This will cause build errors
"use server";
export class MyService { // ❌ BREAKS
  static async method() {}
}

✅ Always use individual exported async functions

// This works correctly
"use server";
export async function myServiceMethod() { // ✅ WORKS
  // implementation
}

Service Layer Pattern

Function Naming Convention

Use descriptive function names that indicate the entity and action:

// Waitlist service functions
addWaitlistEntry()
getWaitlistEntry()
updateWaitlistEntry()
deleteWaitlistEntry()

// User service functions
addUserAccount()
getUserProfile()
updateUserSettings()

Database Null Checks

Always validate database connection in service functions:

export async function serviceFunction() {
  if (!db) {
    throw new Error("Database not initialized");
  }
  // proceed with database operations
}

Server Actions Pattern

Form Handling Actions

Server actions should handle the complete user flow:

export async function handleFormSubmission(formData: FormData) {
  try {
    // 1. Validate input
    // 2. Check business rules (duplicates, etc.)
    // 3. Call service functions
    // 4. Handle side effects (emails, etc.)
    // 5. Return success/error response
    return { success: true };
  } catch (error) {
    return { success: false, error: error.message };
  }
}

Error Handling Pattern

Always provide user-friendly error responses:

} catch (error: unknown) {
  if (error instanceof Error) {
    console.error("Specific error:", error.message);
    return { success: false, error: error.message };
  }
  console.error("Unknown error:", error);
  return { success: false, error: "An unknown error occurred" };
}

Import/Export Patterns

Service Function Imports

Import specific functions, optionally with aliases:

import {
  addWaitlistEntry,
  isEmailOnWaitlist,
  getWaitlistStats as getStats
} from "@/server/services/waitlist-service";