next-safe-form 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+<!-- @format -->
+
+# 🚀 next-safe-form
+
+> Simplify React 19 Server Actions forms in Next.js — without the boilerplate.
+
+---
+
+## ✨ Why this library?
+
+Using `useActionState` with forms in React 19 + Next.js can quickly become repetitive and messy:
+
+- Handling loading states
+- Managing field errors vs server errors
+- Syncing form values
+- Triggering side effects (toast, redirect, etc.)
+
+👉 **next-safe-form solves all of this with a single hook.**
+
+---
+
+## ⚡ Features
+
+- ✅ Clean abstraction over `useActionState`
+- ✅ Automatic handling of:
+
+  - loading state
+  - success state
+  - field errors
+  - server errors
+
+- ✅ Works seamlessly with Next.js Server Actions
+- ✅ Type-safe
+- ✅ Minimal API
+- ✅ Scalable architecture
+
+---
+
+## 📦 Installation
+
+```bash
+npm install next-safe-form
+```
+
+or
+
+```bash
+pnpm add next-safe-form
+```
+
+or
+
+```bash
+yarn add next-safe-form
+```
+
+or
+
+```bash
+bun add next-safe-form
+```
+
+---
+
+## 🧠 Concept (Simple Explanation)
+
+Think of it like this:
+
+👉 Instead of manually handling:
+
+- `useActionState`
+- error parsing
+- UI state
+- side effects
+
+You just use:
+
+```ts
+useActionForm();
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Server Action (standard format)
+
+```ts
+export async function loginAction(_, formData: FormData) {
+  const data = Object.fromEntries(formData);
+
+  // Example validation error
+  if (!data.email) {
+    return {
+      success: false,
+      error: { email: "Email is required" },
+      type: "fields",
+    };
+  }
+
+  // Example server error
+  if (data.email !== "test@test.com") {
+    return {
+      success: false,
+      error: "Invalid credentials",
+      type: "server",
+    };
+  }
+
+  return {
+    success: true,
+    data,
+  };
+}
+```
+
+---
+
+### 2. Client Form
+
+```tsx
+"use client";
+
+import { useActionForm } from "next-safe-form";
+
+export default function LoginForm() {
+  const { formAction, isPending, fieldsErrors, serverError } = useActionForm({
+    action: loginAction,
+    initialValues: {
+      email: "",
+      password: "",
+    },
+    onSuccess: () => {
+      alert("Login successful!");
+    },
+    onError: (err) => {
+      alert(err);
+    },
+  });
+
+  return (
+    <form action={formAction}>
+      <input name="email" placeholder="Email" />
+      {fieldsErrors?.email && <p>{fieldsErrors.email}</p>}
+
+      <input name="password" type="password" placeholder="Password" />
+
+      {serverError && <p>{serverError}</p>}
+
+      <button disabled={isPending}>{isPending ? "Loading..." : "Login"}</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 🧩 API
+
+### `useActionForm(options)`
+
+| Option          | Type     | Description            |
+| --------------- | -------- | ---------------------- |
+| `action`        | function | Server action          |
+| `initialValues` | object   | Initial form values    |
+| `onSuccess`     | function | Called on success      |
+| `onError`       | function | Called on server error |
+
+---
+
+## 🔁 Returned values
+
+| Property       | Description             |
+| -------------- | ----------------------- |
+| `formAction`   | Form action handler     |
+| `isPending`    | Loading state           |
+| `fieldsErrors` | Field validation errors |
+| `serverError`  | Server error message    |
+| `data`         | Returned data           |
+| `isSuccess`    | Success state           |
+| `reset`        | Reset form              |
+
+---
+
+## 🏗️ Roadmap
+
+- [ ] Zod integration
+- [ ] Client-side validation
+- [ ] Server helpers (`createSafeAction`)
+- [ ] Devtools
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 👤 Author
+
+Built with ❤️ for Next.js developers

package/dist/index.cjs

@@ -0,0 +1,85 @@
+/** @format */
+
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if ((from && typeof from === "object") || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (
+  (target = mod != null ? __create(__getProtoOf(mod)) : {}),
+  __copyProps(
+    // If the importer is in node compatibility mode or this is not an ESM
+    // file that has been converted to a CommonJS file using a Babel-
+    // compatible transform (i.e. "__esModule" has not been set), then set
+    // "default" to the CommonJS "module.exports" for node compatibility.
+    isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+    mod
+  )
+);
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useActionForm: () => use_action_form_default,
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/use-action-form.ts
+var import_react = __toESM(require("react"), 1);
+function useActionForm({ action, initialValues, onSuccess, onError }) {
+  const [state, formAction, isPending] = import_react.default.useActionState(action, {
+    success: false,
+    data: initialValues,
+  });
+  const [fieldsErrors, setFieldsErrors] = import_react.default.useState(void 0);
+  const [serverError, setServerError] = import_react.default.useState(void 0);
+  const [data, setData] = import_react.default.useState(initialValues);
+  import_react.default.useEffect(() => {
+    if (!state) return;
+    if (state.success) {
+      setData(state.data);
+      onSuccess?.(state.data);
+      return;
+    }
+    if (state.error?.type === "fields") {
+      setFieldsErrors(state.error.fields);
+    }
+    if (state.error?.type === "server") {
+      setServerError(state.error.message);
+      onError?.(state.error.message);
+    }
+  }, [state]);
+  const reset = import_react.default.useCallback(() => {
+    setData(initialValues);
+    setFieldsErrors(void 0);
+    setServerError(void 0);
+  }, [initialValues]);
+  return {
+    formAction,
+    isPending,
+    fieldsErrors,
+    serverError,
+    data,
+    isSuccess: state?.success ?? false,
+    reset,
+  };
+}
+var use_action_form_default = useActionForm;
+// Annotate the CommonJS export names for ESM import in node:
+0 &&
+  (module.exports = {
+    useActionForm,
+  });

package/dist/index.d.cts

@@ -0,0 +1,34 @@
+/** @format */
+type TSafeActionResult<T> = {
+    success: boolean;
+    data: T;
+    error?: {
+        type: "fields" | "server";
+        message?: string;
+        fields?: Record<string, string>;
+        code?: number;
+    };
+};
+interface UseActionFormOptions<T> {
+    action: (state: any, formData: FormData) => Promise<TSafeActionResult<T>>;
+    initialValues: T;
+    onSuccess?: (data: T) => void;
+    onError?: (error: any) => void;
+}
+
+/**
+ * eslint-disable @typescript-eslint/no-explicit-any
+ * @format
+ */
+
+declare function useActionForm<T>({ action, initialValues, onSuccess, onError }: UseActionFormOptions<T>): {
+    formAction: (payload: FormData) => void;
+    isPending: boolean;
+    fieldsErrors: Record<string, string> | undefined;
+    serverError: string | undefined;
+    data: T;
+    isSuccess: boolean;
+    reset: () => void;
+};
+
+export { type TSafeActionResult, useActionForm };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/** @format */
+type TSafeActionResult<T> = {
+    success: boolean;
+    data: T;
+    error?: {
+        type: "fields" | "server";
+        message?: string;
+        fields?: Record<string, string>;
+        code?: number;
+    };
+};
+interface UseActionFormOptions<T> {
+    action: (state: any, formData: FormData) => Promise<TSafeActionResult<T>>;
+    initialValues: T;
+    onSuccess?: (data: T) => void;
+    onError?: (error: any) => void;
+}
+
+/**
+ * eslint-disable @typescript-eslint/no-explicit-any
+ * @format
+ */
+
+declare function useActionForm<T>({ action, initialValues, onSuccess, onError }: UseActionFormOptions<T>): {
+    formAction: (payload: FormData) => void;
+    isPending: boolean;
+    fieldsErrors: Record<string, string> | undefined;
+    serverError: string | undefined;
+    data: T;
+    isSuccess: boolean;
+    reset: () => void;
+};
+
+export { type TSafeActionResult, useActionForm };

package/dist/index.js

@@ -0,0 +1,44 @@
+/** @format */
+
+// src/hooks/use-action-form.ts
+import React from "react";
+function useActionForm({ action, initialValues, onSuccess, onError }) {
+  const [state, formAction, isPending] = React.useActionState(action, {
+    success: false,
+    data: initialValues,
+  });
+  const [fieldsErrors, setFieldsErrors] = React.useState(void 0);
+  const [serverError, setServerError] = React.useState(void 0);
+  const [data, setData] = React.useState(initialValues);
+  React.useEffect(() => {
+    if (!state) return;
+    if (state.success) {
+      setData(state.data);
+      onSuccess?.(state.data);
+      return;
+    }
+    if (state.error?.type === "fields") {
+      setFieldsErrors(state.error.fields);
+    }
+    if (state.error?.type === "server") {
+      setServerError(state.error.message);
+      onError?.(state.error.message);
+    }
+  }, [state]);
+  const reset = React.useCallback(() => {
+    setData(initialValues);
+    setFieldsErrors(void 0);
+    setServerError(void 0);
+  }, [initialValues]);
+  return {
+    formAction,
+    isPending,
+    fieldsErrors,
+    serverError,
+    data,
+    isSuccess: state?.success ?? false,
+    reset,
+  };
+}
+var use_action_form_default = useActionForm;
+export { use_action_form_default as useActionForm };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "next-safe-form",
+  "version": "1.0.0",
+  "description": "Simplify React 19 Server Actions forms in Next.js",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nextjs",
+    "react",
+    "forms",
+    "server-actions"
+  ],
+  "author": "4develhoper",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "tsup": "^8.5.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "publish": "npm publish",
+    "publish-public": "npm publish --access public",
+    "publish-private": "npm publish --access restricted"
+  }
+}