Next.js App Router 상태 관리 — 네 가지 경계와 값의 수명

// shared/lib/query-client.ts
export const queryClient = new QueryClient({ /* ... */ });

// 모듈 스코프 캐시
const seen = new Set<string>();

// 모듈 스코프 Zustand 스토어
export const useModalStore = create<ModalState>()(/* ... */);

// 모듈 스코프 class instance
export const cartStore = new CartStore();

// shared/lib/index.ts
import { queryClient } from './react-query/query-client';
export { queryClient };
export { useToast } from './use-toast';

// app/get-query-client.ts
import { QueryClient } from '@tanstack/react-query';
import { cache } from 'react';

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // 하이드레이션 직후 즉시 refetch 방지
        staleTime: 60 * 1000,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

export const getQueryClient = cache(() => {
  if (typeof window === 'undefined') {
    return makeQueryClient(); // 서버: 요청마다 새로
  }
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient; // 브라우저: 탭당 하나
});

// stores/counter-store.ts
import { createStore } from 'zustand/vanilla';

export type CounterStore = { count: number; increment: () => void };

export const createCounterStore = (initState = { count: 0 }) =>
  createStore<CounterStore>()((set) => ({
    ...initState,
    increment: () => set((s) => ({ count: s.count + 1 })),
  }));

// providers/counter-store-provider.tsx
'use client';

import { createContext, useContext, useRef, type ReactNode } from 'react';
import { useStore } from 'zustand';
import { createCounterStore, type CounterStore } from '@/stores/counter-store';

type StoreApi = ReturnType<typeof createCounterStore>;
const StoreContext = createContext<StoreApi | null>(null);

export function CounterStoreProvider({ children }: { children: ReactNode }) {
  const storeRef = useRef<StoreApi | null>(null);
  if (storeRef.current === null) {
    storeRef.current = createCounterStore(); // 마운트당 1회
  }

  return <StoreContext value={storeRef.current}>{children}</StoreContext>;
}

export function useCounterStore<T>(selector: (s: CounterStore) => T): T {
  const store = useContext(StoreContext);
  if (!store) throw new Error('CounterStoreProvider 밖에서 호출됨');
  return useStore(store, selector); // selector로 구독 범위 제한
}

// Server Component
const cart = await loadCart(userId); // CartAggregate 인스턴스

// 불가
<CartView cart={cart} />

// 가능 — 스냅샷으로 낮춰서 전달
<CartView snapshot={cart.toJSON()} />

// Client Component — 인스턴스 재구성
function CartView({ snapshot }: { snapshot: CartSnapshot }) {
  const storeRef = useRef<CartStore | null>(null);
  if (storeRef.current === null) storeRef.current = new CartStore(snapshot);
  // ...
}

// Modal은 Client Component, Cart는 서버 렌더 결과로 삽입
<Modal>
  <Cart />
</Modal>

function Theme() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (!mounted) return null;
  return <span>{localStorage.getItem('theme')}</span>;
}

const snapshot = useSyncExternalStore(
  subscribe,         // (onStoreChange) => unsubscribe
  getSnapshot,       // 클라이언트 값
  getServerSnapshot, // SSR + 하이드레이션 전용 (선택)
);

const emptySubscribe = () => () => {};

function useTheme() {
  return useSyncExternalStore(
    emptySubscribe,
    () => localStorage.getItem('theme') ?? 'light', // client
    () => 'light',                                  // server
  );
}

class Store {
  private items: Item[] = [];
  private listeners = new Set<() => void>();

  subscribe = (fn: () => void) => {
    this.listeners.add(fn);
    return () => { this.listeners.delete(fn); };
  };

  // 저장된 참조 그대로 반환
  getSnapshot = () => this.items;

  // 금지 — 무한 루프
  // getSnapshot = () => [...this.items];

  add(item: Item) {
    this.items = [...this.items, item]; // 새 참조로 교체
    this.listeners.forEach((l) => l()); // 구독자 통보
  }
}

// next.config.js — 실험적 플래그, 프로덕션 권장 아님
module.exports = {
  experimental: {
    staleTimes: { dynamic: 30, static: 180 },
  },
};

'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  const session = await auth();
  if (!session?.user) throw new Error('Unauthorized');

  await db.post.create({ /* ... */ });

  revalidatePath('/posts');
  redirect('/posts');
}

'use client';

import { useActionState, startTransition } from 'react';
import { createPost } from '@/app/actions';

export function Button() {
  const [state, action, pending] = useActionState(createPost, null);

  return (
    <button onClick={() => startTransition(action)}>
      {pending ? '저장 중…' : '작성'}
    </button>
  );
}

'use client';

import { useSearchParams } from 'next/navigation';

export function SortControl() {
  const searchParams = useSearchParams();

  function updateSort(order: string) {
    const params = new URLSearchParams(searchParams.toString());
    params.set('sort', order);
    window.history.pushState(null, '', `?${params}`); // 서버 왕복 없음
  }

  return <button onClick={() => updateSort('asc')}>오름차순</button>;
}

// app/posts/page.tsx
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from './get-query-client';

export default async function PostsPage() {
  const queryClient = getQueryClient();
  await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: getPosts });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Posts />
    </HydrationBoundary>
  );
}

// features/notification/notification-stream.ts
type Listener = (n: RealtimeNotification) => void;

export class NotificationStream {
  private source: EventSource | null = null;
  private listeners = new Set<Listener>();
  private retryDelay = 1_000;
  private timer: ReturnType<typeof setTimeout> | null = null;
  private seen = new Set<string>(); // 인스턴스 = 세션 스코프

  connect(url: string) {
    this.disconnect();
    const es = new EventSource(url, { withCredentials: true });
    this.source = es;

    es.onopen = () => { this.retryDelay = 1_000; };

    es.onmessage = (e) => {
      const n: RealtimeNotification = JSON.parse(e.data);
      if (this.seen.has(n.id)) return; // 재전송 중복 제거
      this.seen.add(n.id);
      this.listeners.forEach((l) => l(n));
    };

    es.onerror = () => {
      es.close();
      this.source = null;
      this.timer = setTimeout(() => this.connect(url), this.retryDelay);
      this.retryDelay = Math.min(this.retryDelay * 2, 30_000); // 지수 백오프
    };
  }

  subscribe(listener: Listener) {
    this.listeners.add(listener);
    return () => { this.listeners.delete(listener); };
  }

  disconnect() {
    if (this.timer) clearTimeout(this.timer);
    this.source?.close();
    this.source = null;
  }
}

'use client';

export function NotificationStreamProvider({ children }: { children: ReactNode }) {
  const streamRef = useRef<NotificationStream | null>(null);
  if (streamRef.current === null) streamRef.current = new NotificationStream();

  const queryClient = useQueryClient();

  useEffect(() => {
    const stream = streamRef.current!;
    const unsubscribe = stream.subscribe((n) => {
      showNotificationToast(n);
      // 목록·뱃지는 서버 상태. 스토어에 복사하지 않고 캐시를 무효화한다
      void queryClient.invalidateQueries({ queryKey: queryKeys.notification._def });
    });

    stream.connect('/api/notifications/stream');
    return () => {
      unsubscribe();
      stream.disconnect();
    };
  }, [queryClient]);

  return <>{children}</>;
}