> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Multi-environment builds

Rsbuild can build outputs for multiple environments in a single run. Use [environments](/config/environments.md) to build them in parallel and set a separate Rsbuild config for each one.

## What is an environment

The `environment` refers to the runtime environment for build output. Common environments include browsers, Node.js, and Workers. Rsbuild allows you to define custom environment names and set build options for each environment individually.

A typical scenario is server-side rendering (SSR). You can define two environments, `web` and `node`, where the build targets ([output.target](/config/output/target.md)) are `web` and `node`. These are used for client-side rendering (CSR) and server-side rendering (SSR) scenarios.

You can also define different environments for the same build target, for example:

- Define `rsc` and `ssr` environments, both targeting `node`, used separately for React Server Components and SSR.
- Define `desktop` and `mobile` environments, both targeting `web`, used separately for desktop and mobile browsers.

Without the `environments` configuration, you would need to define multiple configurations for these scenarios and run multiple independent Rsbuild builds. With `environments`, you can build every output in a single Rsbuild run (Rsbuild achieves this using Rspack's [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler)).

In Rsbuild, each `environment` is associated with an Rsbuild configuration, an Rspack configuration, and a set of build outputs. Plugin authors can tailor the build for a specific environment—modifying configs, registering or removing plugins, adjusting Rspack rules, or inspecting asset information—based on the environment name.

## Environment configs

Rsbuild supports defining different Rsbuild configurations for each environment through [environments](/config/environments.md).

For example, if your project needs SSR support, you need to define different configurations for the client and server. You can define web and node environments.

```ts title="rsbuild.config.ts"
export default {
  environments: {
    // Configure the web environment for browsers
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        // Use 'web' target for the browser outputs
        target: 'web',
        distPath: {
          root: 'dist/client',
        },
      },
      resolve: {
        alias: {
          '@common': './src/client/common',
        },
      },
    },
    // Configure the node environment for SSR
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        // Use 'node' target for the Node.js outputs
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
      resolve: {
        alias: {
          '@common': './src/server/common',
        },
      },
    },
  },
};
```

### Config merging

If you configure `environments`, Rsbuild will merge the config in `environments` with the outer base config. When merging, the config in `environments` has higher priority.

In the example above, after merging the configs, Rsbuild generates two standalone environment configs for building web and node environments.

- **web environments config**: Generated by merging base config with `environments.web`
- **node environments config**: Generated by merging base config with `environments.node`

Then, Rsbuild will use these environment configurations to internally generate two Rspack configs and execute a single build using Rspack’s MultiCompiler.

### Debug config

When you execute the command `npx rsbuild inspect` in the project root directory, you will see the following output:

- `rsbuild.config.[name].mjs`: The Rsbuild config used for a certain environment during build.
- `rspack.config.[name].mjs`: The Rspack config corresponding to a certain environment when building.

```bash
➜ npx rsbuild inspect

config inspection completed, generated files:

  - Rsbuild config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
  - Rsbuild config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
  - Rspack config (web): /project/dist/.rsbuild/rspack.config.web.mjs
  - Rspack config (node): /project/dist/.rsbuild/rspack.config.node.mjs
```

## Default environment

When `environments` is not specified, Rsbuild creates an environment by default with the same name as the current target type (the value of [output.target](/config/output/target.md)).

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'web',
  },
};
```

The above config is equivalent to a simplification of the following config:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
  },
};
```

## Build a specific environment

By default, Rsbuild will build all environments in the Rsbuild configuration when you execute `rsbuild dev` or `rsbuild build`. You can build only the specified environments with `--environment <name>`.

```bash
# Build for all environments by default
rsbuild

# Build for the web environment
rsbuild --environment web

# Build for the web and ssr environments
rsbuild --environment web --environment node

# Building multiple environments can be shortened to:
rsbuild --environment web,node
```

## Add plugins for specified environment \{#plugins-specified-environment}

Plugins configured through the [plugins](/config/plugins.md) field support running in all environments. If you want a plugin to run only in a specified environment, you can configure the plugin in the specified `environment`.

For example, enable the React plugin only in the web environment:

