Brain, Mind, and Body in the Healing of Trauma

// What you write:
'use server';
export async function updateProfile(data: ProfileData) {
  // Server logic
}

// What gets generated for the client:
// A reference object that contains:
// - Action ID (encrypted, non-deterministic)
// - Endpoint URL
// - Serialization metadata

3. Action ID Generation

Next.js generates encrypted, non-deterministic IDs for each server action. These IDs:

• Change between builds for security
• Are used to route requests to the correct action
• Prevent unauthorized access to unused actions

The build process creates a manifest mapping action IDs to their implementations:

{
  "actions": {
    "a1b2c3d4e5f6": {
      "file": "./src/server/actions/user-actions.ts",
      "name": "updateProfile",
      "endpoint": "/_next/static/chunks/action-a1b2c3d4e5f6.js"
    }
  }
}

Runtime Loading: Static vs Dynamic Imports

Static Imports (Default Behavior)

When you import a server action statically, Next.js includes the client reference in your initial bundle:

'use client';

import { updateProfile } from '@/server/actions/user-actions';

export function ProfileForm() {
  const handleSubmit = async (data: FormData) => {
    await updateProfile(data); // Action is available immediately
  };
  
  return <form action={handleSubmit}>...</form>;
}

What happens:

1. The client reference is bundled with your component
2. The action ID and endpoint are known at build time
3. No additional network request needed to discover the action
4. Larger initial bundle size

Dynamic Imports (Code Splitting)

You can dynamically import server actions to reduce initial bundle size:

'use client';

import { useState } from 'react';

export function ProfileForm() {
  const [action, setAction] = useState<typeof import('@/server/actions/user-actions') | null>(null);
  
  const loadAction = async () => {
    const { updateProfile } = await import('@/server/actions/user-actions');
    setAction({ updateProfile } as any);
  };
  
  const handleSubmit = async (data: FormData) => {
    if (!action) {
      await loadAction();
    }
    await action!.updateProfile(data);
  };
  
  return <form action={handleSubmit}>...</form>;
}

What happens:

1. The action code is NOT in the initial bundle
2. A separate chunk is created for the action
3. The chunk is loaded on-demand when first needed
4. Smaller initial bundle, but requires a network request

When to Use Each Approach

Use Static Imports When:

• The action is used immediately on page load
• Bundle size is not a concern
• You want the fastest possible first invocation

Use Dynamic Imports When:

• The action is used conditionally or after user interaction
• You're optimizing for initial bundle size
• The action is in a rarely-visited route

HTTP Resolution: How Client Calls Become Server Requests

The magic of Server Actions lies in how Next.js bridges the gap between client-side function calls and server-side HTTP requests.

Server-to-Server: Direct Function Calls

Important distinction: When server actions are called from the server side (from other server actions, server components, or API routes), they execute directly in memory without any HTTP overhead. Next.js detects that both the caller and the action are running on the server, so it bypasses the HTTP layer entirely and calls the function directly.

'use server';

export async function getUserData(userId: string) {
  const db = await getDatabase();
  return await db.users.findById(userId);
}

export async function getUserProfile(userId: string) {
  // This calls getUserData directly in memory - NO HTTP request!
  const userData = await getUserData(userId);
  
  // Process and return
  return { profile: userData };
}

This means:

• No serialization overhead - Objects are passed by reference
• No network latency - Instant function calls
• Full TypeScript type safety - Types flow through directly
• Access to server-only APIs - Can use Node.js APIs, file system, etc.

Only client-to-server calls go through the HTTP layer. Server-to-server calls are pure function invocations, making them extremely efficient for composing complex server-side logic.

The Request Flow

When you call a server action from the client, here's what happens:

// 1. Client calls the action
await updateProfile(formData);

// 2. Next.js intercepts the call
// The client reference is actually a special proxy function

// 3. Serialization happens
// FormData, objects, and primitives are serialized to JSON
const payload = {
  actionId: 'a1b2c3d4e5f6',
  args: [/* serialized arguments */],
  bound: [] // For closure-bound values
};

// 4. HTTP POST request is made
fetch('/_next/static/chunks/action-a1b2c3d4e5f6.js', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Next-Action': 'a1b2c3d4e5f6'
  },
  body: JSON.stringify(payload)
});

// 5. Server receives and routes the request
// Next.js looks up the action by ID and executes it

// 6. Response is serialized and sent back
// The return value is serialized to JSON

// 7. Client receives and deserializes
// The promise resolves with the server's return value

The Endpoint Structure

Next.js creates endpoints at build time following this pattern:

/_next/static/chunks/action-{HASH}.js

These endpoints:

• Are POST-only (GET requests are not supported for security)
• Accept JSON payloads with serialized arguments
• Return JSON responses
• Include CORS headers for same-origin requests

Serialization Rules

Not everything can be serialized. Server Actions support:

✅ Serializable:

• Primitives (string, number, boolean, null)
• Plain objects and arrays
• Date objects (serialized as ISO strings)
• FormData and URLSearchParams
• File and Blob objects
• Typed arrays (Uint8Array, etc.)

❌ Not Serializable:

• Functions
• Class instances (unless they have a custom serializer)
• Symbols
• Circular references
• Browser-only APIs

