fix(nuxt): Node용 #internal/nuxt/paths 해석 및 paths.mjs 디스크 기록

- app:templates에서 paths.mjs에 write: true를 부여하는 로컬 모듈 추가
- 루트 package.json imports로 .nuxt/paths.mjs 매핑
- nuxt ^3.21.2로 명시, 문서(v0.0.59) 반영

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/history.md

@@ -1,5 +1,11 @@
 # 의사결정 이력
 
+## 2026-05-11 v0.0.59
+
+### Nuxt `#internal/nuxt/paths` Node 해석 오류
+
+Nuxt 3.21과 `@nuxt/vite-builder`는 SSR 엔트리에서 `#internal/nuxt/paths`를 롤업 외부 모듈로 남기는데, 동일 경로의 `paths.mjs` 템플릿은 기본적으로 VFS에만 있어 디스크 파일이 없다. Node는 프로젝트 루트 `package.json`의 `imports`로만 서브패스를 해석하므로, 템플릿을 디스크에 쓰도록(`write: true`) 훅하는 로컬 모듈과 루트 `imports` 매핑을 추가했다. `nitro-server` 경로만으로 브리지하면 `nitropack/runtime` 쪽 내부 specifier가 끌려와 단독 해석이 깨지므로, Nuxt가 생성하는 `paths.mjs` 본문을 그대로 두는 방식을 택했다.
+
 ## 2026-05-11 v0.0.58
 
 ### 중앙 본문과 우측 사이드 가로 넘침

docs/map.md

@@ -17,6 +17,12 @@
 |------|------|
 | composables/formatPostDate.js | 공개 화면 게시일 `YYYY.MM.DD` 포맷 |
 
+## Nuxt 모듈
+
+| 파일 | 용도 |
+|------|------|
+| modules/nuxt-ssr-paths-write.mjs | `paths.mjs`를 `.nuxt`에 기록해 Node가 `#internal/nuxt/paths`를 해석할 수 있게 함 |
+
 ## 사이트 컴포넌트
 
 | 파일 | 화면 위치 |

docs/spec.md

@@ -6,7 +6,7 @@
 - **유형**: 커스텀 블로그/CMS
 - **목표**: 개인 블로그 중심 운영, 기존 포털성 링크와 서비스 진입점은 블로그 내부 구조에 통합
 - **참조**: Ghost(관리자 UX/글쓰기), Thred 테마(사용자 화면)
-- **현재 상태**: Nuxt 3 초기 스캐폴딩과 PostgreSQL 저장소 계층 구성 완료
+- **현재 상태**: Nuxt 3.21(SSR)·PostgreSQL 저장소 계층 구성 완료. Node가 SSR 번들의 `#internal/nuxt/paths`를 해석하도록 루트 `package.json` `imports`와 `modules/nuxt-ssr-paths-write.mjs`(`.nuxt/paths.mjs` 디스크 기록)을 둔다.
 - **원격 저장소**: https://git.sori.studio/zenn/sori.studio.git
 
 ---

docs/update.md

@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v0.0.59
+
+- Nuxt 3.21 SSR이 `#internal/nuxt/paths`를 외부 import로 두는데 `.nuxt/paths.mjs`가 기본적으로 디스크에 쓰이지 않아 Node가 루트 `package.json`에서 해석하지 못하던 오류 수정.
+- `modules/nuxt-ssr-paths-write.mjs`에서 `paths.mjs` 템플릿에 `write: true`를 부여하고, 루트 `package.json` `imports`로 `./.nuxt/paths.mjs`를 매핑.
+- `nuxt` 의존성을 `^3.21.2`로 올려 lockfile과 정렬.
+
 ## v0.0.58
 
 - 공개 3열 그리드 중앙을 `minmax(0,1fr)`로 바꾸고 `lg:gap-x-4`·`xl:gap-x-5`를 두어 본문과 오른쪽 사이드 사이 시각적 간격 확보.

modules/nuxt-ssr-paths-write.mjs

@@ -0,0 +1,25 @@
+import { defineNuxtModule } from '@nuxt/kit'
+
+/**
+ * Nuxt 3.21 SSR 번들이 `#internal/nuxt/paths`를 외부 모듈로 두는데,
+ * 기본 `paths.mjs` 템플릿은 `write: true`가 아니어서 `.nuxt/paths.mjs`가 디스크에 없고
+ * Node가 `package.json`의 `imports`로 해석할 실제 파일이 없어 오류가 난다.
+ * 동일 템플릿을 빌드 디렉터리에 기록하도록 한다.
+ * @param {unknown} _options - 모듈 옵션(미사용)
+ * @param {import('@nuxt/schema').Nuxt} nuxt - Nuxt 인스턴스
+ * @returns {void}
+ */
+export default defineNuxtModule({
+  meta: {
+    name: 'nuxt-ssr-paths-write'
+  },
+  setup(_options, nuxt) {
+    nuxt.hook('app:templates', (app) => {
+      for (const template of app.templates) {
+        if (template.filename === 'paths.mjs') {
+          template.write = true
+        }
+      }
+    })
+  }
+})

nuxt.config.js

@@ -7,7 +7,7 @@ export default defineNuxtConfig({
   devtools: {
     enabled: false
   },
-  modules: ['@nuxtjs/tailwindcss'],
+  modules: ['./modules/nuxt-ssr-paths-write.mjs', '@nuxtjs/tailwindcss'],
   components: [
     {
       path: '~/components',

package-lock.json

@@ -1,16 +1,16 @@
 {
   "name": "sori.studio",
-  "version": "0.0.43",
+  "version": "0.0.59",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sori.studio",
-      "version": "0.0.43",
+      "version": "0.0.59",
       "hasInstallScript": true,
       "dependencies": {
         "@nuxtjs/tailwindcss": "^6.14.0",
-        "nuxt": "^3.16.2",
+        "nuxt": "^3.21.2",
         "postgres": "^3.4.9",
         "vue": "^3.5.13",
         "vue-router": "^4.5.0",

package.json

@@ -1,8 +1,11 @@
 {
   "name": "sori.studio",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "private": true,
   "type": "module",
+  "imports": {
+    "#internal/nuxt/paths": "./.nuxt/paths.mjs"
+  },
   "scripts": {
     "dev": "node scripts/dev-server.js",
     "build": "nuxt build",
@@ -12,7 +15,7 @@
   },
   "dependencies": {
     "@nuxtjs/tailwindcss": "^6.14.0",
-    "nuxt": "^3.16.2",
+    "nuxt": "^3.21.2",
     "postgres": "^3.4.9",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0",