sh-ui-cli 0.56.4 → 0.58.0

package/templates/nextjs-standalone/_arch/flat/app/api/proxy/[...path]/route.ts

@@ -0,0 +1,112 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+import {
+  captureApiError,
+  logApiError,
+} from '@/lib/api/observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+const proxyRequest = async (
+  request: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+  method: string,
+) => {
+  const { path } = await ctx.params;
+  const apiPath = path.join('/');
+  const url = new URL(`${API_URL}/${apiPath}`);
+
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale =
+    cookieStore.get(LOCALE_COOKIE)?.value ??
+    request.headers.get('Accept-Language') ??
+    undefined;
+
+  const headers: Record<string, string> = {};
+  if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (locale) headers['Accept-Language'] = locale;
+
+  let body: BodyInit | undefined;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const contentType = request.headers.get('Content-Type');
+    if (contentType?.includes('multipart/form-data')) {
+      body = await request.formData();
+    } else {
+      headers['Content-Type'] = 'application/json';
+      body = await request.text();
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method, headers, body });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    logApiError('PROXY', {
+      url: url.toString(),
+      method,
+      status: response.status,
+      requestBody: typeof body === 'string' ? body : undefined,
+      responseBody: data,
+    });
+
+    captureApiError({
+      url: url.toString(),
+      apiPath,
+      method,
+      status: response.status,
+      responseBody: data,
+    });
+  }
+
+  return NextResponse.json(data, { status: response.status });
+};
+
+export const GET = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'GET');
+
+export const POST = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'POST');
+
+export const PUT = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PUT');
+
+export const PATCH = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PATCH');
+
+export const DELETE = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'DELETE');

package/templates/nextjs-standalone/_arch/flat/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import { RootLayout } from '@/components/layouts/RootLayout';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'My App',
+  description: 'My App Description',
+};
+
+export default function Layout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return <RootLayout>{children}</RootLayout>;
+}

