next-action-client ⚡

The Postman for Next.js Server Actions.

Stop building throwaway forms just to test your 'use server' functions.
next-action-client gives you a visual dev UI that auto-discovers all your Server Actions, lets you fill in JSON arguments, and executes them instantly — with full response inspection.

npx next-action-client

Open http://localhost:3001 and you're done.

Works with Next.js 14 and 15. Zero config. Pure dev-only.

The problem

Since Next.js 14, Server Actions are everywhere. But testing them manually is painful:

1. You create a temporary <form> in your UI just to trigger the action
2. You add console.log on the server to see what's returned
3. You repeat this for every action, every time

There's no Postman/Insomnia equivalent for Server Actions — until now.

How it works

1. Scans your app/ directory using TypeScript's AST (ts-morph) — detects every file with 'use server' and extracts every exported async function with its parameter names and types
2. Displays them in a clean UI — sidebar grouped by file, JSON argument editor, keyboard shortcut ⌘↵ to execute
3. Executes the action and shows the response with syntax-highlighted JSON — or the full error + stack trace
4. Updates live via WebSocket when you modify your Server Actions files

Quick start

# Run directly (no install needed)
npx next-action-client

# Or as a dev dependency
npm install --save-dev next-action-client
npx nac

The UI opens automatically at http://localhost:3001.

Features

• Zero config — one command, works out of the box
• TypeScript-aware — shows parameter names and types extracted from source
• JSON argument editor — with inline validation and type hints
• Syntax-highlighted response viewer (recursive JSON renderer)
• Live file watching — UI updates automatically on file changes
• Two execution modes — direct (tsx subprocess) or proxy (full Next.js context)
• nac scan — CLI-only scan, outputs JSON for scripting
• Dev-only safety guard — returns 403 in production, safe to deploy

CLI options

Usage: nac [options] [command]
       next-action-client [options]

Commands:
  start (default)   Start the visual dev UI
  scan              List all Server Actions in the terminal

Options:
  -p, --port        Port for the dev server (default: 3001)
  -d, --dir         Next.js project root (default: current directory)
  --next-url        URL of the running Next.js server, for proxy mode (default: http://localhost:3000)
  --no-open         Do not open the browser automatically
  -V, --version     Show version

# Custom port
npx nac --port 4000

# Project in a subdirectory (monorepo)
npx nac --dir ./apps/web

# CLI scan, JSON output (great for CI or scripting)
npx nac scan --json

Execution modes

Direct mode (default, zero setup)

Actions run in an isolated tsx subprocess. Works for the vast majority of Server Actions:

• ✅ Database queries (Prisma, Drizzle, Supabase, Mongoose…)
• ✅ External API calls
• ✅ Data validation and transformation
• ❌ cookies(), headers() from next/headers
• ❌ revalidatePath(), revalidateTag() from next/cache

Integrated mode (full Next.js context)

Add one file to your project to unlock full context support:

// app/api/__nac/execute/route.ts
export { POST, GET } from 'next-action-client/handler';

Then start with --next-url:

npx nac --next-url http://localhost:3000

The client detects the handler automatically and switches to proxy mode. All Next.js APIs work correctly.

The handler guards itself with process.env.NODE_ENV !== 'development' — it is safe to commit.

Optional Next.js plugin

Add an extra production safety layer to your config:

// next.config.ts
import { withActionClient } from 'next-action-client/plugin';

export default withActionClient({
  // your existing config
});

Programmatic API

import { createScanner, executeAction, startServer } from 'next-action-client';

// Scan a project for Server Actions
const scanner = createScanner('/path/to/project');
const { actions } = await scanner.scan();
// actions: Array<{ id, name, filePath, relativePath, parameters, returnType, line }>

// Execute a specific action
const result = await executeAction(
  '/path/to/project/app/actions/user.ts',
  'createUser',
  ['John', '[email protected]'],
  { projectRoot: '/path/to/project' }
);

// Start the dev server
const { url, close } = await startServer({
  port: 3001,
  projectRoot: '/path/to/project',
  nextjsUrl: 'http://localhost:3000',
});

Requirements

• Node.js ≥ 18
• Next.js ≥ 14

tsx is used for direct execution — it runs automatically via npx tsx, no manual install needed.

FAQ

Does it work with the Pages Router?
No — Server Actions are an App Router feature ('use server').

Is it safe in production?
Yes. The dev UI only starts when you explicitly run npx nac. The optional route handler (/api/__nac/execute) blocks all requests with a 403 when NODE_ENV !== 'development'.

Does it support JavaScript projects (no TypeScript)?
Yes — .js and .jsx files are scanned too. Parameter types will show as any.

What about monorepos?
Use --dir ./apps/web to point to the right Next.js root.

License

MIT — made by roka_sa