When should I use Server Actions instead of API Routes in Next.js 15?

Use Server Actions for form submissions, mutations triggered from React components, and data flows that stay inside your Next.js app. They eliminate boilerplate and integrate with useFormState and useFormStatus for progressive enhancement.

Can Server Actions fully replace API Routes?

No. API Routes are still the right choice when you need a stable HTTP endpoint — external clients, webhooks, mobile apps, third-party integrations, or anything requiring a fixed URL contract. Server Actions assume the caller is your own Next.js frontend.

Are Server Actions faster than API Routes?

Performance is effectively identical for most workloads since both run on the same server. The real wins are reduced client JavaScript and simpler code paths, not raw latency.

Do Server Actions work for mobile apps or third-party integrations?

No. Server Actions rely on Next.js-specific RPC and are not meant to be called from arbitrary clients. Expose an API Route whenever a non-browser client needs to hit your backend.

Next.js Server Actions vs API Routes: When to Use Each#

Next.js 15 gives you two ways to handle server-side logic: Server Actions and API Routes. Both work, but they're designed for different use cases. Choosing the wrong one leads to unnecessary complexity or missing features.

This guide teaches you when to use each approach.

Understanding the Differences#

Server Actions#

Server Actions are async functions that run on the server and are called directly from components.

typescript

// app/actions.ts
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  const { data, error } = await supabase
    .from('posts')
    .insert({ title, content, user_id: userId })

  if (error) throw error
  return data
}

typescriptrevert

// app/posts/new/page.tsx
'use client'

import { createPost } from '@/app/actions'

export default function NewPostPage() {
  async function handleSubmit(formData: FormData) {
    const post = await createPost(formData)
    console.log('Post created:', post)
  }

  return (
    <form action={handleSubmit}>
      <input name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" required />
      <button type="submit">Create Post</button>
    </form>
  )
}

API Routes#

API Routes are HTTP endpoints that handle requests and responses.

typescript

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const { title, content } = await request.json()

  const { data, error } = await supabase
    .from('posts')
    .insert({ title, content, user_id: userId })

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 400 })
  }

  return NextResponse.json(data)
}

typescript

// app/posts/new/page.tsx
'use client'

export default function NewPostPage() {
  async function handleSubmit(formData: FormData) {
    const response = await fetch('/api/posts', {
      method: 'POST',
      body: JSON.stringify({
        title: formData.get('title'),
        content: formData.get('content')
      })
    })

    const post = await response.json()
    console.log('Post created:', post)
  }

  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      handleSubmit(new FormData(e.currentTarget))
    }}>
      <input name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" required />
      <button type="submit">Create Post</button>
    </form>
  )
}

Key Differences#

| Feature | Server Actions | API Routes | |---------|---|---| | Call Method | Direct function call | HTTP request | | CSRF Protection | Built-in | Manual | | Type Safety | Excellent | Manual | | Caching | Next.js cache functions | Manual | | External Calls | Not possible | Possible | | Middleware | No | Yes | | Complexity | Simple | More verbose | | Flexibility | Limited | High |

When to Use Server Actions#

Use Server Actions for:

Form Submissions#

typescript

// ✅ Perfect for form submissions
'use server'

export async function updateProfile(formData: FormData) {
  const name = formData.get('name') as string
  const email = formData.get('email') as string

  const { error } = await supabase
    .from('profiles')
    .update({ name, email })
    .eq('id', userId)

  if (error) throw error
  revalidatePath('/profile')
}

Simple Mutations#

typescript

// ✅ Good for simple mutations
'use server'

export async function deletePost(postId: string) {
  const { error } = await supabase
    .from('posts')
    .delete()
    .eq('id', postId)

  if (error) throw error
  revalidatePath('/posts')
}

Keeping Secrets Secure#

typescript

// ✅ API keys stay on server
'use server'

export async function sendEmail(email: string) {
  // STRIPE_SECRET_KEY never exposed to client
  const response = await fetch('https://api.stripe.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}`
    }
  })

  return response.json()
}