package/templates/nextjs-standalone/_arch/flat/components/common/FallbackBoundary/index.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  Component,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  Suspense,
+} from 'react';
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+
+export type ErrorFallbackProps = {
+  error: Error | null;
+  resetErrorBoundary: () => void;
+};
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<ErrorFallbackProps>;
+  onReset: () => void;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+  }
+
+  resetErrorBoundary = () => {
+    this.props.onReset();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback: Fallback } = this.props;
+
+    if (hasError && Fallback) {
+      return (
+        <Fallback error={error} resetErrorBoundary={this.resetErrorBoundary} />
+      );
+    }
+
+    return children;
+  }
+}
+
+type FallbackBoundaryProps = {
+  children: ReactNode;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  suspenseFallback?: ReactNode;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+/**
+ * Suspense + ErrorBoundary 합성. React Query 의 reset 신호에 맞춰
+ * `errorFallback` 의 `resetErrorBoundary` 가 쿼리까지 함께 리셋한다.
+ */
+export function FallbackBoundary({
+  children,
+  errorFallback,
+  suspenseFallback,
+  onError,
+}: FallbackBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallback={errorFallback}
+          onError={onError}
+        >
+          <Suspense fallback={suspenseFallback}>{children}</Suspense>
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/common/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/lib/utils/getQueryClient';
+
+export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
+
+type Props = {
+  fetchOptions?: FetchOptions[] | FetchOptions | null;
+  children: ReactNode;
+};
+
+/**
+ * RSC 에서 prefetch 를 끝낸 뒤 dehydrated state 로 클라이언트에 hydrate.
+ * 단일/배열 둘 다 받는다.
+ */
+export async function PrefetchBoundary({ fetchOptions, children }: Props) {
+  const queryClient = getQueryClient();
+
+  if (fetchOptions) {
+    const list = Array.isArray(fetchOptions) ? fetchOptions : [fetchOptions];
+    await Promise.all(list.map((opt) => queryClient.prefetchQuery(opt)));
+  }
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/layouts/RootLayout.tsx

@@ -0,0 +1,11 @@
+import { GlobalProvider } from '@/components/providers';
+
+export function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang='ko' suppressHydrationWarning>
+      <body>
+        <GlobalProvider>{children}</GlobalProvider>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/providers/GlobalProvider/index.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { Toaster } from 'sonner';
+
+import { QueryClientProvider } from '../tanstack/QueryClientProvider';
+import { TanstackDevtoolsProvider } from '../tanstack/TanstackDevtoolsProvider';
+import { ThemeProviders } from '../theme/ThemeProviders';
+
+interface GlobalProviderProps {
+  children: ReactNode;
+}
+
+export function GlobalProvider({ children }: GlobalProviderProps) {
+  return (
+    <ThemeProviders>
+      <QueryClientProvider>
+        <TanstackDevtoolsProvider>
+          <Toaster />
+          {children}
+        </TanstackDevtoolsProvider>
+      </QueryClientProvider>
+    </ThemeProviders>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/providers/index.tsx

@@ -0,0 +1 @@
+export { GlobalProvider } from './GlobalProvider';

package/templates/nextjs-standalone/_arch/flat/components/providers/tanstack/QueryClientProvider.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import { getBrowserQueryClient } from '@/lib/api/queryClient';
+
+export function QueryClientProvider({ children }: { children: ReactNode }) {
+  return (
+    <TanstackQueryClientProvider client={getBrowserQueryClient()}>
+      {children}
+    </TanstackQueryClientProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/providers/tanstack/TanstackDevtoolsProvider.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import type { ReactNode } from 'react';
+
+export function TanstackDevtoolsProvider({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/components/providers/theme/ThemeProviders.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import { ThemeProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+export function ThemeProviders({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider attribute='class' defaultTheme='system' enableSystem>
+      {children}
+    </ThemeProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/flat/lib/api/apiTypes.ts

@@ -0,0 +1,21 @@
+/** 공통 API 에러 형식 */
+export type ApiErrorBody = {
+  message: string;
+  code: string;
+};
+
+/** 백엔드 공통 응답 래퍼 */
+export type ApiResponse<TData = unknown, TError = ApiErrorBody> = {
+  result: 'SUCCESS' | 'ERROR';
+  data: TData;
+  error: TError | null;
+};
+
+/** 페이지네이션 응답 래퍼 */
+export type PaginatedData<T> = {
+  content: T[];
+  totalItems: number;
+  offset: number;
+  limit: number;
+  hasNext: boolean;
+};

package/templates/nextjs-standalone/_arch/flat/lib/api/clientFetch.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import type { ApiResponse } from './apiTypes';
+import { ApiError } from './error';
+
+const PROXY_BASE = '/api/proxy';
+
+export async function clientFetch<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const url = `${PROXY_BASE}${path.startsWith('/') ? path : `/${path}`}`;
+
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(init.headers as Record<string, string> | undefined),
+    },
+    credentials: 'include',
+  });
+
+  const body = (await res.json()) as ApiResponse<T>;
+
+  if (res.status === 401) {
+    if (
+      typeof window !== 'undefined' &&
+      !window.location.pathname.startsWith('/sign-in')
+    ) {
+      window.location.href = '/sign-in';
+    }
+    throw new ApiError(401, body.error?.code ?? 'UNAUTHORIZED', body.error);
+  }
+
+  if (!res.ok || body.result === 'ERROR') {
+    throw new ApiError(res.status, body.error?.code ?? '', body.error);
+  }
+
+  return body.data;
+}

package/templates/nextjs-standalone/_arch/flat/lib/api/error.ts

@@ -0,0 +1,12 @@
+import type { ApiErrorBody } from './apiTypes';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    public readonly data: ApiErrorBody | null,
+  ) {
+    super(data?.message ?? `API 요청 실패 (${status})`);
+    this.name = 'ApiError';
+  }
+}

package/templates/nextjs-standalone/_arch/flat/lib/api/http.ts

@@ -0,0 +1,13 @@
+import { clientFetch } from './clientFetch';
+import { serverFetch } from './serverFetch';
+
+/**
+ * isomorphic 진입점.
+ * RSC/서버에서는 백엔드로 직통, 브라우저에서는 /api/proxy 경유.
+ * API 함수는 한 번만 작성하고 환경 분기는 여기서 처리한다.
+ */
+export function http<T>(path: string, init?: RequestInit): Promise<T> {
+  return typeof window === 'undefined'
+    ? serverFetch<T>(path, init)
+    : clientFetch<T>(path, init);
+}

package/templates/nextjs-standalone/_arch/flat/lib/api/observability.ts

@@ -0,0 +1,20 @@
+type ApiCaptureParams = {
+  url: string;
+  apiPath: string;
+  method: string;
+  status: number | undefined;
+  responseBody?: unknown;
+};
+
+type ApiLogParams = {
+  url: string;
+  method: string;
+  status: number | undefined;
+  requestHeaders?: Record<string, string | undefined>;
+  requestBody?: unknown;
+  responseBody?: unknown;
+};
+
+export const captureApiError = (_params: ApiCaptureParams): void => {};
+
+export const logApiError = (_prefix: string, _params: ApiLogParams): void => {};

package/templates/nextjs-standalone/_arch/flat/lib/api/queryClient.ts

@@ -0,0 +1,30 @@
+import {
+  QueryClient,
+  defaultShouldDehydrateQuery,
+  isServer,
+} from '@tanstack/react-query';
+import { cache } from 'react';
+
+function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        retry: 1,
+      },
+      dehydrate: {
+        shouldDehydrateQuery: (q) =>
+          defaultShouldDehydrateQuery(q) || q.state.status === 'pending',
+      },
+    },
+  });
+}
+
+export const getServerQueryClient = cache(makeQueryClient);
+
+let browserQueryClient: QueryClient | undefined;
+
+export function getBrowserQueryClient(): QueryClient {
+  if (isServer) return makeQueryClient();
+  return (browserQueryClient ??= makeQueryClient());
+}

package/templates/nextjs-standalone/_arch/flat/lib/api/serverFetch.ts

@@ -0,0 +1,59 @@
+import { cookies } from 'next/headers';
+
+import type { ApiResponse } from './apiTypes';
+import { ApiError } from './error';
+import { captureApiError, logApiError } from './observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+export async function serverFetch<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const jar = await cookies();
+  const accessToken = jar.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale = jar.get(LOCALE_COOKIE)?.value;
+
+  const url = `${API_URL}${path.startsWith('/') ? path : `/${path}`}`;
+  const method = (init.method ?? 'GET').toUpperCase();
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...(accessToken && { Authorization: `Bearer ${accessToken}` }),
+    ...(locale && { 'Accept-Language': locale }),
+    ...(init.headers as Record<string, string> | undefined),
+  };
+
+  const res = await fetch(url, {
+    ...init,
+    headers,
+    cache: init.cache ?? 'no-store',
+  });
+
+  const body = (await res.json()) as ApiResponse<T>;
+
+  if (!res.ok || body.result === 'ERROR') {
+    logApiError('SERVER_FETCH', {
+      url,
+      method,
+      status: res.status,
+      requestBody: typeof init.body === 'string' ? init.body : undefined,
+      responseBody: body,
+    });
+
+    captureApiError({
+      url,
+      apiPath: path,
+      method,
+      status: res.status,
+      responseBody: body,
+    });
+
+    throw new ApiError(res.status, body.error?.code ?? '', body.error);
+  }
+
+  return body.data;
+}

