@simplysm/sd-cli 14.0.95 → 14.0.97

package/src/esbuild/esbuild-ssr-config.ts

@@ -0,0 +1,149 @@
+import path from "path";
+import esbuild from "esbuild";
+import { AngularSourceFileCache } from "../angular/angular-compiler.js";
+import { createClientTransformStylesheet } from "../angular/client-transform-stylesheet.js";
+import {
+  createAngularCompilerPlugin,
+  type AngularCompilerPluginOptions,
+} from "./esbuild-angular-compiler-plugin.js";
+import { MemoryLoadResultCache } from "./load-result-cache.js";
+import { createScssPlugin } from "./esbuild-scss-plugin";
+import { createPostcssPlugin, loadPostcssPlugins } from "./esbuild-postcss-plugin";
+
+export interface BuildSsrBundleOptions {
+  /** 패키지 디렉토리 경로 */
+  pkgDir: string;
+  /** 모노레포 루트 (workspaceRoot) */
+  cwd: string;
+  /** tsconfig 경로 (기본: pkgDir/tsconfig.json) */
+  tsconfig?: string;
+  /** 빌드 시 치환할 환경변수 */
+  env?: Record<string, string>;
+  /** PostCSS 플러그인 ([name, options] 튜플 배열) */
+  postcssPlugins?: [string, (object | string)?][];
+  /** 번들 출력 디렉토리 (기본: pkgDir/.angular/ssg) */
+  outdir?: string;
+}
+
+export interface SsrBundleResult {
+  /** 생성된 server 번들 파일 경로 */
+  bundlePath: string;
+}
+
+class SsrSourceFileCache extends AngularSourceFileCache {
+  readonly typeScriptFileCache = new Map<string, string | Uint8Array>();
+  readonly loadResultCache = new MemoryLoadResultCache();
+}
+
+/**
+ * SSG 프리렌더용 server 번들을 빌드한다.
+ *
+ * - 진입점: 가상 래퍼 — src/main.server.ts(부트스트랩 default export)를
+ *   @angular/platform-server의 renderApplication으로 감싸 render(url, document)를 export
+ * - platform: node, format: esm (server 패키지 빌드 패턴과 동일)
+ */
+export async function buildSsrBundle(options: BuildSsrBundleOptions): Promise<SsrBundleResult> {
+  const outdir = options.outdir ?? path.join(options.pkgDir, ".angular", "ssg");
+  const bundlePath = path.join(outdir, "sd-ssg-entry.mjs");
+
+  // SourceFileCache 생성 (일회성 빌드 — 증분 캐시 불필요)
+  const sourceFileCache = new SsrSourceFileCache();
+
+  // SCSS 스타일시트 변환용 공유 상태
+  const stylesheetDependencies = new Map<string, Set<string>>();
+  const stylesheetErrors: string[] = [];
+
+  // PostCSS 플러그인 로딩 (튜플 → 인스턴스)
+  const loadedPostcssPlugins = loadPostcssPlugins(options.pkgDir, options.postcssPlugins);
+
+  const cachePath = path.join(options.pkgDir, ".angular", "cache");
+  const transformStylesheet = createClientTransformStylesheet({
+    loadPaths: [
+      path.join(options.pkgDir, "node_modules"),
+      path.join(options.cwd, "node_modules"),
+    ],
+    postcssPlugins: loadedPostcssPlugins,
+    scssErrors: stylesheetErrors,
+    scssDependencies: stylesheetDependencies,
+    cacheDir: path.join(cachePath, "scss"),
+  });
+
+  const pluginOptions: AngularCompilerPluginOptions = {
+    tsconfig: options.tsconfig ?? path.join(options.pkgDir, "tsconfig.json"),
+    sourcemap: false,
+    advancedOptimizations: true,
+    thirdPartySourcemaps: false,
+    incremental: false,
+    sourceFileCache,
+    typeScriptFileCache: sourceFileCache.typeScriptFileCache,
+    loadResultCache: sourceFileCache.loadResultCache,
+    includeTestMetadata: false,
+    persistentCachePath: cachePath,
+    transformStylesheet,
+    stylesheetDependencies,
+    stylesheetErrors,
+  };
+
+  const angularPlugin = createAngularCompilerPlugin(pluginOptions);
+
+  const scssPlugin = createScssPlugin({
+    loadPaths: [
+      path.join(options.pkgDir, "node_modules"),
+      path.join(options.cwd, "node_modules"),
+    ],
+  });
+
+  // define 주입 (client 빌드 패턴 + 서버 렌더 플래그)
+  const define: Record<string, string> = {
+    ngDevMode: "false",
+    ngJitMode: "false",
+    ngHmrMode: "false",
+    ngServerMode: "true",
+  };
+  if (options.env != null) {
+    define["import.meta.env"] = JSON.stringify(options.env);
+  }
+
+  // CJS 패키지 require() 지원 banner (server 패키지 빌드 패턴과 동일)
+  const bannerJs =
+    "import { createRequire } from 'module'; const require = createRequire(import.meta.url);";
+
+  await esbuild.build({
+    stdin: {
+      contents: [
+        'import bootstrap from "./src/main.server";',
+        'import { renderApplication } from "@angular/platform-server";',
+        "export function render(url: string, document: string): Promise<string> {",
+        "  return renderApplication(bootstrap, { document, url });",
+        "}",
+      ].join("\n"),
+      resolveDir: options.pkgDir,
+      sourcefile: "sd-ssg-entry.ts",
+      loader: "ts",
+    },
+    target: "node20",
+    bundle: true,
+    splitting: false,
+    format: "esm",
+    platform: "node",
+    outdir,
+    // stdin 진입점의 출력 이름은 "stdin"으로 고정되므로 entryNames로 결정론적 지정
+    entryNames: "sd-ssg-entry",
+    outExtension: { ".js": ".mjs" },
+    write: true,
+    sourcemap: false,
+    logLevel: "silent",
+    tsconfig: options.tsconfig ?? path.join(options.pkgDir, "tsconfig.json"),
+    define,
+    banner: { js: bannerJs },
+    plugins: [
+      angularPlugin,
+      scssPlugin,
+      ...(loadedPostcssPlugins != null
+        ? [createPostcssPlugin({ plugins: loadedPostcssPlugins })]
+        : []),
+    ],
+  });
+
+  return { bundlePath };
+}