```ts title="rsbuild.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';

export default {
  environments: {
    web: {
      output: {
        target: 'web',
        distPath: {
          root: 'dist/client',
        },
      },
      plugins: [pluginReact()],
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

If you are a plugin developer, you can view [Developing environment plugins](/plugins/dev/index.md#environment-plugin) for details.

## Configuring output directories

When building for multiple environments, we recommend configuring separate, non-overlapping output directories for each environment. This prevents output files with the same name from overwriting each other and keeps server output outside the web asset directory.

You can use [output.distPath.root](/config/output/dist-path.md) to set independent output root directories for each environment.

For example, output the web bundles to `dist/client` and the node bundles to `dist/server`:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        distPath: {
          root: 'dist/client',
        },
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

## Plugin API

### Update environment config

Rsbuild supports modifying or adding environment config through the [modifyRsbuildConfig](/plugins/dev/hooks.md#modifyrsbuildconfig) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
      return mergeRsbuildConfig(config, {
        environments: {
          web1: {
            source: {
              entry: {
                index: './src/web1/index',
              },
            },
          },
        },
      });
    });
  },
});
```

### Configuring a specific environment

Rsbuild supports modifying the Rsbuild config of a specific environment through the [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name !== 'web') {
        return config;
      }
      config.html.title = 'My Default Title';
    });
  },
});
```

## Environment context

[Environment context](/api/javascript-api/environment-api.md#environment-context) 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 [modifyRspackConfig](/plugins/dev/hooks.md#modifyrspackconfig) and [modifyBundlerChain](/plugins/dev/hooks.md#modifybundlerchain)), Rsbuild supports obtaining the current environment context through the `environment` parameter.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRspackConfig((rspackConfig, { environment }) => {
      if (environment.name === 'node') {
        // do some thing
      }
    });
  },
});
```

For some global plugin hooks (such as [onAfterDevCompile](/plugins/dev/hooks.md#onafterdevcompile), [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver), etc.), Rsbuild supports obtaining the context of all environments through the `environments` parameter.

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterDevCompile(({ environments }) => {
      for (const name in environments) {
        console.log(name, environments[name]);
      }
    });
  },
});
```

## Environment API

Rsbuild server provides a series of APIs related to the build environment. Users can operate the build artifacts in a specific environment on the server side through the Rsbuild [environment API](/api/javascript-api/environment-api.md#environment-api).

You can use the environment API in [server.setup](/config/server/setup.md) or [Custom Server](/api/javascript-api/instance.md#rsbuildcreatedevserver).

For example, you can quickly implement an SSR function through the Rsbuild environment API in development mode:

```ts
import express from 'express';
import { createRsbuild, loadConfig } from '@rsbuild/core';

const serverRender =
  ({ environments }) =>
  async (_req, res) => {
    const bundle = await environments.node.loadBundle('index');
    const rendered = bundle.render();
    const template = await environments.web.getTransformedHtml('index');
    const html = template.replace('<!--app-content-->', rendered);

    res.writeHead(200, {
      'Content-Type': 'text/html',
    });
    res.end(html);
  };

export async function startDevServer() {
  const { content } = await loadConfig();

  // Init Rsbuild
  const rsbuild = await createRsbuild({
    config: content,
  });

  const app = express();

  // Create Rsbuild dev server instance
  const rsbuildServer = await rsbuild.createDevServer();

  const serverRenderMiddleware = serverRender(rsbuildServer);

  app.get('/', async (req, res, next) => {
    try {
      await serverRenderMiddleware(req, res, next);
    } catch (err) {
      logger.error('SSR render error, downgrade to CSR...');
      logger.error(err);
      next();
    }
  });

  // Apply Rsbuild’s built-in middleware
  app.use(rsbuildServer.middlewares);

  // ...
}
```

For detailed usage, please refer to: [SSR + Express Example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/ssr-express).

## Build order

By default, Rsbuild builds all environments in parallel.

To control the build order between different environments, you can set build dependencies through Rspack's [dependencies](https://rspack.rs/config/other-options#dependencies) configuration.

For example, if you need to build the `web` environment first, then build the `node` environment, you can add the following configuration:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      tools: {
        rspack: {
          name: 'foo',
        },
      },
    },
    node: {
      tools: {
        rspack: {
          dependencies: ['foo'],
        },
      },
    },
  },
};
```

We can use a simple plugin to test the build order of multiple environments:

```ts
const testPlugin: RsbuildPlugin = {
  name: 'test-plugin',
  setup(api) {
    api.onBeforeEnvironmentCompile(({ environment }) => {
      console.log('build start:', environment.name);
    });

    api.onAfterEnvironmentCompile(({ stats, environment }) => {
      console.log('build done:', environment.name);
      console.log('stats', stats);
    });
  },
};

// The plugin will output:
// - build start: web
// - build done: web
// - stats: { ... }
// - build start: node
// - build done: node
// - stats: { ... }
```