Best practices for Next.js API architecture with external Express.js backend

[Zakisb]

Summary

Context

I've been building full-stack applications with Next.js for some time, where both the frontend and backend were unified in the same Next.js application. Recently, I'm working on an admin panel (built with Next.js) that interfaces with an existing Express.js backend server (which also serves our mobile app).

Current Setup

• Next.js 15 (App Router) for the admin panel frontend
• Express.js backend as a separate service
• Clerk for authentication
• Service-based architecture for API calls
• React Query for client components fetching / data mutations ( yeah i'm not using server actions yet )

This new architecture presents some challenges I'd like to discuss and hear your opinions on it.

This setup currently works well for:

1. Server Components fetching data (e.g., getting list of exercises)
2. Client Components with React Query mutations (e.g., creating new exercises)

The Challenge

The core issue emerged when implementing Clerk authentication. The same fetchWithAuth function gets called from both server and client contexts:

1.In Server Components:

// pages/exercises/page.tsx (Server Component)
async function ExercisesPage() {
    const exerciseService = new ExerciseService();
    const exercises = await exerciseService.getExercises();
    // ...
}

2. In Client Components:

// components/CreateExercise.tsx (Client Component)
'use client'
export function CreateExercise() {
    const mutation = useMutation({
        mutationFn: (data) => {
            const exerciseService = new ExerciseService();
            return exerciseService.createExercise(data);
        }
    });
    // ...
}

The problem is that getting the Clerk token requires different approaches based on context:

// ForServer Components
import { auth } from '@clerk/nextjs/server';
const { getToken } = auth();

// For Client Components
import { useAuth } from '@clerk/nextjs';
const { getToken } = useAuth();

But our fetchWithAuth function doesn't know which context it's being called from!

Questions

1. How do you handle this server/client context difference in service files that need to work in both contexts? Specific approaches for Token retrieval ?
2. What's the recommended pattern when the same service needs to work seamlessly in both Server and Client Components?
3. Is splitting into separate server/client services the right approach, or is there a cleaner way to handle this?

Additional information

// base-service.js file

function objectToQueryString(obj) {
  return Object.keys(obj)
    .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(obj[key])}`)
    .join("&");
}

function createApiError(message, status) {
  return { message, status };
}

async function fetchWithAuth(baseUrl, endpoint, options = { method: "GET" }) {
    const token = await getAuthToken(); // This is where the challenge lies
 
  let url = `${baseUrl}${endpoint}`;

  if (options.params) {
    const queryString = objectToQueryString(options.params);
    url += `?${queryString}`;
    delete options.params;
  }

  // Initialize fetch options
  const fetchOptions = {
    method: options.method,
    headers: {
      ...options.headers,
      // ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
  };

  // Handle request body based on content type
  if (options.data) {
    if (options.isMultipart) {
      // For multipart/form-data, let the browser set the boundary
      fetchOptions.body = options.data;
      // Don't set Content-Type for multipart/form-data
    } else {
      fetchOptions.headers["Content-Type"] = "application/json";
      fetchOptions.body = JSON.stringify(options.data);
    }
  }

  try {
    const response = await fetch(url, fetchOptions);

    if (!response.ok) {
      const errorMessages = {
        401: "Unauthorized",
        403: "Forbidden",
        404: "Not Found",
        500: "Internal Server Error",
      };

      const message = errorMessages[response.status] || "An error occurred";
      throw createApiError(message, response.status);
    }

    // Check if response is empty
    const contentType = response.headers.get("content-type");
    if (contentType && contentType.includes("application/json")) {
      return await response.json();
    }

    return null; // Return null for empty responses
  } catch (error) {
    console.error("Fetch error:", error);
    throw error;
  }
}

export function createBaseService(baseUrl) {
  return {
    get: (endpoint, params) => fetchWithAuth(baseUrl, endpoint, { params }),
    post: (endpoint, data, options = {}) =>
      fetchWithAuth(baseUrl, endpoint, { method: "POST", data, ...options }),
    put: (endpoint, data) =>
      fetchWithAuth(baseUrl, endpoint, { method: "PUT", data }),
    delete: (endpoint) =>
      fetchWithAuth(baseUrl, endpoint, { method: "DELETE" }),
  };
}

example of service file

import { createBaseService } from "./base-service";

const baseUrl = process.env.NEXT_PUBLIC_API_URL;
const baseService = createBaseService(baseUrl);
const apiEndpoint = "/exercises";

export const exerciseService = {
  getExercises: (params = {}) => baseService.get(apiEndpoint, params),
  getExercise: (id) => baseService.get(`${apiEndpoint}/${id}`),
  createExercise: (data) =>
    baseService.post(apiEndpoint, data, { isMultipart: true }),
  updateExercise: (id, data) => baseService.put(`${apiEndpoint}/${id}`, data),
  deleteExercise: (id) => baseService.delete(`${apiEndpoint}/${id}`),
  getCategories: () => baseService.get(`${apiEndpoint}/categories`),
  getLevels: () => baseService.get(`${apiEndpoint}/levels`),
};