api-client

Alasan ada: semua pemanggilan backend lewat satu pintu yang menangani URL, timeout, token, dan format error, supaya kode fitur tidak mengulanginya.

Mode: frontend.

npm create nextjs-kit@latest my-app -- --mode frontend --modules api-client

Pemakaian

import { api } from "@/server/api/client";

const todos = await api.get<Todo[]>("/todos", { query: { done: false } });
const created = await api.post<Todo>("/todos", { body: { title: "Belajar" } });

api punya get, post, put, patch, dan delete. Body object dikirim sebagai JSON, FormData dan string dikirim apa adanya. Response 204 mengembalikan undefined.

Client ini hanya untuk server (import "server-only"). Panggil dari Server Component, Server Action, atau route handler.

Error

Response non-2xx dan kegagalan jaringan dilempar sebagai ApiError (@/lib/api-error), apa pun bentuk body dari backend. Bentuk yang dikenali:

• { message }, { error }, { detail }, { title } (RFC 9457)
• { error: { message, code } }
• { errors: { field: [...] } } (Laravel) atau { fieldErrors: {...} }

Untuk status 5xx, pesan dan detail dari backend tidak diteruskan: ApiError.message selalu generik, hanya code yang dipertahankan. Ringkasannya dicatat di log server lewat logger: path tanpa query string, serta field code, message, error, detail, title, requestId, dan traceId yang bertipe string dan dipotong 300 karakter. Body mentah tidak pernah dicatat, karena bisa memuat kredensial atau data pengguna yang di-echo backend.

Kondisi	status	code
Backend tidak terjangkau	503	network_error
Melewati timeout	504	timeout

Di Server Action, ubah error menjadi hasil untuk form dengan toActionError:

try {
  await api.post("/todos", { body: parsed.data });
} catch (error) {
  return toActionError(error);
}

Environment

Variabel	Default	Keterangan
API_BASE_URL	http://localhost:8080	URL backend, hanya dipakai di server
API_TIMEOUT_MS	10000	Batas waktu satu request