From f40f0d1df31530a55919c3e85f5ec11eee17d8bd Mon Sep 17 00:00:00 2001 From: gaoyuan Date: Thu, 4 Jul 2024 18:36:30 +0800 Subject: [PATCH] docs: add get environment context info guide (#2796) Co-authored-by: neverland --- .../docs/en/guide/advanced/environments.mdx | 35 +++++++++++++++++++ website/docs/en/plugins/dev/core.mdx | 2 +- website/docs/en/plugins/dev/hooks.mdx | 7 ++-- .../docs/zh/guide/advanced/environments.mdx | 35 +++++++++++++++++++ website/docs/zh/plugins/dev/core.mdx | 2 +- website/docs/zh/plugins/dev/hooks.mdx | 6 ++-- 6 files changed, 80 insertions(+), 7 deletions(-) diff --git a/website/docs/en/guide/advanced/environments.mdx b/website/docs/en/guide/advanced/environments.mdx index 9f0e04673f..039f5075e9 100644 --- a/website/docs/en/guide/advanced/environments.mdx +++ b/website/docs/en/guide/advanced/environments.mdx @@ -132,3 +132,38 @@ const myPlugin = () => ({ }, }); ``` + +## Get environment context + +[Environment context](/api/javascript-api/types#environmentcontext) is a read-only object that provides some context infos about the current environment. Rsbuild supports obtaining environment context information in plugin hooks. + +For some plugin hooks related to the build environment (such as [modifyBundlerChain](/plugins/dev/hooks#modifybundlerchain) and [modifyRspackConfig](/plugins/dev/hooks#modifyrspackconfig)), Rsbuild supports obtaining the current environment context through the `environment` parameter. + +```ts +const myPlugin = () => ({ + setup: (api) => { + api.modifyBundlerChain((chain, { environment }) => { + const { name, config, entry } = environment; + + if (config.output.minify !== false) { + chain.optimization + .minimizer(CHAIN_ID.MINIMIZER.JS) + .use(SwcJsMinimizerRspackPlugin) + .end(); + } + }); + }, +}); +``` + +For some global plugin hooks (such as [onDevCompileDone](/plugins/dev/hooks#ondevcompiledone), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver), etc.), Rsbuild supports obtaining the context of all environments through the `environments` parameter. + +```ts +const myPlugin = () => ({ + setup: (api) => { + api.onDevCompileDone(({ environments }) => { + const entries = Object.values(environments).map((e) => e.entry); + }); + }, +}); +``` diff --git a/website/docs/en/plugins/dev/core.mdx b/website/docs/en/plugins/dev/core.mdx index 3d00c8bb36..2466c69dcd 100644 --- a/website/docs/en/plugins/dev/core.mdx +++ b/website/docs/en/plugins/dev/core.mdx @@ -99,7 +99,7 @@ For example, if you register both the Foo and Bar plugins mentioned above, the F `api.context` is a read-only object that provides some context information. -The content of `api.context` is exactly the same as `rsbuild.context`, please refer to [rsbuild.context](/api/javascript-api/instance#rsbuild-context). +The content of `api.context` is exactly the same as `rsbuild.context`, please refer to [rsbuild.context](/api/javascript-api/instance#rsbuildcontext). - **Example:** diff --git a/website/docs/en/plugins/dev/hooks.mdx b/website/docs/en/plugins/dev/hooks.mdx index 7d3f7f339e..50a1fb21c8 100644 --- a/website/docs/en/plugins/dev/hooks.mdx +++ b/website/docs/en/plugins/dev/hooks.mdx @@ -196,7 +196,6 @@ const myPlugin = () => ({ ### modifyEnvironmentConfig - Modify the Rsbuild configuration of a specific environment. In the callback function, the config object in the parameters has already been merged with the common Rsbuild configuration. You can directly modify this config object, or you can return a new object to replace it. @@ -267,6 +266,7 @@ To modify the final Rspack config object, you can directly modify the config obj ```ts type ModifyRspackConfigUtils = { + environment: EnvironmentContext; env: NodeEnv; isDev: boolean; isProd: boolean; @@ -312,6 +312,7 @@ This hook only supports modifying the configuration of the non-differentiated pa ```ts type ModifyBundlerChainUtils = { + environment: EnvironmentContext; env: NodeEnv; isDev: boolean; isProd: boolean; @@ -393,8 +394,8 @@ type Context = { * @example 'index.html' */ filename: string; - /** The name of the environment to which this build belongs. */ - environment: string; + /** The environment context for current build. */ + environment: EnvironmentContext; }; function ModifyHTMLTags( diff --git a/website/docs/zh/guide/advanced/environments.mdx b/website/docs/zh/guide/advanced/environments.mdx index 5f7922fe2a..f9aae07deb 100644 --- a/website/docs/zh/guide/advanced/environments.mdx +++ b/website/docs/zh/guide/advanced/environments.mdx @@ -132,3 +132,38 @@ const myPlugin = () => ({ }, }); ``` + +## 获取 environment 上下文 + +[Environment context](/api/javascript-api/types#environmentcontext) 是一个只读对象，提供一些和当前环境有关的上下文信息。Rsbuild 支持在 plugin hook 中获取 environment context 信息。 + +对于一些与构建环境相关的 plugin hooks (如 [modifyBundlerChain](/plugins/dev/hooks#modifybundlerchain)、[modifyRspackConfig](/plugins/dev/hooks#modifyrspackconfig) 等), Rsbuild 支持通过 `environment` 参数获取当前 environment 上下文。 + +```ts +const myPlugin = () => ({ + setup: (api) => { + api.modifyBundlerChain((chain, { environment }) => { + const { name, config, entry } = environment; + + if (config.output.minify !== false) { + chain.optimization + .minimizer(CHAIN_ID.MINIMIZER.JS) + .use(SwcJsMinimizerRspackPlugin) + .end(); + } + }); + }, +}); +``` + +对于一些全局的 plugin hooks (如 [onDevCompileDone](/plugins/dev/hooks#ondevcompiledone)、[onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) 等)， Rsbuild 支持通过 `environments` 参数获取所有环境的上下文。 + +```ts +const myPlugin = () => ({ + setup: (api) => { + api.onDevCompileDone(({ environments }) => { + const entries = Object.values(environments).map((e) => e.entry); + }); + }, +}); +``` diff --git a/website/docs/zh/plugins/dev/core.mdx b/website/docs/zh/plugins/dev/core.mdx index 30a105ca5b..86810d77cb 100644 --- a/website/docs/zh/plugins/dev/core.mdx +++ b/website/docs/zh/plugins/dev/core.mdx @@ -97,7 +97,7 @@ const pluginBar = { `api.context` 是一个只读对象，提供一些上下文信息。 -`api.context` 的内容与 `rsbuild.context` 完全一致，请参考 [rsbuild.context](/api/javascript-api/instance#rsbuild-context)。 +`api.context` 的内容与 `rsbuild.context` 完全一致，请参考 [rsbuild.context](/api/javascript-api/instance#rsbuildcontext)。 - **示例：** diff --git a/website/docs/zh/plugins/dev/hooks.mdx b/website/docs/zh/plugins/dev/hooks.mdx index 3949b64aed..29e72d3c41 100644 --- a/website/docs/zh/plugins/dev/hooks.mdx +++ b/website/docs/zh/plugins/dev/hooks.mdx @@ -265,6 +265,7 @@ const myPlugin = () => ({ ```ts type ModifyRspackConfigUtils = { + environment: EnvironmentContext; env: NodeEnv; isDev: boolean; isProd: boolean; @@ -308,6 +309,7 @@ import RspackChain from '@zh/shared/rspackChain.mdx'; ```ts type ModifyBundlerChainUtils = { + environment: EnvironmentContext; env: NodeEnv; isDev: boolean; isProd: boolean; @@ -390,9 +392,9 @@ type Context = { */ filename: string; /** - * 本次构建所属的环境名称 + * 本次构建的 environment 上下文 */ - environment: string; + environment: EnvironmentContext; }; function ModifyHTMLTags(