Server Actions Goldmine: The API-Free Pattern for Modern Next.js Apps

The Old Way: The Hassle of API Routes for Mutations

Anatomy of a Traditional Form Submission

const ContactForm = () => {
  const [email, setEmail] = useState('');
  const [message, setMessage] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);
    
    try {
      const response = await fetch('/api/contact', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, message })
      });
      
      if (!response.ok) throw new Error('Failed to submit');
      // Handle success
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };
  
  // Return your JSX form here
};

The Boilerplate Problem

What Are Server Actions? A Paradigm Shift

The 'use server' Directive

async function submitContact(formData) {
  'use server';
  
  const email = formData.get('email');
  const message = formData.get('message');
  
  // Direct database access - this runs on the server!
  await db.contacts.create({
    email,
    message,
    createdAt: new Date()
  });
  
  // Revalidate the page to show new data
  revalidatePath('/contacts');
}

How They Work Under the Hood

The Benefits of the API-Free Pattern

Drastically Reduced Client-Side JavaScript

Enhanced Security by Default

async function processPayment(formData) {
  'use server';
  
  // This API key is never exposed to the client
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
  
  const amount = formData.get('amount');
  const token = formData.get('token');
  
  // Direct payment processing - completely secure
  const charge = await stripe.charges.create({
    amount: amount * 100,
    currency: 'usd',
    source: token
  });
  
  return { success: true, chargeId: charge.id };
}

Simplified Code and Improved Developer Experience

// Client Component (50+ lines)
const Newsletter = () => {
  const [email, setEmail] = useState('');
  const [status, setStatus] = useState('idle');
  
  const subscribe = async (e) => {
    e.preventDefault();
    setStatus('loading');
    
    try {
      const res = await fetch('/api/newsletter', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email })
      });
      
      if (!res.ok) throw new Error('Failed');
      setStatus('success');
    } catch (error) {
      setStatus('error');
    }
  };
  
  // Plus all the JSX for different states
};

// API Route (another 20+ lines)
export default async function handler(req, res) {
  // Validation, database logic, error handling
}

// Just one file, ~20 lines total
async function subscribe(formData) {
  'use server';
  
  const email = formData.get('email');
  await db.subscribers.create({ email });
  revalidatePath('/');
}

const Newsletter = () => (
  <form action={subscribe}>
    <input name="email" type="email" required />
    <button type="submit">Subscribe</button>
  </form>
);

Progressive Enhancement for Free

Implementing Server Actions: Practical Examples

Basic Form Submission

import { redirect } from 'next/navigation';

async function createContact(formData) {
  'use server';
  
  // Extract form data
  const name = formData.get('name');
  const email = formData.get('email');
  const message = formData.get('message');
  
  // Validate on the server
  if (!email || !email.includes('@')) {
    throw new Error('Invalid email address');
  }
  
  // Save to database
  await db.contacts.create({
    name,
    email,
    message,
    createdAt: new Date()
  });
  
  // Redirect after success
  redirect('/thank-you');
}

export default function ContactPage() {
  return (
    <form action={createContact}>
      <input name="name" placeholder="Your name" required />
      <input name="email" type="email" placeholder="Email" required />
      <textarea name="message" placeholder="Message" required />
      <button type="submit">Send Message</button>
    </form>
  );
}

Revalidating Data with revalidatePath and revalidateTag

import { revalidatePath, revalidateTag } from 'next/cache';

async function createPost(formData) {
  'use server';
  
  const title = formData.get('title');
  const content = formData.get('content');
  
  // Create the post
  const post = await db.posts.create({
    title,
    content,
    slug: generateSlug(title)
  });
  
  // Revalidate specific paths
  revalidatePath('/blog'); // Refreshes the blog listing
  revalidatePath(`/blog/${post.slug}`); // Refreshes the new post page
  
  // Or revalidate by cache tags
  revalidateTag('posts'); // Refreshes anything tagged with 'posts'
}

Handling Loading and Error States

'use client';

import { useFormStatus, useFormState } from 'react-dom';
import { createUser } from './actions';

function SubmitButton() {
  const { pending } = useFormStatus();
  
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Creating...' : 'Create Account'}
    </button>
  );
}

export default function SignupForm() {
  const [state, formAction] = useFormState(createUser, {
    errors: {}
  });
  
  return (
    <form action={formAction}>
      <input name="email" type="email" />
      {state.errors?.email && (
        <p className="error">{state.errors.email}</p>
      )}
      
      <input name="password" type="password" />
      {state.errors?.password && (
        <p className="error">{state.errors.password}</p>
      )}
      
      <SubmitButton />
    </form>
  );
}

Server Actions in Client Components

The 'Action in a Separate File' Pattern

// app/actions/user-actions.js
'use server';

export async function updateProfile(formData) {
  const name = formData.get('name');
  const bio = formData.get('bio');
  
  await db.users.update({
    where: { id: getCurrentUserId() },
    data: { name, bio }
  });
  
  revalidatePath('/profile');
}

// app/components/ProfileForm.jsx
'use client';

import { updateProfile } from '../actions/user-actions';

export default function ProfileForm({ user }) {
  return (
    <form action={updateProfile}>
      <input name="name" defaultValue={user.name} />
      <textarea name="bio" defaultValue={user.bio} />
      <button type="submit">Update Profile</button>
    </form>
  );
}

Invoking Actions with startTransition

'use client';

import { useTransition } from 'react';
import { deleteItem } from '../actions';

export default function ItemList({ items }) {
  const [isPending, startTransition] = useTransition();
  
  const handleDelete = (itemId) => {
    startTransition(async () => {
      await deleteItem(itemId);
    });
  };
  
  return (
    <ul style={{ opacity: isPending ? 0.5 : 1 }}>
      {items.map(item => (
        <li key={item.id}>
          {item.name}
          <button onClick={() => handleDelete(item.id)}>
            Delete
          </button>
        </li>
      ))}
    </ul>
  );
}

When Not to Use Server Actions

Public APIs and Webhooks

// app/api/webhooks/stripe/route.js
export async function POST(request) {
  const signature = request.headers.get('stripe-signature');
  const body = await request.text();
  
  // Verify webhook signature
  const event = stripe.webhooks.constructEvent(
    body,
    signature,
    process.env.STRIPE_WEBHOOK_SECRET
  );
  
  // Process the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      await handlePaymentSuccess(event.data.object);
      break;
    // Handle other event types
  }
  
  return Response.json({ received: true });
}

GET Requests and Data Fetching

// Fetch directly in the component
async function ProductList() {
  const products = await db.products.findMany();
  
  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

// Use a Route Handler for client-side data needs
// app/api/products/route.js
export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const category = searchParams.get('category');
  
  const products = await db.products.findMany({
    where: category ? { category } : undefined
  });
  
  return Response.json(products);
}

Conclusion

References