@dokebi/template-inertia 0.1.1 → 0.1.2

package/AI.md

@@ -1,4 +1,4 @@
-# AI 작업 안내 — @dokebi/template-inertia 0.1.1
+# AI 작업 안내 — @dokebi/template-inertia 0.1.2
 
 Inertia(v3) 서버 어댑터다. 첫 요청은 HTML(+ `script[data-page]` JSON), 이후 `X-Inertia` 요청은 page JSON으로 답한다. Vite manifest를 읽어 스크립트·스타일·버전을 채우고 빌드 파일을 직접 내보낸다. 선택적으로 첫 HTML을 같은 프로세스에서 서버 렌더링(SSR, D-0039)한다. Vue·Vite는 서버 의존성이 아니다(앱의 개발 의존성). Node >=24.0.0, core ^0.2.0, @dokebi/web(peer). 세부는 [README](README.md)다.
 
@@ -21,7 +21,7 @@ npm run build                                       # dist/(브라우저) + dist
 | `rootId` | 루트 요소 id(기본 `app`, `^[A-Za-z][A-Za-z0-9_-]*$`) |
 | `version` · `scripts` · `styles` | 자산 버전과 URL(`/`로 시작하는 로컬 URL). 없으면 `INERTIA_VERSION_DEFAULT` 경고 |
 | `vite: { manifest, entry, base? }` | manifest에서 scripts·styles·version 계산. 위 셋과 함께 쓰면 거부 |
-| `ssr: { bundle, failure? }` | 서버 렌더링. `failure`: `fallback`(기본) · `error` |
+| `ssr: { bundle, failure?, entry? }` | 서버 렌더링. `failure`: `fallback`(기본) · `error`. `entry`는 개발 모드에서 쓰는 번들의 원본 모듈(§5.1) |
 
 ## 3. 페이지 렌더
 
