From ad33f24e51ae5688a54d68fc25aee0b133cb4381 Mon Sep 17 00:00:00 2001 From: killa Date: Wed, 13 May 2026 02:06:12 +0800 Subject: [PATCH 1/2] docs(core): document loaderFS option --- packages/core/README.md | 25 +++++++++++++------------ site/docs/advanced/loader.md | 5 +++++ site/docs/zh-CN/advanced/loader.md | 5 +++++ wiki/log.md | 6 ++++++ wiki/packages/core.md | 8 +++++++- 5 files changed, 36 insertions(+), 13 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index 72f6768feb..b5e12069ea 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -224,18 +224,19 @@ await this.loadExtend('application', app); ### LoaderOptions -| Param | Type | Description | -| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | -| directory | `String/Array` | directories to be loaded | -| target | `Object` | attach the target object from loaded files | -| match | `String/Array` | match the files when load, default to `**/*.js`(if process.env.EGG\*TYPESCRIPT was true, default to `[ '\*\*/\_.(js | ts)', '!\*_/_.d.ts' ]`) | -| ignore | `String/Array` | ignore the files when load | -| initializer | `Function` | custom file exports, receive two parameters, first is the inject object(if not js file, will be content buffer), second is an `options` object that contain `path` | -| caseStyle | `String/Function` | set property's case when converting a filepath to property list. | -| override | `Boolean` | determine whether override the property when get the same name | -| call | `Boolean` | determine whether invoke when exports is function | -| inject | `Object` | an object that be the argument when invoke the function | -| filter | `Function` | a function that filter the exports which can be loaded | +| Param | Type | Description | +| ----------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| directory | `String/Array` | directories to be loaded | +| target | `Object` | attach the target object from loaded files | +| match | `String/Array` | match the files when load, default to `**/*.js` (if `process.env.EGG_TYPESCRIPT` is true, default to `[ '**/*.(js\|ts)', '!**/*.d.ts' ]`) | +| ignore | `String/Array` | ignore the files when load | +| initializer | `Function` | custom file exports, receive two parameters, first is the inject object (if not js file, will be content buffer), second is an `options` object that contain `path` | +| caseStyle | `String/Function` | set property's case when converting a filepath to property list | +| override | `Boolean` | determine whether override the property when get the same name | +| call | `Boolean` | determine whether invoke when exports is function | +| inject | `Object` | an object that be the argument when invoke the function | +| filter | `Function` | a function that filter the exports which can be loaded | +| loaderFS | `LoaderFS` | loader-facing filesystem abstraction used for discovery, file stats, JSON reads, and module loading | ## Timing diff --git a/site/docs/advanced/loader.md b/site/docs/advanced/loader.md index 81857636ce..3e7f775a0a 100644 --- a/site/docs/advanced/loader.md +++ b/site/docs/advanced/loader.md @@ -495,6 +495,11 @@ Loading different files uses different configurations: | app/middleware | false | | app/service | true | +#### `loaderFS [LoaderFS]` + +Customize the filesystem boundary used by `loadToApp` and `loadToContext` for file discovery, file stats, and module loading. +By default, Egg uses `RealLoaderFS`, which delegates to the local filesystem and keeps the existing runtime behavior. + ## CustomLoader You can use `customLoader` instead of `loadToContext` and `loadToApp`. diff --git a/site/docs/zh-CN/advanced/loader.md b/site/docs/zh-CN/advanced/loader.md index 8afec3f6a7..1dc5d2e41b 100644 --- a/site/docs/zh-CN/advanced/loader.md +++ b/site/docs/zh-CN/advanced/loader.md @@ -500,6 +500,11 @@ app.loader.loadToApp(directory, 'model', { | app/middleware | false | | app/service | true | +#### loaderFS [LoaderFS] + +自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取和模块加载。 +默认使用 `RealLoaderFS`，它会委托给本地文件系统，以保持现有运行时行为。 + ## CustomLoader `loadToContext` 和 `loadToApp` 方法可以通过 `customLoader` 的配置来替代。 diff --git a/wiki/log.md b/wiki/log.md index 50d72d6823..588a53ff0c 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -2,6 +2,12 @@ Dates use the workspace-local Asia/Shanghai calendar date. +## [2026-05-13] docs | sync LoaderFS loader option docs + +- sources touched: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts` +- pages updated: `packages/core/README.md`, `site/docs/advanced/loader.md`, `site/docs/zh-CN/advanced/loader.md`, `wiki/packages/core.md`, `wiki/log.md` +- note: Added the public `loaderFS` LoaderOptions entry to core and site loader docs, and refreshed the core wiki page to point at those docs. + ## [2026-05-07] package | document core LoaderFS boundary - sources touched: `packages/core/src/index.ts`, `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/context_loader.ts`, `packages/core/src/loader/egg_loader.ts` diff --git a/wiki/packages/core.md b/wiki/packages/core.md index 4bf8ae0332..d102a081d3 100644 --- a/wiki/packages/core.md +++ b/wiki/packages/core.md @@ -3,12 +3,15 @@ title: Core Package type: package summary: Loader, lifecycle, and application core primitives used by Egg runtime packages. source_files: + - packages/core/README.md - packages/core/src/index.ts - packages/core/src/loader/loader_fs.ts - packages/core/src/loader/file_loader.ts - packages/core/src/loader/context_loader.ts - packages/core/src/loader/egg_loader.ts -updated_at: 2026-05-07 + - site/docs/advanced/loader.md + - site/docs/zh-CN/advanced/loader.md +updated_at: 2026-05-13 status: active --- @@ -33,3 +36,6 @@ runtime behavior by delegating to `fs.existsSync`, `fs.statSync`, custom `loaderFS`. `EggLoader` passes its loader FS into `loadToApp()` and `loadToContext()` so later bundled loaders can replace file discovery and module loading without changing the public loader call sites. + +The public loader docs now list `loaderFS` with the other `LoaderOptions` so +custom loader filesystem implementations are discoverable for advanced users. From c8c83451b2dca9cb661efd75f015dddd2f7f79e9 Mon Sep 17 00:00:00 2001 From: killa Date: Wed, 13 May 2026 02:14:19 +0800 Subject: [PATCH 2/2] docs(core): address loaderFS doc review --- packages/core/README.md | 6 +++--- site/docs/advanced/loader.md | 2 +- site/docs/zh-CN/advanced/loader.md | 2 +- wiki/log.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index b5e12069ea..8da1cf2126 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -230,12 +230,12 @@ await this.loadExtend('application', app); | target | `Object` | attach the target object from loaded files | | match | `String/Array` | match the files when load, default to `**/*.js` (if `process.env.EGG_TYPESCRIPT` is true, default to `[ '**/*.(js\|ts)', '!**/*.d.ts' ]`) | | ignore | `String/Array` | ignore the files when load | -| initializer | `Function` | custom file exports, receive two parameters, first is the inject object (if not js file, will be content buffer), second is an `options` object that contain `path` | +| initializer | `Function` | custom file exports, receive two parameters, first is the inject object (if not js file, will be content buffer), second is an `options` object that contains `path` | | caseStyle | `String/Function` | set property's case when converting a filepath to property list | | override | `Boolean` | determine whether override the property when get the same name | | call | `Boolean` | determine whether invoke when exports is function | -| inject | `Object` | an object that be the argument when invoke the function | -| filter | `Function` | a function that filter the exports which can be loaded | +| inject | `Object` | an object that is the argument when invoking the function | +| filter | `Function` | a function that filters the exports which can be loaded | | loaderFS | `LoaderFS` | loader-facing filesystem abstraction used for discovery, file stats, JSON reads, and module loading | ## Timing diff --git a/site/docs/advanced/loader.md b/site/docs/advanced/loader.md index 3e7f775a0a..430feca550 100644 --- a/site/docs/advanced/loader.md +++ b/site/docs/advanced/loader.md @@ -497,7 +497,7 @@ Loading different files uses different configurations: #### `loaderFS [LoaderFS]` -Customize the filesystem boundary used by `loadToApp` and `loadToContext` for file discovery, file stats, and module loading. +Customize the filesystem boundary used by `loadToApp` and `loadToContext` for file discovery, file stats, JSON reads, and module loading. By default, Egg uses `RealLoaderFS`, which delegates to the local filesystem and keeps the existing runtime behavior. ## CustomLoader diff --git a/site/docs/zh-CN/advanced/loader.md b/site/docs/zh-CN/advanced/loader.md index 1dc5d2e41b..d357b0d79b 100644 --- a/site/docs/zh-CN/advanced/loader.md +++ b/site/docs/zh-CN/advanced/loader.md @@ -502,7 +502,7 @@ app.loader.loadToApp(directory, 'model', { #### loaderFS [LoaderFS] -自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取和模块加载。 +自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取、JSON 读取和模块加载。 默认使用 `RealLoaderFS`，它会委托给本地文件系统，以保持现有运行时行为。 ## CustomLoader diff --git a/wiki/log.md b/wiki/log.md index 588a53ff0c..c2357dfbe7 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -4,7 +4,7 @@ Dates use the workspace-local Asia/Shanghai calendar date. ## [2026-05-13] docs | sync LoaderFS loader option docs -- sources touched: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts` +- sources referenced: `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/egg_loader.ts` - pages updated: `packages/core/README.md`, `site/docs/advanced/loader.md`, `site/docs/zh-CN/advanced/loader.md`, `wiki/packages/core.md`, `wiki/log.md` - note: Added the public `loaderFS` LoaderOptions entry to core and site loader docs, and refreshed the core wiki page to point at those docs.