npm - @mandujs/core - Versions diffs - 0.3.4 → 0.4.1 - Mend

@mandujs/core 0.3.4 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/src/runtime/ssr.ts CHANGED Viewed

@@ -1,14 +1,132 @@
 import { renderToString } from "react-dom/server";
 import type { ReactElement } from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 export interface SSROptions {
   title?: string;
   lang?: string;
+  /** 서버에서 로드한 데이터 (클라이언트로 전달) */
+  serverData?: Record<string, unknown>;
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** 라우트 ID (island 식별용) */
+  routeId?: string;
+  /** 추가 head 태그 */
+  headTags?: string;
+  /** 추가 body 끝 태그 */
+  bodyEndTags?: string;
+  /** 개발 모드 여부 */
+  isDev?: boolean;
+  /** HMR 포트 (개발 모드에서 사용) */
+  hmrPort?: number;
+}
+/**
+ * SSR 데이터를 안전하게 직렬화
+ */
+function serializeServerData(data: Record<string, unknown>): string {
+  // XSS 방지를 위한 이스케이프
+  const json = JSON.stringify(data)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/'/g, "\\u0027");
+  return `<script id="__MANDU_DATA__" type="application/json">${json}</script>
+<script>window.__MANDU_DATA__ = JSON.parse(document.getElementById('__MANDU_DATA__').textContent);</script>`;
+}
+/**
+ * Hydration 스크립트 태그 생성
+ */
+function generateHydrationScripts(
+  routeId: string,
+  manifest: BundleManifest
+): string {
+  const scripts: string[] = [];
+  // Runtime 로드
+  if (manifest.shared.runtime) {
+    scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
+  }
+  // Vendor 로드
+  if (manifest.shared.vendor) {
+    scripts.push(`<script type="module" src="${manifest.shared.vendor}"></script>`);
+  }
+  // Island 번들 로드
+  const bundle = manifest.bundles[routeId];
+  if (bundle) {
+    // Preload (선택적)
+    scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
+    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
+  }
+  return scripts.join("\n");
+}
+/**
+ * Island 래퍼로 컨텐츠 감싸기
+ */
+export function wrapWithIsland(
+  content: string,
+  routeId: string,
+  priority: HydrationPriority = "visible"
+): string {
+  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
 }
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const { title = "Mandu App", lang = "ko" } = options;
-  const content = renderToString(element);
+  const {
+    title = "Mandu App",
+    lang = "ko",
+    serverData,
+    hydration,
+    bundleManifest,
+    routeId,
+    headTags = "",
+    bodyEndTags = "",
+    isDev = false,
+    hmrPort,
+  } = options;
+  let content = renderToString(element);
+  // Island 래퍼 적용 (hydration 필요 시)
+  const needsHydration =
+    hydration && hydration.strategy !== "none" && routeId && bundleManifest;
+  if (needsHydration) {
+    content = wrapWithIsland(content, routeId, hydration.priority);
+  }
+  // 서버 데이터 스크립트
+  let dataScript = "";
+  if (serverData && routeId) {
+    const wrappedData = {
+      [routeId]: {
+        serverData,
+        timestamp: Date.now(),
+      },
+    };
+    dataScript = serializeServerData(wrappedData);
+  }
+  // Hydration 스크립트
+  let hydrationScripts = "";
+  if (needsHydration && bundleManifest) {
+    hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
+  }
+  // HMR 스크립트 (개발 모드)
+  let hmrScript = "";
+  if (isDev && hmrPort) {
+    hmrScript = generateHMRScript(hmrPort);
+  }
   return `<!doctype html>
 <html lang="${lang}">
@@ -16,13 +134,62 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${headTags}
 </head>
 <body>
   <div id="root">${content}</div>
+  ${dataScript}
+  ${hydrationScripts}
+  ${hmrScript}
+  ${bodyEndTags}
 </body>
 </html>`;
 }
