@alyvro/nexus 🚀

The ultimate type-safe bridge between Next.js Server Actions and Client Components. Standardize your data flow, handle validations with Zod, and manage loading/error states effortlessly.

✨ Features

• Zero-Config Type Safety: Automatic TypeScript inference from Server to Client.
• Zod Integration: First-class support for input validation.
• Smart Transitions: Uses React's useTransition under the hood for a smooth UX.
• Error Handling: Distinct handling for validation errors and server exceptions.
• Lightweight: Zero bloat, designed specifically for Next.js App Router.

📦 Installation

pnpm add @alyvro/nexus zod

🚀 Quick Start

1. Define a Server Action

Create a file (e.g., actions.ts) and use createNexusAction.

// actions.ts
"use server";
import { createNexusAction } from "@alyvro/nexus/server";
import { z } from "zod";

const Schema = z.object({
  email: z.string().email("Invalid email address"),
});

export const subscribeUser = createNexusAction(Schema, async (data) => {
  // Simulate DB delay
  await new Promise((res) => setTimeout(res, 1000));

  return { id: "123", message: `Subscribed: ${data.email}` };
});

2. Use in Client Component

Use the useNexus hook to trigger the action and track its state.

// FormComponent.tsx
"use client";
import { useNexus } from "@alyvro/nexus/client";
import { subscribeUser } from "./actions";

export default function SubscribeForm() {
  const { execute, data, isLoading, error, validationErrors } = useNexus(subscribeUser);

  return (
    <div>
      <button onClick={() => execute({ email: "[email protected]" })} disabled={isLoading}>
        {isLoading ? "Loading..." : "Subscribe"}
      </button>

      {data && <p className="text-green-500">{data.message}</p>}
      {error && <p className="text-red-500">{error}</p>}
      {validationErrors?.email && <p className="text-orange-500">{validationErrors.email[0]}</p>}
    </div>
  );
}

🛠 API Reference

createNexusAction(schema, handler)

• schema: A Zod schema.
• handler: Your async logic. Receives validated data.

useNexus(action, options?)

Returns:

• execute(input): Function to trigger the action.
• data: The result of the action.
• isLoading: Boolean (uses useTransition).
• error: Generic server error message.
• validationErrors: Field-specific errors from Zod.
• reset(): Clear all states.

🛡 License

MIT © Alyvro