package/src/sd-config.types.ts

@@ -240,6 +240,13 @@ export interface SdClientPackageConfig {
   browserSupport?: SdBrowserSupportConfig;
   /** PWA 설정. false이면 비활성화. 미지정 시 기본값으로 활성화 */
   pwa?: false | SdPwaConfig;
+  /**
+   * SSG(빌드 타임 프리렌더) 라우트 목록 (예: ["/", "/about"])
+   * - 지정 시 프로덕션 빌드에서 src/main.server.ts 진입점으로 라우트별 HTML을 생성
+   * - SPA 셸은 index.csr.html로 별도 출력 (비프리렌더 라우트 딥링크 폴백용)
+   * - dev/watch 모드에는 적용되지 않음 (기존 SPA dev 서버 그대로)
+   */
+  prerender?: string[];
 }
 
 /**

package/src/ssg/prerender.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "path";
+import { pathToFileURL } from "node:url";
+import { createLogger } from "@simplysm/core-common";
+
+const logger = createLogger("sd:cli:ssg:prerender");
+
+export interface PrerenderOptions {
+  /** buildSsrBundle로 생성된 server 번들 경로 */
+  bundlePath: string;
+  /** 프리렌더할 라우트 경로 목록 (예: ["/", "/about"]) */
+  routes: string[];
+  /** 렌더 기준 문서 (SPA 셸 index.html 내용) */
+  documentHtml: string;
+  /** base 경로 (예: "/my-client/") — 렌더 URL 구성에 사용 */
+  basePath: string;
+  /** HTML 출력 디렉토리 (dist/) */
+  outdir: string;
+}
+
+interface SsrBundleModule {
+  render(url: string, document: string): Promise<string>;
+}
+
+/**
+ * server 번들로 라우트별 HTML을 생성해 outdir에 기록한다.
+ *
+ * 라우트 1건이라도 실패하면 throw (빌드 전체 실패 — 부분 산출 금지).
+ */
+export async function prerenderRoutes(options: PrerenderOptions): Promise<void> {
+  const bundleModule = (await import(
+    pathToFileURL(options.bundlePath).href
+  )) as SsrBundleModule;
+
+  // 1. 전체 라우트 렌더 (전부 성공해야 기록 단계로 진행)
+  const rendered: { route: string; html: string }[] = [];
+  for (const route of options.routes) {
+    const normalizedRoute = normalizeRoute(route);
+    const url = path.posix.join(options.basePath, normalizedRoute);
+    logger.debug(`프리렌더: ${url}`);
+    try {
+      const html = await bundleModule.render(url, options.documentHtml);
+      rendered.push({ route: normalizedRoute, html });
+    } catch (err) {
+      throw new Error(`프리렌더 실패 (라우트: ${route}): ${err instanceof Error ? err.message : String(err)}`, {
+        cause: err,
+      });
+    }
+  }
+
+  // 2. 라우트별 <경로>/index.html 기록 ("/"는 index.html)
+  for (const { route, html } of rendered) {
+    const htmlPath = path.join(options.outdir, route, "index.html");
+    fs.mkdirSync(path.dirname(htmlPath), { recursive: true });
+    fs.writeFileSync(htmlPath, html);
+  }
+}
+
+/** 라우트 경로 정규화: 선행 "/" 제거 ("/" → "") */
+function normalizeRoute(route: string): string {
+  if (!route.startsWith("/")) {
+    throw new Error(`프리렌더 라우트는 "/"로 시작해야 합니다: "${route}"`);
+  }
+  return route.replace(/^\/+/, "").replace(/\/+$/, "");
+}

