[Next.js] 클라이언트와 서버 실행 분리해야하는 이유(feat. Zustand)

최근 프로젝트에서 Next.js와 Zustand를 함께 사용해 사용자 상태(userData)를 관리하고 있었습니다. 특히, 상태에 저장된 사용자 정보를 API로 넘기기 위해 Zustand의 useUserStore를 API 함수에서 직접 사용하려 했습니다. 하지만 다음과 같은 오류가 발생했습니다:

webpack://_N_E/src/client/app-index.tsx?b6bc의 콘텐츠를 로드할 수 없습니다. 
(Fetch through target failed: Unsupported URL scheme; Fallback: HTTP 오류: 상태 코드 404, net::ERR_UNKNOWN_URL_SCHEME)

이 오류는 Next.js가 서버와 클라이언트 모두에서 실행되기 때문에, 클라이언트 전용 상태 관리 훅을 서버에서 호출하려 할 때 발생하는 문제입니다. 이 글에서는 이러한 문제를 해결하고, Next.js와 Zustand를 올바르게 사용하는 방법을 설명하려고 합니다.

 

■ 문제 상황: 클라이언트 전용 상태를 서버에서 접근하려는 시도

먼저, 제가 작성했던 코드에서 어떤 부분이 잘못되었는지 살펴보겠습니다. 아래 코드는 API 함수 내에서 직접 Zustand의 useUserStore 훅을 호출하여 상태를 가져오려고 했습니다:

import axios from 'axios';
import { RouteData } from '@/types/routeData';
import useUserStore from '@/store/useUserStore';

axios.defaults.withCredentials = true;

export const route = async (routeData: RouteData): Promise<string> => {
  try {
    const userData = useUserStore((state) => state.user); // 클라이언트 상태를 서버에서 접근 시도
    const response = await axios.post(`${process.env.NEXT_PUBLIC_API_BASE_URL}/api/map/route`, {
      routeData,
      userData,
    });
    return response.data;
  } catch (error: any) {
    console.error(error.message);
    throw error;
  }
};

위 코드에서 상태를 관리하는 useUserStore는 클라이언트에서만 접근할 수 있습니다. 하지만 Next.js는 서버와 클라이언트 모두에서 코드가 실행되기 때문에, 서버에서 이 함수를 호출하려 하면 오류가 발생하게 됩니다.

오류 원인:

• useUserStore는 클라이언트 사이드 상태 관리 훅임.
• Next.js는 서버에서도 이 코드를 실행할 수 있는데, 서버에서는 클라이언트 훅(useUserStore)을 사용할 수 없음. 결과적으로, 서버에서 window와 같은 브라우저 객체가 없기 때문에 해당 오류가 발생.

 

■ 왜 클라이언트와 서버를 분리해야 할까?

Next.js는 **서버 사이드 렌더링(SSR)**과 **클라이언트 사이드 렌더링(CSR)**을 모두 지원하는 프레임워크입니다. 즉, 페이지가 처음 요청될 때 서버에서 미리 렌더링된 HTML을 생성하고, 그 후 클라이언트 사이드에서 React가 페이지를 활성화합니다.

 

이 때문에 서버 사이드에서는 클라이언트 전용 객체나 React 훅에 접근할 수 없습니다. 특히, Zustand와 같은 클라이언트 상태 관리 도구는 서버에서 접근할 수 없기 때문에, 상태를 안전하게 관리하기 위해서는 클라이언트에서만 상태를 사용하도록 해야 합니다.

 

■ 해결 방법: 상태를 컴포넌트에서만 접근하고 API 함수는 순수하게 유지

핵심 원칙은 API 함수는 상태와 무관하게 순수한 비동기 함수로 유지하고, 클라이언트에서 상태를 관리하는 방식으로 코드를 작성하는 것입니다.

1.  API 함수는 순수하게 유지

먼저, API 함수 자체에서 Zustand 상태 관리 훅을 직접 사용하지 않고, 순수하게 routeData와 userData를 인자로 받아 처리하도록 수정합니다.

import axios from 'axios';
import { RouteData } from '@/types/routeData';

axios.defaults.withCredentials = true;

export const route = async (routeData: RouteData, userData: any): Promise<string> => {
  try {
    // 이 부분의 코드 삭제 const userData = useUserStore((state) => state.user);
    const response = await axios.post(`${process.env.NEXT_PUBLIC_API_BASE_URL}/api/map/route`, {
      routeData,
      userData,
    });
    return response.data;
  } catch (error: any) {
    console.error(error.message);
    throw error;
  }
};

• 이 함수는 클라이언트 상태를 직접 다루지 않고, 상태가 함수 외부에서 주어지면 그 상태를 기반으로 API 요청을 보냅니다.
• 이 방식으로 서버와 클라이언트 간의 상태 관리 문제를 해결할 수 있습니다.

2. 클라이언트에서 Zustand 상태를 사용하여 API 호출

이제 클라이언트 사이드에서 Zustand 상태를 안전하게 가져와 API 함수에 전달하는 방식으로 코드를 수정할 수 있습니다. 버튼 클릭과 같은 사용자의 명시적인 동작이 있을 때 상태를 읽어와 API에 전달하는 것이 가장 좋은 방법입니다.

"use client";

import { useState } from 'react';
import useUserStore from '@/store/useUserStore';
import { route } from '@/api/user';
import { RouteData } from '@/types/routeData';

const MyComponent = ({ routeData }: { routeData: RouteData }) => {
  const userData = useUserStore((state) => state.user); // 클라이언트 사이드에서 상태 접근
  const [apiResponse, setApiResponse] = useState<string | null>(null);

  const handleFindRoute = async () => {
    if (!userData) {
      console.error('User data is missing!');
      return;
    }

    try {
      const response = await route(routeData, userData); // API에 상태를 전달
      setApiResponse(response);
    } catch (error) {
      console.error('Error fetching route:', error);
    }
  };

  return (
    <div>
      <button onClick={handleFindRoute}>Find Route</button>
      {apiResponse && <p>API Response: {apiResponse}</p>}
    </div>
  );
};

 

• useUserStore를 통해 클라이언트 사이드에서만 상태를 가져옵니다.
• handleFindRoute는 버튼 클릭 시 상태를 읽고, 이를 API로 전달하는 역할을 합니다.
• 이 방식은 상태 관리와 API 호출을 명확하게 분리하면서, 서버 사이드에서 발생할 수 있는 오류를 방지할 수 있습니다.

 

■ 결론: Next.js에서 클라이언트 상태를 안전하게 처리하기

Next.js는 클라이언트와 서버에서 모두 실행되기 때문에, 클라이언트 전용 상태 관리 도구인 Zustand와 같은 훅을 서버에서 직접 호출하려 할 때 오류가 발생합니다. 이 문제를 해결하기 위해서는:

1. API 함수는 상태와 무관하게 순수한 비동기 함수로 유지하고,
2. 클라이언트에서만 상태를 관리하여 API에 전달하는 방식으로 코드를 작성해야 합니다.

이 방식을 사용하면, Next.js의 서버 사이드와 클라이언트 사이드의 차이점을 안전하게 처리할 수 있으며, 클라이언트 전용 상태를 올바르게 API로 전달할 수 있습니다.