'use server';

export async function processData(data: {
  name: string;
  timestamp: Date; // ✅ Serialized as ISO string
  callback: () => void; // ❌ Cannot serialize functions
}) {
  // This will fail if callback is passed
}

Error Handling and HTTP Status Codes

Server Actions use standard HTTP status codes:

'use server';

export async function mightFail() {
  try {
    const result = await riskyOperation();
    return { success: true, data: result };
    // Returns 200 OK
  } catch (error) {
    // Throwing an error returns 500 Internal Server Error
    throw new Error('Operation failed');
    
    // You can also return error objects
    return { success: false, error: 'Operation failed' };
    // Still returns 200 OK, but with error in response body
  }
}

Advanced Patterns: Progressive Enhancement

Server Actions work seamlessly with HTML forms for progressive enhancement:

'use server';

export async function submitForm(formData: FormData) {
  const email = formData.get('email') as string;
  // Process form data
  return { success: true };
}

// Works with or without JavaScript!
<form action={submitForm}>
  <input name="email" type="email" required />
  <button type="submit">Submit</button>
</form>

// With JavaScript, you get:
// - No page reload
// - Optimistic updates
// - Better error handling

Security Considerations

Server Actions are publicly accessible endpoints. Always:

1. Validate on the server - Never trust client input
2. Authenticate requests - Check user sessions
3. Authorize actions - Verify permissions
4. Sanitize inputs - Prevent injection attacks

'use server';

import { auth } from '@/lib/auth';
import { z } from 'zod';

const updateSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100)
});

export async function updateProfile(data: unknown) {
  // 1. Authenticate
  const session = await auth();
  if (!session) {
    throw new Error('Unauthorized');
  }
  
  // 2. Validate
  const validated = updateSchema.parse(data);
  
  // 3. Authorize
  if (session.userId !== validated.userId) {
    throw new Error('Forbidden');
  }
  
  // 4. Process (inputs are now safe)
  return await db.users.update(validated);
}

Performance Optimizations

1. Batch Multiple Actions

Instead of multiple round trips:

// ❌ Bad: Multiple requests
await updateName(data.name);
await updateEmail(data.email);
await updateAvatar(data.avatar);

// ✅ Good: Single request
await updateProfile(data); // Handles all updates

2. Use revalidatePath and revalidateTag

Keep your cache fresh:

'use server';

import { revalidatePath } from 'next/cache';

export async function updatePost(id: string, data: PostData) {
  await db.posts.update(id, data);
  
  // Invalidate cached pages
  revalidatePath('/posts');
  revalidatePath(`/posts/${id}`);
  
  return { success: true };
}

3. Optimistic Updates

Update UI immediately, rollback on error:

'use client';

import { useOptimistic } from 'react';
import { updatePost } from './actions';

export function PostEditor({ post }) {
  const [optimisticPost, addOptimisticPost] = useOptimistic(
    post,
    (state, newPost) => ({ ...state, ...newPost })
  );
  
  const handleUpdate = async (data: PostData) => {
    addOptimisticPost(data); // Update UI immediately
    
    try {
      await updatePost(post.id, data);
    } catch (error) {
      // UI will revert automatically
      throw error;
    }
  };
  
  return <form action={handleUpdate}>...</form>;
}

Debugging Server Actions

1. Check Network Tab

Server Actions appear as POST requests in your browser's network tab:

• Look for requests to /_next/static/chunks/action-*.js
• Check request/response payloads
• Verify status codes

2. Server Logs

Add logging to your actions:

'use server';

export async function debugAction(data: unknown) {
  console.log('Action called with:', data);
  console.log('Request headers:', headers());
  console.log('Cookies:', cookies());
  
  // Your logic here
}

3. Error Boundaries

Wrap server action calls in error boundaries:

'use client';

import { ErrorBoundary } from 'react-error-boundary';

function ActionButton() {
  return (
    <ErrorBoundary fallback={<ErrorFallback />}>
      <form action={riskyAction}>
        <button>Submit</button>
      </form>
    </ErrorBoundary>
  );
}

Conclusion

Next.js Server Actions provide a powerful abstraction over HTTP requests, but understanding their internals helps you:

• Write more efficient code
• Debug issues faster
• Optimize bundle sizes
• Implement better error handling
• Build more secure applications

The key takeaways:

1. Build time: Actions are identified, bundled, and assigned encrypted IDs
2. Runtime: Static imports bundle immediately, dynamic imports load on-demand
3. HTTP: Client calls are serialized, sent as POST requests, and responses are deserialized
4. Security: Always validate, authenticate, and authorize on the server

Further Learning

Here are some excellent video resources to deepen your understanding:

Next.js Server Actions Explained

This comprehensive tutorial covers the fundamentals of Server Actions, including form handling and progressive enhancement.

Server Actions with Authentication

Learn how to implement authentication patterns with Server Actions and React Server Components.

Advanced Server Actions Patterns

Explore advanced patterns, error handling, and performance optimizations for Server Actions.

Server Actions vs API Routes

Understand when to use Server Actions versus traditional API routes in your Next.js applications.

Want to dive deeper? Check out the Next.js Server Actions documentation for the latest features and best practices.

Book a Discovery Call