Skip to content

docs(core): document loaderFS option #5950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
killagu wants to merge 2 commits into
base: next
Choose a base branch
from
Open

docs(core): document loaderFS option #5950

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad33f24
docs(core): document loaderFS option
killagu May 12, 2026
c8c8345
docs(core): address loaderFS doc review
killagu May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions packages/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Fix grammar: "contain" should be "contains" when referring to the options object.

Suggested change
| 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 |

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Improve the grammar for the inject and filter descriptions to make them more idiomatic and consistent with the rest of the table.

Suggested change
| 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

Expand Down
5 changes: 5 additions & 0 deletions site/docs/advanced/loader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The description of loaderFS should include "JSON reads" for completeness, as the LoaderFS interface provides readJSON. Additionally, using backticks for function and class names improves readability and consistency with other parts of the documentation.

Suggested change
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.
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

You can use `customLoader` instead of `loadToContext` and `loadToApp`.
Expand Down
5 changes: 5 additions & 0 deletions site/docs/zh-CN/advanced/loader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -500,6 +500,11 @@ app.loader.loadToApp(directory, 'model', {
| app/middleware | false |
| app/service | true |

#### loaderFS [LoaderFS]

自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取和模块加载。
默认使用 `RealLoaderFS`，它会委托给本地文件系统，以保持现有运行时行为。

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

建议在 loaderFS 的描述中增加 "JSON 读取"，以保持与英文文档和 LoaderFS 接口定义的一致性。同时，为函数和类名添加反引号以提高可读性。

Suggested change
自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取和模块加载。
默认使用 `RealLoaderFS`，它会委托给本地文件系统，以保持现有运行时行为。
自定义 `loadToApp` 和 `loadToContext` 使用的文件系统边界，用于文件发现、文件状态读取、JSON 读取和模块加载。
默认使用 `RealLoaderFS`，它会委托给本地文件系统，以保持现有运行时行为。


## CustomLoader

`loadToContext` 和 `loadToApp` 方法可以通过 `customLoader` 的配置来替代。
Expand Down
6 changes: 6 additions & 0 deletions wiki/log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
8 changes: 7 additions & 1 deletion wiki/packages/core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---

Expand All @@ -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.