React Server Actions Generator

Tính năng nổi bật

• Sinh file Server Action TypeScript có chỉ thị 'use server' ở đầu file
• Tên action tùy chọn, kiểm tra là định danh JavaScript hợp lệ trước khi sinh code
• Chữ ký (prevState, formData) và kiểu trả về Promise<ActionState> dùng thẳng được với useActionState của React 19
• Tùy chọn Zod validation: schema mẫu, safeParse trên server, trả fieldErrors theo từng field
• Tùy chọn revalidatePath từ next/cache, chỉ chạy khi thao tác thành công
• Khối try/catch ghi log lỗi ở server và trả thông báo chung, không lộ chi tiết nội bộ cho client
• Chú thích nhắc kiểm tra đăng nhập và quyền vì Server Action là endpoint POST công khai
• Kèm ví dụ Client Component dùng useActionState, hiển thị lỗi field, trạng thái isPending
• Code sinh ra đã được kiểm tra kiểu với TypeScript strict, React 19 và Zod 3
• Copy toàn bộ code bằng một nút, miễn phí

Server Actions thay thế API Routes như thế nào?

Trước khi có Server Actions, mọi thao tác ghi dữ liệu từ form phải đi qua API route (ví dụ /api/users) với khá nhiều code lặp: tạo route, gọi fetch() từ client, tự quản lý trạng thái loading và lỗi, parse JSON, validate request rồi trả JSON về. Server Actions trong Next.js App Router đơn giản hóa việc này: bạn viết một hàm async chạy trên server, đánh dấu 'use server', rồi gắn thẳng vào thuộc tính action của form hoặc gọi từ client như một hàm bình thường. Lợi ích: kiểu dữ liệu được TypeScript theo dõi từ đầu đến cuối mà không cần viết hợp đồng API riêng; form có thể gửi được cả khi JavaScript chưa tải xong (progressive enhancement); Next.js tự tạo endpoint, không cần cấu hình; tích hợp với transitions, useActionState, useOptimistic của React; logic nằm ở server nên không làm tăng bundle phía client; và làm mới dữ liệu đã cache ngay sau thao tác bằng revalidatePath hoặc revalidateTag. Dù vậy, Server Action vẫn là một endpoint HTTP, nên các nguyên tắc bảo mật của API vẫn áp dụng đầy đủ.

Lợi ích khi sử dụng

• •Bớt nhiều code lặp so với API route cho các thao tác ghi dữ liệu nội bộ
• •Type-safe từ server tới client mà không cần OpenAPI hay tRPC
• •Progressive enhancement: form gắn trực tiếp Server Action có thể gửi được khi JavaScript chưa tải xong
• •Làm mới cache ngay sau thao tác bằng revalidatePath hoặc revalidateTag
• •Giảm bundle phía client vì logic chạy trên server
• •Truy cập trực tiếp database hoặc dịch vụ nội bộ, không cần lớp REST trung gian
• •Tích hợp tự nhiên với transitions, useActionState và useOptimistic
• •Khung code sinh sẵn đã có validate phía server và nhắc kiểm tra quyền

Hướng dẫn tạo và sử dụng Server Actions

1. 1Nhập tên action vào ô Action Name, ví dụ createUser hoặc updateProfile. Tên phải bắt đầu bằng chữ cái, _ hoặc $ và không có khoảng trắng.
2. 2Bật Include Zod Validation nếu muốn có schema và bước validate phía server (cần cài gói zod trong dự án).
3. 3Bật Include Revalidation nếu sau khi lưu cần làm mới dữ liệu đang hiển thị ở một đường dẫn.
4. 4Bấm Generate Server Action để sinh code, rồi bấm nút copy.
5. 5Dán vào một file riêng, ví dụ app/actions.ts, thay schema mẫu bằng các field thật của form và thêm logic ghi dữ liệu vào khối try.
6. 6Thêm kiểm tra đăng nhập và quyền ở đầu hàm, đổi đường dẫn trong revalidatePath thành trang đang hiển thị dữ liệu.
7. 7Tạo Client Component theo ví dụ trong phần chú thích cuối file: dùng useActionState, gắn formAction vào form và hiển thị state.message, state.fieldErrors.
8. 8Chạy npm run dev, gửi form với dữ liệu hợp lệ và không hợp lệ để kiểm tra cả hai nhánh.

