feat(rspeedy/core): support cli flag --environment (#462)

<!--
  Thank you for submitting a pull request!

We appreciate the time and effort you have invested in making these
changes. Please ensure that you provide enough information to allow
others to review your pull request.

Upon submission, your pull request will be automatically assigned with
reviewers.

If you want to learn more about contributing to this project, please
visit:
https://github.com/lynx-family/lynx-stack/blob/main/CONTRIBUTING.md.
-->

## Summary

<!-- Can you explain the reasoning behind implementing this change? What
problem or issue does this pull request resolve? -->

<!-- It would be helpful if you could provide any relevant context, such
as GitHub issues or related discussions. -->

As one of several PRs addressing issue #304

Support cli option `--environment` to specify the name of environment to
build.

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).

Author: gaoachao

.changeset/ninety-zoos-dream.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/rspeedy": patch
+---
+
+Support cli option `--environment` to specify the name of environment to build

packages/rspeedy/core/etc/rspeedy.api.md

@@ -71,11 +71,12 @@ export interface Config {
 export type ConsoleType = 'log' | 'warn' | 'error' | 'info' | 'debug' | 'profile' | 'profileEnd' | (string & Record<never, never>);
 
 // @public
-export function createRspeedy({ cwd, rspeedyConfig, loadEnv }: CreateRspeedyOptions): Promise<RspeedyInstance>;
+export function createRspeedy({ cwd, rspeedyConfig, loadEnv, environment }: CreateRspeedyOptions): Promise<RspeedyInstance>;
 
 // @public
 export interface CreateRspeedyOptions {
     cwd?: string;
+    environment?: CreateRsbuildOptions['environment'];
     loadEnv?: CreateRsbuildOptions['loadEnv'];
     rspeedyConfig?: Config;
 }

packages/rspeedy/core/src/cli/build.ts

@@ -6,12 +6,15 @@ import { logger } from '@rsbuild/core'
 import type { Command } from 'commander'
 
 import type { CommonOptions } from './commands.js'
+import type { CreateRspeedyOptions } from '../create-rspeedy.js'
 import { exit } from './exit.js'
 import { loadConfig } from '../config/loadConfig.js'
 import { createRspeedy } from '../create-rspeedy.js'
 import { isCI } from '../utils/is-ci.js'
 
-export type BuildOptions = CommonOptions
+export type BuildOptions = CommonOptions & {
+  environment?: string[] | undefined
+}
 
 export async function build(
   this: Command,
@@ -28,13 +31,20 @@ export async function build(
       configPath: buildOptions.config,
     })
 
-    const rspeedy = await createRspeedy({
+    const options: CreateRspeedyOptions = {
       cwd,
       rspeedyConfig,
-      ...(buildOptions.envMode
-        ? { loadEnv: { mode: buildOptions.envMode } }
-        : {}),
-    })
+    }
+
+    if (buildOptions.envMode) {
+      options.loadEnv = { mode: buildOptions.envMode }
+    }
+
+    if (buildOptions.environment) {
+      options.environment = buildOptions.environment
+    }
+
+    const rspeedy = await createRspeedy(options)
 
     await rspeedy.build()
   } catch (error) {

packages/rspeedy/core/src/cli/commands.ts

@@ -46,6 +46,10 @@ export function apply(program: Command): Command {
   const buildCommand = program.command('build')
   buildCommand
     .description('Build the project in production mode')
+    .option(
+      '--environment <name...>',
+      'specify the name of environment to build',
+    )
     .action(
       (buildOptions: BuildOptions) =>
         import('./build.js').then(({ build }) =>
@@ -59,6 +63,10 @@ export function apply(program: Command): Command {
       'Run the dev server and watch for source file changes while serving.',
     )
     .option('--base <base>', 'specify the base path of the server')
+    .option(
+      '--environment <name...>',
+      'specify the name of environment to build',
+    )
     .action(
       (devOptions: DevOptions) =>
         import('./dev.js').then(({ dev }) =>

packages/rspeedy/core/src/cli/dev.ts

@@ -11,10 +11,12 @@ import color from 'picocolors'
 import type { CommonOptions } from './commands.js'
 import { loadConfig, resolveConfigPath } from '../config/loadConfig.js'
 import { createRspeedy } from '../create-rspeedy.js'
+import type { CreateRspeedyOptions } from '../create-rspeedy.js'
 import { exit } from './exit.js'
 
 export interface DevOptions extends CommonOptions {
   base?: string | undefined
+  environment?: string[] | undefined
 }
 
 export async function dev(
@@ -63,13 +65,20 @@ export async function dev(
       },
     )
 
-    const rspeedy = await createRspeedy({
+    const options: CreateRspeedyOptions = {
       cwd,
       rspeedyConfig,
-      ...(devOptions.envMode
-        ? { loadEnv: { mode: devOptions.envMode } }
-        : {}),
-    })
+    }
+
+    if (devOptions.envMode) {
+      options.loadEnv = { mode: devOptions.envMode }
+    }
+
+    if (devOptions.environment) {
+      options.environment = devOptions.environment
+    }
+
+    const rspeedy = await createRspeedy(options)
 
     const server = await rspeedy.createDevServer()
 

packages/rspeedy/core/src/create-rspeedy.ts

@@ -47,6 +47,14 @@ export interface CreateRspeedyOptions {
    * @defaultValue true
    */
   loadEnv?: CreateRsbuildOptions['loadEnv']
+  /**
+   * Only build specified environments.
+   * For example, passing `['lynx']` will only build the `lynx` environment.
+   * If not specified or passing an empty array, all environments will be built.
+   * @see https://rsbuild.dev/guide/advanced/environments#build-specified-environment
+   * @defaultValue []
+   */
+  environment?: CreateRsbuildOptions['environment']
 }
 /**
  * The `createRspeedy` method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime.
@@ -68,7 +76,7 @@ export interface CreateRspeedyOptions {
  * @public
  */
 export async function createRspeedy(
-  { cwd = process.cwd(), rspeedyConfig = {}, loadEnv = true }:
+  { cwd = process.cwd(), rspeedyConfig = {}, loadEnv = true, environment = [] }:
     CreateRspeedyOptions,
 ): Promise<RspeedyInstance> {
   const config = applyDefaultRspeedyConfig(rspeedyConfig)
@@ -78,6 +86,7 @@ export async function createRspeedy(
       cwd,
       loadEnv,
       rsbuildConfig: toRsbuildConfig(config) as RsbuildConfig,
+      environment,
     }),
     import('./plugins/index.js'),
   ])

packages/rspeedy/core/test/cli/config.test.ts

@@ -69,3 +69,39 @@ describe('rspeedy config test', () => {
     )
   })
 })
+
+describe('rspeedy environment test', () => {
+  const fixturesRoot = join(
+    dirname(fileURLToPath(import.meta.url)),
+    'fixtures',
+  )
+
+  test.each([
+    { name: 'web only', environment: ['web'], expected: ['web'] },
+    { name: 'lynx only', environment: ['lynx'], expected: ['lynx'] },
+    {
+      name: 'web + lynx',
+      environment: ['web', 'lynx'],
+      expected: ['web', 'lynx'],
+    },
+    { name: 'empty array', environment: [], expected: ['web', 'lynx'] },
+  ])(
+    'test environment combinations - $name',
+    async ({ environment, expected }) => {
+      const root = join(fixturesRoot, 'environment')
+      const rsbuild = await createRspeedy({
+        cwd: root,
+        rspeedyConfig: {
+          environments: {
+            web: {},
+            lynx: {},
+          },
+        },
+        environment,
+      })
+      const configs = await rsbuild.initConfigs()
+      expect(configs).toHaveLength(expected.length)
+      expect(configs.map(c => c.name)).toEqual(expected)
+    },
+  )
+})

packages/rspeedy/core/test/cli/fixtures/environment/lynx.config.js

@@ -0,0 +1 @@
+

website/docs/en/guide/cli.md

@@ -64,10 +64,11 @@ The `rspeedy dev` command is used to start a local dev server and compile the so
 Usage: rspeedy dev [options]
 
 Options:
-  -b --base <base>      specify the base path of the server
-  -c --config <config>  specify the configuration file, can be a relative or absolute path
-  --env-mode <mode>     specify the env mode to load the .env.[mode] file
-  -h, --help            display help for command
+  -b --base <base>          specify the base path of the server
+  -c --config <config>      specify the configuration file, can be a relative or absolute path
+  --env-mode <mode>         specify the env mode to load the .env.[mode] file
+  --environment <name...>   specify the name of environment to build
+  -h, --help                display help for command
 ```
 
 The dev server will restart automatically when the content of the configuration file is modified.
@@ -82,9 +83,10 @@ The `rspeedy build` command will build the outputs for production in the `dist/`
 Usage: rspeedy build [options]
 
 Options:
-  -c --config <config>  specify the configuration file, can be a relative or absolute path
-  --env-mode <mode>     specify the env mode to load the .env.[mode] file
-  -h, --help            display help for command
+  -c --config <config>      specify the configuration file, can be a relative or absolute path
+  --env-mode <mode>         specify the env mode to load the .env.[mode] file
+  --environment <name...>   specify the name of environment to build
+  -h, --help                display help for command
 ```
 
 ## rspeedy preview

website/docs/zh/guide/cli.md

@@ -64,10 +64,11 @@ Commands:
 Usage: rspeedy dev [options]
 
 Options:
-  -b --base <base>      specify the base path of the server
-  -c --config <config>  specify the configuration file, can be a relative or absolute path
-  --env-mode <mode>     specify the env mode to load the .env.[mode] file
-  -h, --help            display help for command
+  -b --base <base>          specify the base path of the server
+  -c --config <config>      specify the configuration file, can be a relative or absolute path
+  --env-mode <mode>         specify the env mode to load the .env.[mode] file
+  --environment <name...>   specify the name of environment to build
+  -h, --help                display help for command
 ```
 
 当配置文件内容发生修改时，开发服务器会自动重启。
@@ -82,9 +83,10 @@ Options:
 Usage: rspeedy build [options]
 
 Options:
-  -c --config <config>  specify the configuration file, can be a relative or absolute path
-  --env-mode <mode>     specify the env mode to load the .env.[mode] file
-  -h, --help            display help for command
+  -c --config <config>      specify the configuration file, can be a relative or absolute path
+  --env-mode <mode>         specify the env mode to load the .env.[mode] file
+  --environment <name...>   specify the name of environment to build
+  -h, --help                display help for command
 ```
 
 ## rspeedy preview