Epic: Direct Client-Backend API Migration—Remove Server-Proxied Remote Functions for a Secure, Scalable SvelteKit Frontend

[TheRealSeber]

Objective

Migrate from a server-proxied (remote functions) API architecture to a direct client-to-backend API integration in our SvelteKit (Svelte 5) frontend application. The goal is to streamline the application structure, enhance scalability, and modernize authentication/token management, while maintaining developer ergonomics, robust security (with http-only cookies and access tokens), and complete parity in feature support.

---

Motivation

The existing use of SvelteKit remote functions introduces a redundant proxy layer for API communication, which increases complexity and obscures the client/server boundary. Shifting to a direct client-side API model simplifies architecture, improves performance, and better leverages modern Svelte patterns. Authentication should rely on secure, standards-based mechanisms: the backend will continue setting refresh tokens via http-only cookies, while access tokens will be managed client-side (e.g., localStorage with in-memory cache) and transparently sent with each request.

---

Migration Steps

1. Backend CORS & API Service Refactor

• API Client (OO, client-side): Refactor ApiService.ts into an object-oriented class supporting instantiation in both SSR and browser contexts.
  • Remove reliance on server-only utilities.
  • Add createClientApiClient() factory for browser
  • Expose public API base URL via $env/dynamic/public.
  • Update refresh token logic to rely on backend's http-only cookies.
  • Implement robust client-side access token management (storage, renewal, handling race conditions, memory cache fallback).
  • createClientApiClient must be implemented next to the existing logic, since we will be migrating to new functionalities set pby step not everything at once

2. Query Management Refactor

• Custom Query Utility: Build createQuery() leveraging Svelte 5 runes ($state, $derived).
  • Expose { current, loading, error, refresh() } and full type safety for query state.
  • Support parameterless and validated-parameter queries.
  • Create a base class representing that
• Migration: Refactor sample remote functions (tasks.remote.ts, user.remote.ts, task.remote.ts) to use the new query utility and direct client API calls.
  • Remove all uses of getRequestEvent() and server cookie handling.

3. Client-Side Form Handling

• Custom Form Utility: Build createForm() abstraction with Valibot validation.
  • Integrate submitting state, field-level errors, and action handler for SvelteKit-enhanced forms.
  • Support file uploads (FormData serialization) and post-success navigation via goto().
  • Migrate representative forms (e.g., login.remote.ts, submit.remote.ts).

4. Direct Command Execution

• Remove the command() wrappers (e.g., contests.remote.ts, registration-requests.remote.ts).
• Call service methods directly within relevant client event-handlers.
• Implement manual loading/error state management and explicit query refresh triggers.

5. Authentication & Token Handling Redesign

• Refactor TokenManager and AuthService for robust client-side access token lifecycle:
  • Store access tokens with a layered strategy (localStorage/sessionStorage + memory cache).
  • Refresh tokens remain handled securely via backend-set http-only cookies.
  • Update login flow to extract/set access token, trigger API client update.
  • Remove/harden any server-side token management artifacts (e.g., hooks.server.ts).
• Implement client-side route guards and redirect logic in +page.ts load functions (using goto()).

6. Cleanup & Documentation

• Remove all *.remote.ts files.
• Refactor all component imports to utilize the new query/form utilities.
• Update svelte.config.js (remove experimental.remoteFunctions).
• Lint and type-check codebase, ensuring no lingering remote function artifacts.
• Document migration decisions, architecture rationale, and authentication patterns for maintainers.

---

Acceptance Criteria

• No SvelteKit remote function proxies remain; all API interaction is direct.
• Feature parity, authentication (with refresh token in http-only cookie, access token client-side), SSR support, and robust error handling are preserved.
• All code follows TypeScript strict mode, object-oriented patterns, and Svelte 5 runes best practices.
• Developer onboarding/documentation is clear regarding new API and auth flows.

---

This migration is critical for scaling the frontend platform with clean separation of concerns, improved security posture, and modern Svelte paradigms.