Pattern chuẩn cho Server Actions với validation và error handling

Cấu trúc nên theo: 1) Đánh dấu 'use server' ở đầu file (hoặc đầu thân hàm nếu hàm nằm trong Server Component). 2) Định nghĩa Zod schema cho input. 3) Kiểm tra đăng nhập và quyền ngay đầu hàm. 4) Validate input bằng schema.safeParse(), không ném lỗi mà trả về lỗi theo field. 5) Thực hiện logic nghiệp vụ, ví dụ ghi database, trong try/catch. 6) Gọi revalidatePath() hoặc revalidateTag() để làm mới cache. 7) Trả về một object có hình dạng cố định như { success, message, fieldErrors } cho các lỗi dự đoán được; chỉ để lỗi ngoài dự kiến rơi vào error boundary. 8) Tùy chọn gọi redirect() để chuyển trang, lưu ý redirect hoạt động bằng cách ném ra một lỗi đặc biệt nên phải gọi ngoài khối try/catch. Phía client: useActionState để giữ kết quả và trạng thái đang gửi, useFormStatus cho nút bấm nằm trong form, useOptimistic để cập nhật giao diện ngay. Cần xử lý đủ ba nhánh: lỗi validate, lỗi quyền và lỗi server, mỗi nhánh có thông báo rõ ràng.

Code công cụ sinh ra gồm những gì, giải thích từng phần

Với tên createUser và bật cả hai tùy chọn, file sinh ra có: dòng 'use server'; import z từ zod và revalidatePath từ next/cache; kiểu ActionState gồm success, message và fieldErrors; schema mẫu với một field name bắt buộc sau khi cắt khoảng trắng; hàm export async function createUser(prevState: ActionState, formData: FormData): Promise<ActionState>. Trong hàm là chú thích nhắc kiểm tra quyền, rồi schema.safeParse({ name: formData.get('name') }); nếu thất bại trả về success: false kèm validatedFields.error.flatten().fieldErrors, nếu thành công đi tiếp vào try, nơi bạn gọi database với validatedFields.data. Lỗi trong try được console.error ở server và client chỉ nhận thông báo chung. revalidatePath('/') chỉ chạy khi không có lỗi, sau đó trả về success: true. Cuối file là một khối chú thích chứa Client Component mẫu. Chúng tôi đã kiểm tra cả bốn tổ hợp bật tắt tùy chọn bằng TypeScript ở chế độ strict với React 19 và Zod 3, không có lỗi kiểu.

useActionState thay cho useFormState: thay đổi của React 19

Trong React 19, hook useFormState của react-dom được đổi tên và chuyển thành useActionState, import từ react. Chữ ký là const [state, formAction, isPending] = useActionState(action, initialState): hook trả thêm isPending nên không cần useFormStatus chỉ để biết form đang gửi. Action truyền vào nhận hai tham số (prevState, formData) chứ không phải chỉ formData, đây là lý do code sinh ra có tham số prevState dù thân hàm chưa dùng tới. Next.js 15 dùng React 19 cho App Router, nên với dự án mới hãy dùng useActionState. Nếu dự án còn ở Next.js 14 với React 18, useActionState chưa có; khi đó dùng useFormState từ react-dom với cùng chữ ký (prevState, formData), phần Server Action giữ nguyên.

Lỗi kiểu thường gặp: gắn action trả về object thẳng vào form

Một lỗi rất phổ biến khi nâng lên React 19 là viết action dạng async function createUser(formData: FormData) trả về { error: '...' } rồi gắn thẳng <form action={createUser}>. Với kiểu dữ liệu của React 19, thuộc tính action của form chỉ nhận hàm trả về void hoặc Promise<void>, nên TypeScript báo lỗi kiểu không gán được, và kể cả khi bỏ qua lỗi thì giá trị trả về cũng bị bỏ đi, người dùng không bao giờ thấy thông báo lỗi. Có hai cách đúng: action không cần báo kết quả thì trả về void (có thể redirect sau khi xong); action cần báo lỗi hoặc thành công thì dùng chữ ký (prevState, formData) và gắn qua useActionState như code công cụ sinh ra.

Bảo mật Server Actions: những điều khung code không tự làm thay bạn

