sh-ui-cli 0.33.0 → 0.34.0

package/data/changelog/versions.json

@@ -2,6 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.34.0",
+      "date": "2026-04-29",
+      "title": "Next 템플릿 — RSC prefetch / 에러 바운더리 / 테스트 헬퍼 + KRW·날짜 포맷 유틸 기본 탑재",
+      "type": "minor",
+      "highlights": [
+        "shared/ui/PrefetchBoundary + shared/lib/getQueryClient — RSC 에서 prefetch 후 dehydrate → 클라이언트 hydrate. 단일/배열 fetchOptions 모두 지원, 이미 깔린 TanStack Query 인프라와 즉시 호환",
+        "shared/ui/FallbackBoundary — Suspense + ErrorBoundary 합성, QueryErrorResetBoundary 와 연동돼 errorFallback 의 resetErrorBoundary 가 쿼리까지 함께 리셋. onError 콜백으로 외부 옵저버빌리티 (Sentry 등) 훅인 자유",
+        "shared/test/renderWithProviders + createTestQueryClient — RTL render + QueryClientProvider + userEvent 한 번에. 기존 vitest 인프라에 컴포넌트 테스트 진입장벽 제거",
+        "shared/lib/formatDate / formatPrice — 로케일 기반 Intl 포맷 유틸. formatPrice 는 한국 원화(KRW, 소수점 없음) 기본",
+        "@testing-library/react + user-event devDeps 추가 (양쪽 nextjs 템플릿)"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.34.0"
+    },
     {
       "version": "0.33.0",
       "date": "2026-04-29",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/templates/nextjs-app/package.json

@@ -30,6 +30,8 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-query-devtools": "^5.91.3",
     "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14",
     "@types/node": "^25.1.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",

package/templates/nextjs-app/src/shared/lib/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);

package/templates/nextjs-app/src/shared/lib/formatPrice.ts

@@ -0,0 +1,10 @@
+/**
+ * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
+ * 예: 12000 → "₩12,000"
+ */
+export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: 'KRW',
+    maximumFractionDigits: 0,
+  }).format(amount);

package/templates/nextjs-app/src/shared/lib/getQueryClient.ts

@@ -0,0 +1,14 @@
+import { isServer } from '@tanstack/react-query';
+
+import {
+  getBrowserQueryClient,
+  getServerQueryClient,
+} from '@/src/shared/api/queryClient';
+
+/**
+ * RSC 와 클라이언트 양쪽에서 안전하게 호출 가능한 QueryClient 핸들.
+ * 서버에서는 React `cache()` 로 요청 단위 싱글턴, 브라우저에서는 모듈 싱글턴.
+ */
+export default function getQueryClient() {
+  return isServer ? getServerQueryClient() : getBrowserQueryClient();
+}

package/templates/nextjs-app/src/shared/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-app/src/shared/test/index.ts

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

package/templates/nextjs-app/src/shared/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-app/src/shared/ui/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-app/src/shared/ui/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/src/shared/lib/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/package.json

@@ -35,6 +35,8 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-query-devtools": "^5.91.3",
     "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14",
     "@types/node": "^25.1.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",

package/templates/nextjs-standalone/src/shared/lib/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);

package/templates/nextjs-standalone/src/shared/lib/formatPrice.ts

@@ -0,0 +1,10 @@
+/**
+ * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
+ * 예: 12000 → "₩12,000"
+ */
+export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: 'KRW',
+    maximumFractionDigits: 0,
+  }).format(amount);

package/templates/nextjs-standalone/src/shared/lib/getQueryClient.ts

@@ -0,0 +1,14 @@
+import { isServer } from '@tanstack/react-query';
+
+import {
+  getBrowserQueryClient,
+  getServerQueryClient,
+} from '@/src/shared/api/queryClient';
+
+/**
+ * RSC 와 클라이언트 양쪽에서 안전하게 호출 가능한 QueryClient 핸들.
+ * 서버에서는 React `cache()` 로 요청 단위 싱글턴, 브라우저에서는 모듈 싱글턴.
+ */
+export default function getQueryClient() {
+  return isServer ? getServerQueryClient() : getBrowserQueryClient();
+}

package/templates/nextjs-standalone/src/shared/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/src/shared/test/index.ts

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

package/templates/nextjs-standalone/src/shared/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/src/shared/ui/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/src/shared/ui/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/src/shared/lib/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>
+  );
+}