+/**
+ * HMR 스크립트 생성
+ */
+function generateHMRScript(port: number): string {
+  const hmrPort = port + 1;
+  return `<script>
+(function() {
+  var ws = null;
+  var reconnectAttempts = 0;
+  var maxReconnectAttempts = 10;
+  function connect() {
+    try {
+      ws = new WebSocket('ws://localhost:${hmrPort}');
+      ws.onopen = function() {
+        console.log('[Mandu HMR] Connected');
+        reconnectAttempts = 0;
+      };
+      ws.onmessage = function(e) {
+        try {
+          var msg = JSON.parse(e.data);
+          if (msg.type === 'reload' || msg.type === 'island-update') {
+            console.log('[Mandu HMR] Reloading...');
+            location.reload();
+          } else if (msg.type === 'error') {
+            console.error('[Mandu HMR] Build error:', msg.data?.message);
+          }
+        } catch(err) {}
+      };
+      ws.onclose = function() {
+        if (reconnectAttempts < maxReconnectAttempts) {
+          reconnectAttempts++;
+          setTimeout(connect, 1000 * reconnectAttempts);
+        }
+      };
+    } catch(err) {
+      setTimeout(connect, 1000);
+    }
+  }
+  connect();
+})();
+</script>`;
+}
 export function createHTMLResponse(html: string, status: number = 200): Response {
   return new Response(html, {
     status,
@@ -36,3 +203,33 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
   const html = renderToHTML(element, options);
   return createHTMLResponse(html);
 }
+/**
+ * Hydration이 포함된 SSR 렌더링
+ *
+ * @example
+ * ```typescript
+ * const response = await renderWithHydration(
+ *   <TodoList todos={todos} />,
+ *   {
+ *     title: "할일 목록",
+ *     routeId: "todos",
+ *     serverData: { todos },
+ *     hydration: { strategy: "island", priority: "visible" },
+ *     bundleManifest,
+ *   }
+ * );
+ * ```
+ */
+export async function renderWithHydration(
+  element: ReactElement,
+  options: SSROptions & {
+    routeId: string;
+    serverData: Record<string, unknown>;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
+): Promise<Response> {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}

package/src/spec/schema.ts CHANGED Viewed

@@ -1,16 +1,90 @@
 import { z } from "zod";
+// ========== Hydration 설정 ==========
+export const HydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
+export type HydrationStrategy = z.infer<typeof HydrationStrategy>;
+export const HydrationPriority = z.enum(["immediate", "visible", "idle", "interaction"]);
+export type HydrationPriority = z.infer<typeof HydrationPriority>;
+export const HydrationConfig = z.object({
+  /**
+   * Hydration 전략
+   * - none: 순수 Static HTML (JS 없음)
+   * - island: Slot 영역만 hydrate (기본값)
+   * - full: 전체 페이지 hydrate
+   * - progressive: 점진적 hydrate
+   */
+  strategy: HydrationStrategy,
+  /**
+   * Hydration 우선순위
+   * - immediate: 페이지 로드 즉시
+   * - visible: 뷰포트에 보일 때 (기본값)
+   * - idle: 브라우저 idle 시
+   * - interaction: 사용자 상호작용 시
+   */
+  priority: HydrationPriority.default("visible"),
+  /**
+   * 번들 preload 여부
+   */
+  preload: z.boolean().default(false),
+});
+export type HydrationConfig = z.infer<typeof HydrationConfig>;
+// ========== Loader 설정 ==========
+export const LoaderConfig = z.object({
+  /**
+   * SSR 시 데이터 로딩 타임아웃 (ms)
+   */
+  timeout: z.number().positive().default(5000),
+  /**
+   * 로딩 실패 시 fallback 데이터
+   */
+  fallback: z.record(z.unknown()).optional(),
+});
+export type LoaderConfig = z.infer<typeof LoaderConfig>;
+// ========== Route 설정 ==========
 export const RouteKind = z.enum(["page", "api"]);
 export type RouteKind = z.infer<typeof RouteKind>;
+export const HttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+export type HttpMethod = z.infer<typeof HttpMethod>;
 export const RouteSpec = z
   .object({
     id: z.string().min(1, "id는 필수입니다"),
     pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
     kind: RouteKind,
+    // HTTP 메서드 (API용)
+    methods: z.array(HttpMethod).optional(),
+    // 서버 모듈 (generated route handler)
     module: z.string().min(1, "module 경로는 필수입니다"),
+    // 페이지 컴포넌트 모듈 (generated)
     componentModule: z.string().optional(),
+    // 서버 슬롯 (비즈니스 로직)
     slotModule: z.string().optional(),
+    // 클라이언트 슬롯 (interactive 로직) [NEW]
+    clientModule: z.string().optional(),
+    // Hydration 설정 [NEW]
+    hydration: HydrationConfig.optional(),
+    // Loader 설정 [NEW]
+    loader: LoaderConfig.optional(),
   })
   .refine(
     (route) => {
@@ -23,10 +97,25 @@ export const RouteSpec = z
       message: "kind가 'page'인 경우 componentModule은 필수입니다",
       path: ["componentModule"],
     }
+  )
+  .refine(
+    (route) => {
+      // clientModule이 있으면 hydration.strategy가 none이 아니어야 함
+      if (route.clientModule && route.hydration?.strategy === "none") {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: "clientModule이 있으면 hydration.strategy는 'none'이 아니어야 합니다",
+      path: ["hydration"],
+    }
   );
 export type RouteSpec = z.infer<typeof RouteSpec>;
+// ========== Manifest ==========
 export const RoutesManifest = z
   .object({
     version: z.number().int().positive(),
@@ -56,3 +145,46 @@ export const RoutesManifest = z
   );
 export type RoutesManifest = z.infer<typeof RoutesManifest>;
+// ========== 유틸리티 함수 ==========
+/**
+ * 기본 hydration 설정 반환
+ */
+export function getDefaultHydration(route: RouteSpec): HydrationConfig {
+  // clientModule이 있으면 island, 없으면 none
+  if (route.clientModule) {
+    return {
+      strategy: "island",
+      priority: "visible",
+      preload: false,
+    };
+  }
+  return {
+    strategy: "none",
+    priority: "visible",
+    preload: false,
+  };
+}
+/**
+ * 라우트의 실제 hydration 설정 반환 (기본값 적용)
+ */
+export function getRouteHydration(route: RouteSpec): HydrationConfig {
+  if (route.hydration) {
+    return {
+      strategy: route.hydration.strategy,
+      priority: route.hydration.priority ?? "visible",
+      preload: route.hydration.preload ?? false,
+    };
+  }
+  return getDefaultHydration(route);
+}
+/**
+ * Hydration이 필요한 라우트인지 확인
+ */
+export function needsHydration(route: RouteSpec): boolean {
+  const hydration = getRouteHydration(route);
+  return route.kind === "page" && hydration.strategy !== "none";
+}