From f92b9935eca4e5907f98d4b246154349a55cc815 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Tue, 24 Dec 2024 11:23:51 +0800
Subject: [PATCH] docs: add `loaderContext.importModule()` (#8821)

---
 website/docs/en/api/loader-api/context.mdx | 74 ++++++++++++++++++++++
 website/docs/zh/api/loader-api/context.mdx | 74 ++++++++++++++++++++++
 2 files changed, 148 insertions(+)

diff --git a/website/docs/en/api/loader-api/context.mdx b/website/docs/en/api/loader-api/context.mdx
index df2b63ec87fa..1648019d2eb2 100644
--- a/website/docs/en/api/loader-api/context.mdx
+++ b/website/docs/en/api/loader-api/context.mdx
@@ -133,6 +133,80 @@ function getResolve(options: ResolveOptions): resolve;
 
 Create a resolver like `this.resolve`.
 
+## this.importModule()
+
+```ts
+interface ImportModuleOptions {
+  /**
+   * Specify a layer in which this module is placed/compiled
+   */
+  layer?: string;
+  /**
+   * The public path used for the built modules
+   */
+  publicPath?: PublicPath;
+  /**
+   * Target base uri
+   */
+  baseUri?: string;
+}
+
+// with callback
+function importModule<T = any>(
+  request: string,
+  options: ImportModuleOptions | undefined,
+  callback: (err?: null | Error, exports?: T) => any,
+): void;
+// without callback, return Promise
+function importModule<T = any>(
+  request: string,
+  options?: ImportModuleOptions,
+): Promise<T>;
+```
+
+Compile and execute a module at the build time. This is an alternative lightweight solution for the child compiler.
+
+`importModule` will return a Promise if no callback is provided.
+
+```js title="loader.js"
+const path = require('node:path');
+
+module.exports = async function loader(source) {
+  const modulePath = path.resolve(__dirname, 'some-module.ts');
+  const moduleExports = await this.importModule(modulePath, {
+    // optional options
+  });
+
+  const result = someProcessing(source, moduleExports);
+  return result;
+};
+```
+
+Or you can pass a callback to it.
+
+```js title="loader.js"
+const path = require('node:path');
+
+module.exports = function loader(source) {
+  const callback = this.async();
+  const modulePath = path.resolve(__dirname, 'some-module.ts');
+
+  this.importModule(
+    modulePath,
+    // optional options
+    undefined,
+    (err, moduleExports) => {
+      if (err) {
+        return callback(err);
+      }
+
+      const result = someProcessing(source, moduleExports);
+      callback(null, result);
+    },
+  );
+};
+```
+
 ## this.resolve()
 
 ```ts
diff --git a/website/docs/zh/api/loader-api/context.mdx b/website/docs/zh/api/loader-api/context.mdx
index 6a538e3a63ed..fc2d43482ac6 100644
--- a/website/docs/zh/api/loader-api/context.mdx
+++ b/website/docs/zh/api/loader-api/context.mdx
@@ -128,6 +128,80 @@ function getResolve(options: ResolveOptions): resolve;
 
 创建一个类似于 `this.resolve` 的解析函数。
 
+## this.importModule()
+
+```ts
+interface ImportModuleOptions {
+  /**
+   * 指定模块的 layer
+   */
+  layer?: string;
+  /**
+   * 构建模块时使用的 public path
+   */
+  publicPath?: PublicPath;
+  /**
+   * 目标 base uri
+   */
+  baseUri?: string;
+}
+
+// 传入回调函数
+function importModule<T = any>(
+  request: string,
+  options: ImportModuleOptions | undefined,
+  callback: (err?: null | Error, exports?: T) => any,
+): void;
+// 不传入回调函数时，返回 Promise
+function importModule<T = any>(
+  request: string,
+  options?: ImportModuleOptions,
+): Promise<T>;
+```
+
+在构建过程中编译和执行一个模块。这是 child compiler 的轻量级替代方案。
+
+在没有提供回调函数时，`importModule` 会返回一个 Promise。
+
+```js title="loader.js"
+const path = require('node:path');
+
+module.exports = async function loader(source) {
+  const modulePath = path.resolve(__dirname, 'some-module.ts');
+  const moduleExports = await this.importModule(modulePath, {
+    // 可选参数
+  });
+
+  const result = someProcessing(source, moduleExports);
+  return result;
+};
+```
+
+或者你可以传递一个回调函数给它。
+
+```js title="loader.js"
+const path = require('node:path');
+
+module.exports = function loader(source) {
+  const callback = this.async();
+  const modulePath = path.resolve(__dirname, 'some-module.ts');
+
+  this.importModule(
+    modulePath,
+    // 可选参数
+    undefined,
+    (err, moduleExports) => {
+      if (err) {
+        return callback(err);
+      }
+
+      const result = someProcessing(source, moduleExports);
+      callback(null, result);
+    },
+  );
+};
+```
+
 ## this.resolve()
 
 ```ts