@@ -59,6 +59,14 @@ route.post('/orders', async (request, reply, page) => {
 - 브라우저 진입은 `el.hasAttribute('data-server-rendered')`면 `createSSRApp`으로 hydration한다. 서버·브라우저가 같은 레이아웃을 고르도록 페이지 모듈을 바꾸지 말고 `layout` 옵션을 쓴다(동시에 여러 템플릿을 그리므로).
 - `ssrStats()` → `{ renders, failures }`(health·대시보드용). `scope({ ssr: false })`로 앱별로 끌 수 있다.
 
+## 5.1 개발 모드(HMR, D-0045)
+
+- 환경 변수 `DOKEBI_VITE_DEV=1`(`dokebi dev`가 넣는다)이면 manifest·빌드 없이 **프로젝트의 Vite를 미들웨어 모드로** 한 프로세스에 하나 띄운다. 페이지 스크립트는 `<base>@vite/client`와 `<base><vite.entry>`, 스타일 링크 없음, version `dev`. `<base>*` 요청은 Vite가 답한다.
+- HMR 소켓은 프로세스마다 빈 포트 하나를 따로 쓴다(앱 포트는 @dokebi/websocket이 upgrade를 모두 받으므로). 브라우저는 페이지와 같은 호스트로 붙는다.
+- SSR은 요청마다 `ssrLoadModule(<원본 진입>)`. 원본 진입은 `ssr.entry`(예: `src/apps/admin/views/ssr.js`), 없으면 `vite.entry`와 같은 폴더의 `ssr.js`. 둘 다 없으면 시작 실패.
+- Vite가 프로젝트에 없으면 시작 실패(`npm install --save-dev vite`). Vite는 `localhost`·`*.localhost`·IP 말고 다른 호스트(예: hosts 파일의 `admin.a.com`)를 막으므로, 그런 도메인으로 개발하면 vite.config에 `server.allowedHosts`를 넣는다.
+- 운영(`DOKEBI_VITE_DEV` 없음)에는 영향이 없다. 운영 서버에 이 변수를 넣지 않는다.
+
 ## 6. 범위(scope)
 
 `await api.scope({ title?, rootId?, version?, scripts?, styles?, vite?, ssr?, shared? })` → 그 설정의 렌더러. 정하지 않은 값은 플러그인 옵션, `shared`는 플러그인 shared 뒤에 합쳐진다. @dokebi/app이 앱마다 부른다.
@@ -71,4 +79,4 @@ route.post('/orders', async (request, reply, page) => {
 - deferred·merge·once props, Precognition, session flash는 없다. 있다고 가정하지 않는다.
 - 앱 인스턴스마다 새 플러그인. 전체 drain 뒤에 responder가 닫힌다.
 
-근거: `examples/24-template-inertia`(실제 Chrome: CSR·SSR·cluster, 측정), `examples/26-scaffold`(CLI가 만든 SSR 앱의 빌드·서버 렌더), `examples/25-playground`, D-0027·D-0031·D-0039.
+근거: `examples/24-template-inertia`(실제 Chrome: CSR·SSR·cluster, 측정), `examples/26-scaffold`(CLI가 만든 SSR 앱의 빌드·서버 렌더), `examples/25-playground`, D-0027·D-0031·D-0039·D-0045.

package/README.md

@@ -1,4 +1,4 @@
-# @dokebi/template-inertia 0.1.1
+# @dokebi/template-inertia 0.1.2
 
 Node >=24.0.0, core ^0.2.0, 선택 패키지다(npm 공개). ID는 `dokebi-template-inertia`이며 `dokebi-web`에 의존한다. `@dokebi/web`은 peer 의존성이다(예전의 고정 버전 dependency가 아니다). EJS·Vue·Vite를 서버 패키지의 필수 의존성으로 설치하지 않는다.
 
@@ -64,3 +64,7 @@ Vue 페이지 이동·초기 props는 Inertia, 이후 조회·수정은 `fetch('
 - `scope({ ssr })`: 앱마다 번들을 정한다. 생략하면 플러그인 옵션을 따르고 `false`면 끈다. 같은 파일은 한 번만 import한다.
 
 측정(예제 24, 같은 프로세스, 순차 400회): CSR 0.20~0.24ms, SSR 0.24~0.28ms(작은 페이지), SSR 450장 뒤 heap +1.1MB.
+
+## 개발 모드(HMR, [D-0045](../../docs/decisions/D-0045-inertia-vite-dev.md))
+
+`DOKEBI_VITE_DEV=1`(`dokebi dev`가 넣는다)이면 빌드 없이 프로젝트의 Vite를 미들웨어 모드로 띄워 `<base>*`를 Vite가 답하고, 페이지는 `@vite/client`와 원본 진입을 불러온다. `.vue`를 고치면 새로고침 없이 바뀐다(HMR 소켓은 프로세스마다 따로 잡은 빈 포트). SSR은 요청마다 Vite로 원본(`ssr.entry`, 없으면 `vite.entry` 옆 `ssr.js`)을 그린다. 운영에는 영향이 없다.

package/dist/index.d.ts

@@ -18,6 +18,11 @@ export interface InertiaSsrOptions {
      * `error` fails the request, which is easier to notice while developing.
      */
     readonly failure?: 'fallback' | 'error';
+    /**
+     * Source module of the bundle (for example `src/apps/admin/views/ssr.js`), rendered through
+     * Vite in development (D-0045). Default: `ssr.js` beside the `vite.entry` when it exists.
+     */
+    readonly entry?: string;
 }
 /** Counts since start, for health checks and dashboards. */
 export interface InertiaSsrStats {

package/dist/index.js

@@ -1,10 +1,12 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { types } from 'node:util';
 import { definePlugin, providerDependency, } from '@dokebi/core';
 import { InertiaResponder, normalizeInertiaOptions, } from './responder.js';
+import { startViteDev, viteDevRequested } from './vite-dev.js';
 const MANIFEST_MAX_BYTES = 4 * 1024 * 1024;
 function parseVite(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
@@ -25,13 +27,14 @@ function parseSsr(input) {
         return undefined;
     if (input === null || typeof input !== 'object' || Array.isArray(input) || types.isProxy(input))
         throw new TypeError('Invalid Inertia ssr options');
-    const { bundle, failure = 'fallback', ...rest } = input;
+    const { bundle, failure = 'fallback', entry, ...rest } = input;
     if (Object.keys(rest).length ||
         typeof bundle !== 'string' ||
         !bundle ||
-        (failure !== 'fallback' && failure !== 'error'))
+        (failure !== 'fallback' && failure !== 'error') ||
+        (entry !== undefined && (typeof entry !== 'string' || !entry || entry.includes('..'))))
         throw new TypeError('Invalid Inertia ssr options');
-    return Object.freeze({ bundle, failure });
+    return Object.freeze({ bundle, failure, ...(entry ? { entry: entry } : {}) });
 }
 /**
  * Imports the SSR bundle. A missing file or a bundle without `render` stops the start: SSR that
@@ -194,9 +197,52 @@ class InertiaRuntime {
                 code: 'INERTIA_VERSION_DEFAULT',
             });
         const server = context.getDependency(web);
+        // Development (D-0045): one Vite dev server for every scope, started by the first `vite`.
+        const develop = viteDevRequested();
+        let devServer;
+        const devBases = new Set();
+        // Registered now: scopes are created later, from other plugins' setup.
+        context.defer(async () => {
+            if (devServer)
+                await (await devServer).close();
+        });
+        const viteDev = (base) => {
+            if (!devServer) {
+                devServer = startViteDev();
+                context.logger.log('info', 'Inertia views are served by the Vite dev server', {
+                    code: 'INERTIA_VITE_DEV',
+                });
+            }
+            const current = devServer;
+            if (!devBases.has(base)) {
+                devBases.add(base);
+                // Modules, pre-bundled dependencies and @vite/client, under the Vite base.
+                server.route({
+                    method: 'GET', // Fastify adds HEAD
+                    url: `${base}*`,
+                    handler: async (request, reply) => {
+                        const vite = await current;
+                        reply.hijack();
+                        vite.middlewares(request.raw, reply.raw, () => {
+                            reply.raw.statusCode = 404;
+                            reply.raw.end();
+                        });
+                    },
+                });
+            }
+            return current;
+        };
         // Built files are served at their exact URL (no wildcard), once even if apps share chunks.
         const served = new Set();
         const built = async (options) => {
+            if (develop) {
+                await viteDev(options.base);
+                return {
+                    scripts: [`${options.base}@vite/client`, `${options.base}${options.entry}`],
+                    styles: [],
+                    version: 'dev',
+                };
+            }
             const { files, ...assets } = await viteAssets(options);
             for (const [url, file] of files) {
                 if (served.has(url))
@@ -223,14 +269,31 @@ class InertiaRuntime {
         // One import per bundle file, shared by the scopes that name it.
         const bundles = new Map();
         const stats = { renders: 0, failures: 0 };
-        const serverRendering = async (ssr) => {
+        const serverRendering = async (ssr, vite) => {
             if (!ssr)
                 return undefined;
-            const path = resolve(ssr.bundle);
-            let render = bundles.get(path);
-            if (!render) {
-                render = loadBundle(ssr.bundle);
-                bundles.set(path, render);
+            let render;
+            if (develop) {
+                // The source module through Vite on every render: an edit shows in the next first HTML.
+                const fallback = vite ? `${dirname(vite.entry)}/ssr.js` : undefined;
+                const source = ssr.entry ?? (fallback && existsSync(resolve(fallback)) ? fallback : undefined);
+                if (!source || !vite)
+                    throw new Error(`Inertia SSR in development needs the source of ${ssr.bundle}: set ssr.entry`);
+                const dev = viteDev(vite.base);
+                render = Promise.resolve(async (page) => {
+                    const module = await (await dev).ssrLoadModule(`/${source}`);
+                    if (typeof module.render !== 'function')
+                        throw new Error(`Inertia SSR entry ${source} does not export render(page)`);
+                    return module.render(page);
+                });
+            }
+            else {
+                const path = resolve(ssr.bundle);
+                render = bundles.get(path);
+                if (!render) {
+                    render = loadBundle(ssr.bundle);
+                    bundles.set(path, render);
+                }
             }
             return Object.freeze({
                 render: await render,
@@ -263,7 +326,7 @@ class InertiaRuntime {
                 location: responder.location.bind(responder),
             });
         };
-        const root = api(new InertiaResponder(document, this.shared, await serverRendering(this.settings.ssr)));
+        const root = api(new InertiaResponder(document, this.shared, await serverRendering(this.settings.ssr, this.settings.vite)));
         const shared = this.shared;
         return Object.freeze({
             ...root,
@@ -283,14 +346,15 @@ class InertiaRuntime {
                 const merged = shared && extra
                     ? async (request) => ({ ...(await shared(request)), ...(await extra(request)) })
                     : (extra ?? shared);
-                return api(new InertiaResponder(scoped, merged, await serverRendering(ssr)));
+                const scopedVite = vite === undefined ? this.settings.vite : parseVite(vite);
+                return api(new InertiaResponder(scoped, merged, await serverRendering(ssr, scopedVite)));
             },
         });
     }
 }
 export const createPlugin = definePlugin({
     name: 'dokebi-template-inertia',
-    version: '0.1.1',
+    version: '0.1.2',
     core: '^0.2.0',
     options: parseOptions,
     entry: parseEntry,

package/dist/vite-dev.d.ts

@@ -0,0 +1,13 @@
+/** The part of Vite's dev server used here. */
+export interface ViteDevServer {
+    middlewares(request: unknown, response: unknown, next: (error?: unknown) => void): void;
+    ssrLoadModule(url: string): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+export declare const viteDevRequested: () => boolean;
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
+ * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
+ * the ones that are not its routes, so HMR cannot share that server.
+ */
+export declare function startViteDev(root?: string): Promise<ViteDevServer>;

package/dist/vite-dev.js

@@ -0,0 +1,42 @@
+// Development mode (D-0045): with DOKEBI_VITE_DEV=1 (set by `dokebi dev`) pages load their code
+// from the project's Vite in middleware mode instead of a build, so a .vue edit reaches the
+// browser by hot module replacement. Vite is the project's dev dependency, found from the
+// working directory; this package does not depend on it.
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const viteDevRequested = () => process.env.DOKEBI_VITE_DEV === '1';
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('port')));
+        });
+    });
+}
+/**
+ * Starts the project's Vite (its vite.config.*) in middleware mode. The HMR socket gets a free
+ * port of its own: @dokebi/websocket answers every upgrade on the app's HTTP server and closes
+ * the ones that are not its routes, so HMR cannot share that server.
+ */
+export async function startViteDev(root = process.cwd()) {
+    let entry;
+    try {
+        const require = createRequire(join(root, 'package.json'));
+        entry = join(dirname(require.resolve('vite/package.json')), 'dist/node/index.js');
+    }
+    catch (cause) {
+        throw new Error('DOKEBI_VITE_DEV=1 needs Vite in the project (npm install --save-dev vite)', {
+            cause,
+        });
+    }
+    const vite = (await import(pathToFileURL(entry).href));
+    return vite.createServer({
+        root,
+        appType: 'custom',
+        server: { middlewareMode: true, hmr: { port: await freePort() } },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/template-inertia",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "license": "MIT",