Database Operations#

typescript

// ✅ Direct database access
'use server'

export async function getPostsWithComments() {
  const { data } = await supabase
    .from('posts')
    .select(`
      *,
      comments(*)
    `)

  return data
}

When to Use API Routes#

Use API Routes for:

Webhooks#

typescript

// ✅ External services need HTTP endpoints
export async function POST(request: NextRequest) {
  const event = await request.json()

  if (event.type === 'charge.succeeded') {
    // Handle Stripe webhook
    await supabase
      .from('payments')
      .insert({ stripe_id: event.data.id, status: 'completed' })
  }

  return NextResponse.json({ received: true })
}

External Integrations#

typescript

// ✅ Third-party services call your API
export async function POST(request: NextRequest) {
  const { apiKey } = request.headers

  // Verify API key
  if (apiKey !== process.env.EXTERNAL_API_KEY) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const data = await request.json()
  // Process data
  return NextResponse.json({ success: true })
}

Complex Business Logic#

typescript

// ✅ Complex logic benefits from middleware and error handling
export async function POST(request: NextRequest) {
  try {
    const { userId, amount } = await request.json()

    // Validate
    if (amount < 0) {
      return NextResponse.json({ error: 'Invalid amount' }, { status: 400 })
    }

    // Check user balance
    const { data: user } = await supabase
      .from('users')
      .select('balance')
      .eq('id', userId)
      .single()

    if (user.balance < amount) {
      return NextResponse.json({ error: 'Insufficient balance' }, { status: 400 })
    }

    // Process transaction
    const { data: transaction } = await supabase
      .from('transactions')
      .insert({ user_id: userId, amount })

    return NextResponse.json(transaction)
  } catch (error) {
    return NextResponse.json({ error: 'Server error' }, { status: 500 })
  }
}

Rate Limiting#

typescript

// ✅ Middleware for rate limiting
import { Ratelimit } from '@upstash/ratelimit'

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '1 h')
})

export async function POST(request: NextRequest) {
  const ip = request.headers.get('x-forwarded-for') || 'unknown'
  const { success } = await ratelimit.limit(ip)

  if (!success) {
    return NextResponse.json({ error: 'Rate limited' }, { status: 429 })
  }

  // Handle request
}

RESTful APIs#

typescript

// ✅ Full REST API with multiple methods
export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')

  const { data } = await supabase
    .from('posts')
    .select('*')
    .eq('id', id)
    .single()

  return NextResponse.json(data)
}

export async function POST(request: NextRequest) {
  const body = await request.json()
  const { data } = await supabase.from('posts').insert(body)
  return NextResponse.json(data)
}

export async function PUT(request: NextRequest) {
  const { id, ...updates } = await request.json()
  const { data } = await supabase
    .from('posts')
    .update(updates)
    .eq('id', id)
  return NextResponse.json(data)
}

export async function DELETE(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')
  const { data } = await supabase.from('posts').delete().eq('id', id)
  return NextResponse.json(data)
}

Real-World Decision Tree#

Is it a form submission or simple mutation?
├─ YES → Use Server Actions
└─ NO → Continue

Does an external service need to call your app?
├─ YES → Use API Routes
└─ NO → Continue

Do you need middleware or rate limiting?
├─ YES → Use API Routes
└─ NO → Continue

Do you need fine-grained HTTP control?
├─ YES → Use API Routes
└─ NO → Use Server Actions

Performance Comparison#

Server Actions:

Lower latency (no HTTP overhead)
Direct function call
Automatic serialization
Built-in CSRF protection

API Routes:

Slightly higher latency (HTTP overhead)
More flexible
Manual serialization
Manual CSRF protection

For most applications, the performance difference is negligible (less than 10ms). Choose based on functionality, not performance.

Error Handling#

Server Actions#

typescript

'use client'

