@fluojs/vite 1.0.5 → 1.0.7

package/README.ko.md

@@ -8,7 +8,9 @@ fluo 프로젝트를 위한 Vite 플러그인과 빌드 유틸리티입니다.
 
 - [설치](#설치)
 - [사용 시점](#사용-시점)
+- [런타임 및 peer 계약](#런타임-및-peer-계약)
 - [빠른 시작](#빠른-시작)
+- [데코레이터 변환 경계](#데코레이터-변환-경계)
 - [공개 API](#공개-api)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -27,6 +29,12 @@ npm install --save-dev @fluojs/vite vite @babel/core @babel/plugin-proposal-deco
 - starter 프로젝트가 Babel 설정을 inline으로 복사하지 않고 유지보수되는 decorator transform을 import해야 할 때
 - 향후 Vite 대상 fluo 빌드 유틸리티에 독립적인 public package 경계가 필요할 때
 
+## 런타임 및 peer 계약
+
+`@fluojs/vite`는 `engines.node` 하한을 `>=20.0.0`으로 두는 Node.js 패키지입니다. 생성된 non-Deno starter는 이 Node 기준선과 Vite `>=6.2.0`, 그리고 위에 나열한 Babel peer를 함께 사용합니다.
+
+패키지 root는 Babel이 설치되거나 해석되기 전에 import해도 안전합니다. `@fluojs/vite`를 import하거나 `fluoDecoratorsPlugin()`을 생성해도 `@babel/core`를 로드하지 않습니다. Babel은 eligible 애플리케이션 `.ts` 파일에 대한 Vite `transform` hook에서만 lazy load되며, 누락된 Babel peer도 plugin 생성 시점이 아니라 이 transform 경계에서 보고됩니다.
+
 ## 빠른 시작
 
 ```ts
@@ -44,6 +52,16 @@ export default defineConfig({
 
 이 플러그인은 `.ts` 애플리케이션 파일을 Babel로 변환하며 `2023-11` decorators proposal과 `@babel/preset-typescript`를 사용합니다. 파일 경계를 판단하기 전에 Vite query suffix를 제거한 뒤 declaration 파일, `*.test.ts` 또는 `*.spec.ts` 파일, `node_modules`, `.ts`가 아닌 파일은 건너뛰므로 생성된 Vitest 테스트 파일은 계속 전용 `@fluojs/testing/vitest` transform 경로를 사용합니다. `@fluojs/vite`를 import하거나 `fluoDecoratorsPlugin()`을 생성하는 시점에는 `@babel/core`를 로드하지 않으며, 누락된 Babel peer는 Vite가 변환 중인 소스 파일에 대한 transform-time 진단으로 표시됩니다.
 
+## 데코레이터 변환 경계
+
+`@fluojs/vite`는 Vitest 테스트 변환이 아니라 애플리케이션 빌드 변환을 소유합니다. 생성된 non-Deno starter는 파일 경계 분리를 명시적으로 유지합니다:
+
+1. `vite.config.ts`는 `@fluojs/vite`에서 `fluoDecoratorsPlugin()`을 import합니다.
+2. Vite 플러그인은 query suffix를 제거하고 애플리케이션 `.ts` 파일만 허용하며, 첫 eligible transform 시점에 Babel을 lazy load한 뒤 `@babel/plugin-proposal-decorators`의 `{ version: '2023-11' }` 설정과 `@babel/preset-typescript`를 실행합니다.
+3. `vitest.config.ts`는 `@fluojs/testing/vitest`에서 `fluoBabelDecoratorsPlugin()`을 import하므로 `*.test.ts`와 `*.spec.ts` 파일은 testing-specific transform 경로에 남습니다.
+
+생성 프로젝트를 커스터마이즈할 때도 이 경계를 분리하세요. `experimentalDecorators`를 다시 활성화하거나, direct esbuild decorator handling에 의존하거나, 테스트 파일을 Vite 애플리케이션 transform으로 보내는 방식은 문서화된 fluo 지원 계약 밖에 있습니다.
+
 ## 공개 API
 
 - `fluoDecoratorsPlugin()` — 생성된 fluo starter 프로젝트가 사용하는 Vite 플러그인을 만듭니다.

package/README.md

@@ -8,7 +8,9 @@ Vite plugin and build utilities for fluo projects.
 
 - [Installation](#installation)
 - [When to Use](#when-to-use)
+- [Runtime and Peer Contract](#runtime-and-peer-contract)
 - [Quick Start](#quick-start)
+- [Decorator Transform Boundary](#decorator-transform-boundary)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -27,6 +29,12 @@ npm install --save-dev @fluojs/vite vite @babel/core @babel/plugin-proposal-deco
 - when starter projects should import the maintained decorator transform instead of copying Babel configuration inline
 - when future Vite-facing fluo build utilities need a dedicated public package boundary
 
+## Runtime and Peer Contract
+
+`@fluojs/vite` is a Node.js package with an `engines.node` floor of `>=20.0.0`. Generated non-Deno starters pair that Node baseline with Vite `>=6.2.0` and the Babel peers listed above.
+
+The package root is safe to import before Babel is installed or resolved: importing `@fluojs/vite` and creating `fluoDecoratorsPlugin()` do not load `@babel/core`. Babel is loaded lazily only from Vite's `transform` hook for eligible application `.ts` files, and missing Babel peers are reported from that transform boundary instead of plugin creation.
+
 ## Quick Start
 
 ```ts
@@ -44,6 +52,16 @@ export default defineConfig({
 
 The plugin transforms `.ts` application files with Babel using the `2023-11` decorators proposal and `@babel/preset-typescript`. It strips Vite query suffixes before deciding the file boundary, then skips declaration files, `*.test.ts` or `*.spec.ts` files, `node_modules`, and non-`.ts` files so generated Vitest test files continue to use the dedicated `@fluojs/testing/vitest` transform path. Importing `@fluojs/vite` or creating `fluoDecoratorsPlugin()` does not load `@babel/core`; missing Babel peers are surfaced as transform-time diagnostics for the source file Vite is transforming.
 
+## Decorator Transform Boundary
+
+`@fluojs/vite` owns application build transforms, not Vitest test transforms. Generated non-Deno starters keep the file-boundary split explicit:
+
+1. `vite.config.ts` imports `fluoDecoratorsPlugin()` from `@fluojs/vite`.
+2. The Vite plugin strips query suffixes, accepts only application `.ts` files, lazily loads Babel on the first eligible transform, and runs `@babel/plugin-proposal-decorators` with `{ version: '2023-11' }` plus `@babel/preset-typescript`.
+3. `vitest.config.ts` imports `fluoBabelDecoratorsPlugin()` from `@fluojs/testing/vitest`, so `*.test.ts` and `*.spec.ts` files stay on the testing-specific transform path.
+
+Keep those boundaries separate when customizing generated projects. Re-enabling `experimentalDecorators`, relying on direct esbuild decorator handling, or routing test files through the Vite application transform is outside the documented fluo support contract.
+
 ## Public API
 
 - `fluoDecoratorsPlugin()` — creates the Vite plugin used by generated fluo starter projects.

package/dist/decorators-plugin.d.ts

@@ -1,19 +1,9 @@
 import type { Plugin } from 'vite';
 /**
- * Creates the Vite transform plugin used by fluo starter projects to compile
- * TC39 standard decorator syntax through Babel before Vite bundles the app.
+ * Creates the Vite plugin used by generated fluo starter projects to transform
+ * TypeScript application files that contain TC39 standard decorators.
  *
- * @returns A Vite plugin that transforms TypeScript application files and skips test files.
- *
- * @example
- * ```ts
- * import { fluoDecoratorsPlugin } from '@fluojs/vite';
- * import { defineConfig } from 'vite';
- *
- * export default defineConfig({
- *   plugins: [fluoDecoratorsPlugin()],
- * });
- * ```
+ * @returns A Vite plugin that lazily loads Babel for eligible application `.ts` files.
  */
 export declare function fluoDecoratorsPlugin(): Plugin;
 //# sourceMappingURL=decorators-plugin.d.ts.map

package/dist/decorators-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators-plugin.d.ts","sourceRoot":"","sources":["../src/decorators-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AAoFnD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAsC7C"}
+{"version":3,"file":"decorators-plugin.d.ts","sourceRoot":"","sources":["../src/decorators-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AAiJnD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/decorators-plugin.js

@@ -21,9 +21,12 @@ function createBabelTransformDiagnostic(error, filePath) {
   }
   return new Error(`[fluo-babel-decorators] Failed to resolve a Babel peer dependency while transforming ${filePath}. ` + 'Install @babel/core, @babel/plugin-proposal-decorators, and @babel/preset-typescript in the Vite project. ' + `Original error: ${message}`);
 }
-async function loadBabelCore(filePath) {
+async function importBabelCore() {
+  return await import('@babel/core');
+}
+async function loadBabelCore(filePath, importBabelCoreModule) {
   try {
-    return await import('@babel/core');
+    return await importBabelCoreModule();
   } catch (error) {
     throw createBabelTransformDiagnostic(error, filePath);
   }
@@ -65,9 +68,9 @@ function shouldRequestBabelSourceMaps(config) {
  * });
  * ```
  */
-export function fluoDecoratorsPlugin() {
+function createFluoDecoratorsPlugin(importBabelCoreModule) {
   let shouldGenerateSourceMaps = false;
-  let babelCorePromise;
+  let babelCore;
   return {
     name: 'fluo-babel-decorators',
     configResolved(config) {
@@ -78,9 +81,9 @@ export function fluoDecoratorsPlugin() {
         return null;
       }
       const filePath = readViteFilePath(id);
-      babelCorePromise ??= loadBabelCore(filePath);
-      const babelCore = await babelCorePromise;
-      const result = await babelCore.transformAsync(code, {
+      const loadedBabelCore = babelCore ?? (await loadBabelCore(filePath, importBabelCoreModule));
+      babelCore = loadedBabelCore;
+      const result = await loadedBabelCore.transformAsync(code, {
         babelrc: false,
         configFile: false,
         filename: filePath,
@@ -103,4 +106,25 @@ export function fluoDecoratorsPlugin() {
       };
     }
   };
+}
+
+/**
+ * Creates the Vite plugin used by generated fluo starter projects to transform
+ * TypeScript application files that contain TC39 standard decorators.
+ *
+ * @returns A Vite plugin that lazily loads Babel for eligible application `.ts` files.
+ */
+export function fluoDecoratorsPlugin() {
+  return createFluoDecoratorsPlugin(importBabelCore);
+}
+
+/**
+ * Creates the fluo Vite decorators plugin with an injected Babel importer for regression tests.
+ *
+ * @internal
+ * @param importBabelCoreModule - Async loader used instead of the production `@babel/core` dynamic import.
+ * @returns A Vite plugin that preserves the production transform boundary while allowing tests to control Babel loading.
+ */
+export function createFluoDecoratorsPluginForTesting(importBabelCoreModule) {
+  return createFluoDecoratorsPlugin(importBabelCoreModule);
 }

package/package.json

@@ -8,7 +8,7 @@
     "babel",
     "build-tooling"
   ],
-  "version": "1.0.5",
+  "version": "1.0.7",
   "private": false,
   "license": "MIT",
   "repository": {