frontend-lib

Frontend Lib Patterns

Thesis: Lib files are the shared foundation: typed API client, auth store, constants, and utilities. Every API call is typed, every protected route is registered.

Follow the established patterns in api.ts, auth.ts, and constants.ts.

API Client (api.ts)

Adding a New API Module

Group types and methods together. Follow the established API object pattern:

// 1. Define TypeScript interfaces matching backend response structs
export interface Item {
  id: string;
  title: string;
  // ... fields match the Go Detail struct exactly
}

export interface ItemListResult {
  items: Item[];
  total: number;
  page: number;
  per_page: number;
  total_pages: number;
}

// 2. Query builder for list endpoints (if filterable)
function buildItemQuery(params?: ItemListParams): string { ... }

// 3. API object with typed methods
export const itemsApi = {
  create: (data: CreateItemInput) => post<Item>("/items", data),
  list: (params?: ItemListParams) => get<ItemListResult>(`/items${buildItemQuery(params)}`),
  getById: (id: string) => get<Item>(`/items/${id}`),
  update: (id: string, data: Partial<Item>) => put<Item>(`/items/${id}`, data),
  delete: (id: string) => del<{ message: string }>(`/items/${id}`),
};

Conventions

• Use the convenience helpers — get, post, put, patch, del from the same file. Never raw fetch.
• Type every response — get<MyType>(...) not get<any>(...).
• All endpoints start with / — the api() function prepends /api/v1.
• skipAuth: true only for public endpoints (login, register, universities).
• Optional fields use ? — match the Go struct's omitempty tags.

Search/Filter Query Builder

For list endpoints with search and pagination, use a query builder function:

function buildItemQuery(params?: { page?: number; perPage?: number; search?: string }): string {
  const p = new URLSearchParams();
  if (params?.page) p.set("page", String(params.page));
  if (params?.perPage) p.set("per_page", String(params.perPage));
  if (params?.search) p.set("search", params.search);
  const qs = p.toString();
  return qs ? `?${qs}` : "";
}