Mỗi Server Action được export sẽ trở thành một endpoint POST mà bất kỳ ai cũng có thể gọi trực tiếp, không cần đi qua giao diện của bạn. Vì vậy: luôn kiểm tra phiên đăng nhập và quyền trên từng action, không dựa vào việc nút bấm bị ẩn ở giao diện; luôn validate lại input trên server dù client đã kiểm tra; không nhận các trường nhạy cảm như userId, role, giá tiền từ formData khi server tự xác định được; không trả lỗi gốc từ database về client. Next.js có một số lớp bảo vệ mặc định: so sánh header Origin với Host để giảm nguy cơ CSRF, tạo ID khó đoán cho action và loại bỏ action không được dùng khỏi bản build, giới hạn kích thước body mặc định 1MB (chỉnh bằng serverActions.bodySizeLimit). Các lớp này không thay thế được kiểm tra quyền. Với thao tác dễ bị lạm dụng như gửi form liên hệ, đăng ký, hãy thêm giới hạn tần suất theo IP hoặc tài khoản.

Server Actions vs API Routes vs tRPC: khi nào dùng cái nào

Server Actions: phù hợp nhất cho thao tác ghi dữ liệu từ chính ứng dụng Next.js như gửi form, bấm nút. Type-safe, ít code lặp, hỗ trợ progressive enhancement. Route Handlers (API Routes): cần khi có client bên ngoài (ứng dụng di động, bên thứ ba), webhook, API công khai có quản lý phiên bản và giới hạn tần suất, hoặc khi cần trả luồng dữ liệu, file, định dạng tùy ý. Server Action cũng không phù hợp để đọc dữ liệu: chúng chạy tuần tự và dùng phương thức POST, việc đọc dữ liệu nên làm trong Server Component hoặc route handler. tRPC: phù hợp khi cần type-safety nhưng dùng backend riêng như Express, Hono, hoặc nhiều loại client. Mô hình kết hợp thường gặp: Server Actions cho thao tác nội bộ, Route Handlers cho endpoint công khai và webhook. Có thể chuyển dần từ API route sang Server Actions, giữ API route cũ cho client bên ngoài.

Zod 3 và Zod 4: lưu ý khi dùng code sinh ra

Code sinh ra dùng z.object, z.string().trim().min() và safeParse, các API này giống nhau ở Zod 3 và Zod 4. Phần khác biệt là cách gom lỗi theo field: validatedFields.error.flatten().fieldErrors là cách chuẩn ở Zod 3; ở Zod 4 phương thức này vẫn chạy nhưng đã bị đánh dấu không khuyến khích, cách mới là z.flattenError(validatedFields.error).fieldErrors. Kiểm tra phiên bản zod trong package.json của bạn. Lưu ý thêm: formData.get() trả về string, File hoặc null. Nếu input không có trong form, giá trị là null và Zod sẽ báo lỗi kiểu thay vì thông báo bạn đặt trong min(); với checkbox, trường chưa tích cũng là null, nên dùng z.coerce hoặc xử lý riêng; với số, dùng z.coerce.number() vì dữ liệu form luôn là chuỗi.

Giới hạn của công cụ

Công cụ chỉ có ba thiết lập: tên action, bật tắt Zod và bật tắt revalidatePath. Nó không sinh CRUD theo entity, không tích hợp Prisma hay Drizzle, không sinh code upload file, useOptimistic, redirect, cookies hay rate limiting, và không tự thêm thư viện xác thực như Auth.js hay Clerk; phần kiểm tra quyền chỉ là chú thích để bạn tự viết. Schema chỉ có một field mẫu name, đường dẫn revalidate mặc định là trang chủ, và ví dụ Client Component nằm trong khối chú thích để bạn tách ra file riêng có 'use client'. Hãy xem đầu ra là bộ khung đúng chuẩn để bắt đầu, sau đó đọc tài liệu Next.js và React cho phiên bản bạn đang dùng.

Câu hỏi thường gặp (FAQ)

Từ khóa liên quan

• react server actions generator
• next.js server actions
• server actions next.js 15
• server actions zod validation
• useActionState
• useActionState react 19
• useFormState deprecated
• useOptimistic
• next.js form action
• react 19 server actions
• next.js revalidatePath
• use server
• server actions bảo mật
• type-safe server functions
• next.js app router form
• zod safeParse formData
• next.js mutations tutorial
• server actions vs api routes