sh-ui-cli 0.24.0 → 0.25.0

package/data/changelog/versions.json

@@ -2,6 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.25.0",
+      "date": "2026-04-28",
+      "title": "Next.js 템플릿에 http 골격 + BFF proxy 추가 — IS_SERVER 분기 제거",
+      "type": "minor",
+      "highlights": [
+        "nextjs-app · nextjs-standalone 템플릿에 axios 단일 인스턴스(src/shared/api/http.ts)와 BFF 라우트 핸들러(app/api/proxy/[...path]/route.ts) 추가 — 클라/서버 모두 /api/proxy 경유, IS_SERVER 분기 없음",
+        "인증 · 토큰 refresh · Sentry · 로그인 쿠키 특례 처리는 의도적으로 제외해 인증 비종속 골격으로 유지 — 프로젝트별 추가는 apps/docs/recipes 가이드로 분리",
+        "레시피 9종 추가 (apps/docs/app/recipes/): api-layer, auth, file-upload, tanstack-query, async-boundary, i18n, sentry, testing, deployment",
+        "사이드바에 '레시피' 진입점 추가"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.25.0"
+    },
     {
       "version": "0.24.0",
       "date": "2026-04-28",

package/package.json

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

package/templates/monorepo/README.md

@@ -77,7 +77,7 @@ pnpm dev          # 모든 앱 동시 실행
 ## 앱 추가
 
 ```bash
-npx sh-ui-create add-app
+npx sh-ui-cli create add-app
 ```
 
 `apps/{name}/` 과 `packages/ui/ui-apps/ui-{name}/` 을 함께 생성합니다.
@@ -93,10 +93,10 @@ pnpm --filter admin build
 
 ```bash
 # 모든 ui 패키지에 추가 (대화형)
-npx sh-ui-create add-component button
+npx sh-ui-cli create add-component button
 
 # 특정 앱에만 추가
-npx sh-ui-create add-component button --app web
+npx sh-ui-cli create add-component button --app web
 ```
 
 내부적으로 `packages/ui/ui-apps/ui-{app}/` 디렉토리에서 `npx sh-ui add button` 이 실행되며,

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

@@ -0,0 +1,85 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+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 url = new URL(`${API_URL}/${path.join('/')}`);
+
+  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();
+    }
+  }
+
+  try {
+    const response = await fetch(url.toString(), { method, headers, body });
+    const data = await response.json();
+    return NextResponse.json(data, { status: response.status });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+};
+
+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-app/src/shared/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-app/src/shared/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-app/src/shared/api/http.ts

@@ -0,0 +1,56 @@
+import axios from 'axios';
+
+import { ApiError } from './error';
+import type { ApiResponse } from './apiTypes';
+
+const HTTP_TIMEOUT = 10_000;
+
+const http = axios.create({
+  baseURL: '/api/proxy',
+  timeout: HTTP_TIMEOUT,
+});
+
+// 서버 컴포넌트에서 호출 시 axios 는 절대 URL 이 필요하다.
+// 호스트만 프리픽스하고 그 외 분기는 두지 않는다.
+http.interceptors.request.use(async (config) => {
+  if (typeof window !== 'undefined') return config;
+
+  const { headers: getHeaders } = await import('next/headers');
+  const hdrs = await getHeaders();
+  const host = hdrs.get('host') ?? 'localhost:3000';
+  const protocol = process.env.NODE_ENV === 'production' ? 'https' : 'http';
+  config.baseURL = `${protocol}://${host}/api/proxy`;
+  return config;
+});
+
+http.interceptors.response.use(
+  (response) => {
+    const body = response.data as ApiResponse;
+    if (body && typeof body === 'object' && 'result' in body) {
+      if (body.result === 'ERROR') {
+        return Promise.reject(
+          new ApiError(response.status, body.error?.code ?? '', body.error),
+        );
+      }
+      response.data = body.data;
+    }
+    return response;
+  },
+  (error) => {
+    if (axios.isAxiosError(error)) {
+      const { response } = error;
+      const body = response?.data as ApiResponse | undefined;
+      const errorBody = body?.error ?? null;
+      return Promise.reject(
+        new ApiError(
+          response?.status ?? 0,
+          errorBody?.code ?? '',
+          errorBody,
+        ),
+      );
+    }
+    return Promise.reject(error);
+  },
+);
+
+export { http };

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

@@ -0,0 +1,85 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+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 url = new URL(`${API_URL}/${path.join('/')}`);
+
+  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();
+    }
+  }
+
+  try {
+    const response = await fetch(url.toString(), { method, headers, body });
+    const data = await response.json();
+    return NextResponse.json(data, { status: response.status });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+};
+
+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/src/shared/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/src/shared/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/src/shared/api/http.ts

@@ -0,0 +1,56 @@
+import axios from 'axios';
+
+import { ApiError } from './error';
+import type { ApiResponse } from './apiTypes';
+
+const HTTP_TIMEOUT = 10_000;
+
+const http = axios.create({
+  baseURL: '/api/proxy',
+  timeout: HTTP_TIMEOUT,
+});
+
+// 서버 컴포넌트에서 호출 시 axios 는 절대 URL 이 필요하다.
+// 호스트만 프리픽스하고 그 외 분기는 두지 않는다.
+http.interceptors.request.use(async (config) => {
+  if (typeof window !== 'undefined') return config;
+
+  const { headers: getHeaders } = await import('next/headers');
+  const hdrs = await getHeaders();
+  const host = hdrs.get('host') ?? 'localhost:3000';
+  const protocol = process.env.NODE_ENV === 'production' ? 'https' : 'http';
+  config.baseURL = `${protocol}://${host}/api/proxy`;
+  return config;
+});
+
+http.interceptors.response.use(
+  (response) => {
+    const body = response.data as ApiResponse;
+    if (body && typeof body === 'object' && 'result' in body) {
+      if (body.result === 'ERROR') {
+        return Promise.reject(
+          new ApiError(response.status, body.error?.code ?? '', body.error),
+        );
+      }
+      response.data = body.data;
+    }
+    return response;
+  },
+  (error) => {
+    if (axios.isAxiosError(error)) {
+      const { response } = error;
+      const body = response?.data as ApiResponse | undefined;
+      const errorBody = body?.error ?? null;
+      return Promise.reject(
+        new ApiError(
+          response?.status ?? 0,
+          errorBody?.code ?? '',
+          errorBody,
+        ),
+      );
+    }
+    return Promise.reject(error);
+  },
+);
+
+export { http };