async function handleSubmit(formData: FormData) {
  try {
    const result = await createPost(formData)
    console.log('Success:', result)
  } catch (error) {
    console.error('Error:', error.message)
  }
}

API Routes#

typescript

'use client'

async function handleSubmit(formData: FormData) {
  try {
    const response = await fetch('/api/posts', {
      method: 'POST',
      body: JSON.stringify(Object.fromEntries(formData))
    })

    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.message)
    }

    const result = await response.json()
    console.log('Success:', result)
  } catch (error) {
    console.error('Error:', error.message)
  }
}

Best Practices#

Server Actions:

✅ Use for form submissions
✅ Keep them simple and focused
✅ Use revalidatePath for cache invalidation
✅ Throw errors for error handling
✅ Use FormData for file uploads

API Routes:

✅ Use for webhooks and external integrations
✅ Implement proper error handling
✅ Add rate limiting for public endpoints
✅ Validate all input
✅ Return appropriate HTTP status codes

Conclusion#

Server Actions and API Routes both have their place. Use Server Actions for simple mutations and form submissions—they're simpler and have better type safety. Use API Routes for webhooks, external integrations, and complex business logic.

The key is understanding the trade-offs. Server Actions are simpler but less flexible. API Routes are more complex but more powerful. Choose the right tool for the job.

Production Notes#

Root cause to verify: measure the route with production rendering mode, real cache headers, and realistic data volume.
Production fix pattern: choose caching boundaries deliberately and verify invalidation after every mutation path.
Verification step: compare p50 and p95 latency before and after the change, not just local dev behavior.

Next.js Server Actions vs API Routes: When to Use Each

Next.js Server Actions vs API Routes: When to Use Each#

Understanding the Differences#

Server Actions#

API Routes#

Key Differences#

When to Use Server Actions#

Form Submissions#

Simple Mutations#

Keeping Secrets Secure#

Database Operations#

When to Use API Routes#

Webhooks#

External Integrations#

Complex Business Logic#

Rate Limiting#

RESTful APIs#

Real-World Decision Tree#

Performance Comparison#

Error Handling#

Server Actions#

API Routes#

Best Practices#

Conclusion#

Production Notes#

Frequently Asked Questions

When should I use Server Actions instead of API Routes in Next.js 15?

Can Server Actions fully replace API Routes?

Are Server Actions faster than API Routes?

Do Server Actions work for mobile apps or third-party integrations?

Written by

Mahdi Br

10 Common Mistakes Building with Next.js and Supabase (And How to Fix Them)

Next.js Turbopack Stuck Compiling: 9 Fixes for Dev and Production Builds

Fix Next.js revalidatePath Not Working in Server Actions

Browse by Topic

Technology

PostgreSQL in Production

automation

Business

Next.js Server Actions vs API Routes: When to Use Each

Next.js Server Actions vs API Routes: When to Use Each#

Understanding the Differences#

Server Actions#

API Routes#

Key Differences#

When to Use Server Actions#

Form Submissions#

Simple Mutations#

Keeping Secrets Secure#

Database Operations#

When to Use API Routes#

Webhooks#

External Integrations#

Complex Business Logic#

Rate Limiting#

RESTful APIs#

Real-World Decision Tree#

Performance Comparison#

Error Handling#

Server Actions#

API Routes#

Best Practices#

Related Articles#

Conclusion#

Production Notes#

Frequently Asked Questions

When should I use Server Actions instead of API Routes in Next.js 15?

Can Server Actions fully replace API Routes?

Are Server Actions faster than API Routes?

Do Server Actions work for mobile apps or third-party integrations?

Written by

Mahdi Br

Continue Reading

10 Common Mistakes Building with Next.js and Supabase (And How to Fix Them)

Next.js Turbopack Stuck Compiling: 9 Fixes for Dev and Production Builds

Fix Next.js revalidatePath Not Working in Server Actions

Browse by Topic

Technology

PostgreSQL in Production

automation

Business