package/templates/nextjs-standalone/_arch/flat/lib/hooks/useAppMutation.ts

@@ -0,0 +1,52 @@
+import {
+  useMutation,
+  type UseMutationOptions,
+  type DefaultError,
+} from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { ApiError } from '../api/error';
+
+type AppMutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+> = UseMutationOptions<TData, TError, TVariables, TContext> & {
+  errorMessage?: string;
+  showErrorToast?: boolean;
+};
+
+/**
+ * useMutation 래퍼 — 에러 발생 시 ApiError.message 를 toast 로 띄운다.
+ * showErrorToast: false 로 끌 수 있고, errorMessage 로 fallback 메시지 지정.
+ */
+export const useAppMutation = <
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+>(
+  options: AppMutationOptions<TData, TError, TVariables, TContext>,
+) => {
+  const { errorMessage, showErrorToast = true, onError, ...rest } = options;
+
+  return useMutation({
+    ...rest,
+    onError: (...args) => {
+      onError?.(...args);
+
+      if (!showErrorToast) return;
+
+      const [error] = args;
+      const message =
+        error instanceof ApiError
+          ? (error.data?.message ?? errorMessage)
+          : errorMessage;
+
+      if (message) {
+        toast.error(message);
+      }
+    },
+  });
+};

package/templates/nextjs-standalone/_arch/flat/lib/test/createTestQueryClient.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 테스트 전용 QueryClient — retry/refetch 끄고 gcTime 0 으로 격리.
+ */
+export const createTestQueryClient = (): QueryClient =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        refetchOnWindowFocus: false,
+        gcTime: 0,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });

package/templates/nextjs-standalone/_arch/flat/lib/test/index.ts

@@ -0,0 +1,2 @@
+export { createTestQueryClient } from './createTestQueryClient';
+export { renderWithProviders } from './renderWithProviders';

package/templates/nextjs-standalone/_arch/flat/lib/test/renderWithProviders.tsx

@@ -0,0 +1,40 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import {
+  render,
+  type RenderOptions,
+  type RenderResult,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { createTestQueryClient } from './createTestQueryClient';
+
+type Options = Omit<RenderOptions, 'wrapper'> & {
+  queryClient?: QueryClient;
+};
+
+type Result = RenderResult & {
+  user: ReturnType<typeof userEvent.setup>;
+  queryClient: QueryClient;
+};
+
+/**
+ * RTL render + QueryClientProvider + userEvent setup 한 번에.
+ * 추가 Provider 가 필요하면 이 파일을 직접 수정하거나 wrapper 옵션을 쓴다.
+ */
+export const renderWithProviders = (
+  ui: ReactElement,
+  options: Options = {},
+): Result => {
+  const { queryClient = createTestQueryClient(), ...rtlOptions } = options;
+
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const result = render(ui, { wrapper: Wrapper, ...rtlOptions });
+  const user = userEvent.setup();
+
+  return { ...result, user, queryClient };
+};

package/templates/nextjs-standalone/_arch/flat/lib/utils/formatDate.ts

@@ -0,0 +1,22 @@
+/**
+ * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ */
+export const formatDate = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date);
+
+/**
+ * Date → 로케일 기반 날짜 + 시간 포맷 (24h).
+ */
+export const formatDateTime = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);