package/src/workers/client.worker.ts

@@ -14,6 +14,8 @@ import { createDevHttpServer, type DevHttpServer } from "../dev-server/dev-http-
 import { createHmrService, type HmrService } from "../dev-server/hmr-service";
 import { createHmrPostTransform } from "../dev-server/hmr-client-script";
 import { copyPublicFiles, watchPublicFiles } from "../utils/copy-public";
+import { buildSsrBundle } from "../esbuild/esbuild-ssr-config";
+import { prerenderRoutes } from "../ssg/prerender";
 import type { SdBrowserSupportConfig, SdPwaConfig } from "../sd-config.types";
 import type esbuild from "esbuild";
 import type { PartialMessage } from "esbuild";
@@ -40,6 +42,8 @@ export interface ClientBuildInfo {
   base?: string;
   /** 브라우저 지원 설정 (메인 프로세스에서 전달, Worker 내 sd.config.ts 재로드 방지) */
   browserSupport?: SdBrowserSupportConfig;
+  /** SSG(빌드 타임 프리렌더) 라우트 목록. 지정 시 프로덕션 빌드에서만 적용 */
+  prerender?: string[];
 }
 
 /** Client 빌드 결과 */
@@ -150,6 +154,28 @@ async function build(info: ClientBuildInfo): Promise<ClientBuildResult> {
 
     fs.writeFileSync(path.join(outdir, "index.html"), indexResult.content);
 
+    // 5.5. SSG 프리렌더 (opt-in — prerender 설정이 있을 때만)
+    if (info.prerender != null && info.prerender.length > 0 && indexResult.errors.length === 0) {
+      // SPA 셸 별도 보존 (비프리렌더 라우트 딥링크 폴백용 — 서버 정적 핸들러가 사용)
+      fs.writeFileSync(path.join(outdir, "index.csr.html"), indexResult.content);
+
+      const { bundlePath } = await buildSsrBundle({
+        pkgDir: info.pkgDir,
+        cwd: info.cwd,
+        env: info.env,
+        postcssPlugins: info.browserSupport?.postCss?.plugins,
+      });
+
+      // 라우트별 HTML 생성 ("/"는 index.html을 프리렌더 결과로 대체)
+      await prerenderRoutes({
+        bundlePath,
+        routes: info.prerender,
+        documentHtml: indexResult.content,
+        basePath,
+        outdir,
+      });
+    }
+
     // 6. PWA 적용
     await applyPwa({
       pkgDir: info.pkgDir,

package/tests/engines/base-engine.spec.ts

@@ -14,8 +14,7 @@ vi.spyOn(Worker, "create").mockReturnValue(mockWorker as any);
 import { TscEngine } from "../../src/engines/TscEngine";
 import { BaseEngine } from "../../src/engines/BaseEngine";
 
-import type { BuildPackageInfo, BuildOutput } from "../../src/engines/types";
-import type { BuildResult } from "../../src/runtime/ResultCollector";
+import type { BuildPackageInfo } from "../../src/engines/types";
 
 // --- Helpers ---
 
@@ -373,18 +372,6 @@ describe("BaseEngine", () => {
   });
 
   describe("lint 통합", () => {
-    describe("BuildOutput.lint flag controls lint execution", () => {
-      it("BuildOutput이 lint 불리언 플래그를 수용", () => {
-        const output: BuildOutput = { js: true, dts: true, lint: true };
-        expect(output.lint).toBe(true);
-      });
-
-      it("BuildOutput.lint는 미설정 시 undefined가 기본값", () => {
-        const output: BuildOutput = { js: true, dts: true };
-        expect(output.lint).toBeUndefined();
-      });
-    });
-
     describe("EngineResult includes lint field", () => {
       it("run() returns EngineResult with lint field when worker provides it", async () => {
         mockWorker.build.mockResolvedValue({
@@ -496,17 +483,5 @@ describe("BaseEngine", () => {
         await engine.stop();
       });
     });
-
-    describe("ResultCollector supports lint type", () => {
-      it("BuildResult 타입에 lint 포함", () => {
-        const lintResult: BuildResult = {
-          name: "test-pkg",
-          target: "node",
-          type: "lint",
-          status: "success",
-        };
-        expect(lintResult.type).toBe("lint");
-      });
-    });
   });
 });

package/tests/init/__snapshots__/render.spec.ts.snap

@@ -1,68 +1,82 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`client/src/main.ts.hbs > 라우팅 N (mobile) 1`] = `
-"import consola from "consola";
-import { enableProdMode, inject, provideAppInitializer } from "@angular/core";
+"import { enableProdMode, inject, provideAppInitializer } from "@angular/core";
 import { bootstrapApplication } from "@angular/platform-browser";
 import { provideHttpClient, withFetch } from "@angular/common/http";
-import { provideSdAngular } from "@simplysm/angular";
-import { AppServiceProvider } from "@demo/client-common";
+import {
+  provideSdAngular,
+} from "@simplysm/angular";
+import { createLogger } from "@simplysm/core-common";
 import { AppRoot } from "./app.root";
 import "./styles.scss";
+import {
+  AppServiceProvider,
+} from "@demo/client-common";
+
+const CLIENT_NAME = "client-pda";
+
+const logger = createLogger(CLIENT_NAME);
 
 if (typeof ngDevMode !== "undefined" && !ngDevMode) {
   enableProdMode();
 } else {
-  consola.log("dev mode");
+  logger.info("dev mode");
 }
 
 bootstrapApplication(AppRoot, {
   providers: [
     provideHttpClient(withFetch()),
-    provideSdAngular({ clientName: "client-pda" }),
+    provideSdAngular({ clientName: CLIENT_NAME }),
 
-    //-- app-service 연결
     provideAppInitializer(async () => {
       await inject(AppServiceProvider).connectAsync();
     }),
   ],
 }).catch((err: unknown) => {
-  consola.error(err);
+  logger.error("부트스트랩 실패", err);
 });
 "
 `;
 
 exports[`client/src/main.ts.hbs > 라우팅 Y (web) 1`] = `
-"import consola from "consola";
-import { enableProdMode, inject, provideAppInitializer } from "@angular/core";
+"import { enableProdMode, inject, provideAppInitializer } from "@angular/core";
 import { bootstrapApplication } from "@angular/platform-browser";
 import { provideHttpClient, withFetch } from "@angular/common/http";
 import { provideRouter, withHashLocation } from "@angular/router";
-import { provideSdAngular } from "@simplysm/angular";
-import { AppServiceProvider } from "@demo/client-common";
+import {
+  provideSdAngular,
+} from "@simplysm/angular";
+import { createLogger } from "@simplysm/core-common";
 import { AppRoot } from "./app.root";
 import { routes } from "./routes";
 import "./styles.scss";
+import {
+  AppServiceProvider,
+} from "@demo/client-common";
+
+const CLIENT_NAME = "client-admin";
+
+const logger = createLogger(CLIENT_NAME);
 
 if (typeof ngDevMode !== "undefined" && !ngDevMode) {
   enableProdMode();
 } else {
-  consola.log("dev mode");
+  logger.info("dev mode");
 }
 
 bootstrapApplication(AppRoot, {
   providers: [
     provideHttpClient(withFetch()),
     provideRouter(routes, withHashLocation()),
-    provideSdAngular({ clientName: "client-admin" }),
+    provideSdAngular({ clientName: CLIENT_NAME }),
 
-    //-- app-service 연결
     provideAppInitializer(async () => {
       await inject(AppServiceProvider).connectAsync();
     }),
   ],
 }).catch((err: unknown) => {
-  consola.error(err);
+  logger.error("부트스트랩 실패", err);
 });
 "
 `;
@@ -177,7 +191,7 @@ exports[`server/src/main.ts.hbs > DB=N — OrmService 없음 1`] = `
 import { env, num, parseBoolEnv } from "@simplysm/core-common";
 import { setupConsola } from "@simplysm/core-node";
 import { createServiceServer, getConfig } from "@simplysm/service-server";
-import {EventEmitter} from "node:events";
+import { EventEmitter } from "node:events";
 
 Error.stackTraceLimit = Infinity;
 EventEmitter.defaultMaxListeners = 0;
@@ -194,7 +208,8 @@ if (authConfig?.jwtSecret == null) {
 
 export const server = createServiceServer({
   rootPath: import.meta.dirname,
-  services: [],
+  services: [
+  ],
   port: num.parseInt(env("SERVER_PORT"))!,
   auth: { jwtSecret: authConfig.jwtSecret },
 });
@@ -210,7 +225,7 @@ exports[`server/src/main.ts.hbs > DB=Y — OrmService 포함 1`] = `
 import { env, num, parseBoolEnv } from "@simplysm/core-common";
 import { setupConsola } from "@simplysm/core-node";
 import { createServiceServer, getConfig, OrmService } from "@simplysm/service-server";
-import {EventEmitter} from "node:events";
+import { EventEmitter } from "node:events";
 import { DevService } from "./services/dev.service";
 
 Error.stackTraceLimit = Infinity;
@@ -228,7 +243,10 @@ if (authConfig?.jwtSecret == null) {
 
 export const server = createServiceServer({
   rootPath: import.meta.dirname,
-  services: [OrmService, ...(parseBoolEnv(env("DEV")) ? [DevService] : [])],
+  services: [
+    OrmService,
+    ...(parseBoolEnv(env("DEV")) ? [DevService] : []),
+  ],
   port: num.parseInt(env("SERVER_PORT"))!,
   auth: { jwtSecret: authConfig.jwtSecret },
 });