Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
58 changes: 43 additions & 15 deletions website/docs/en/config/server/open.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ type Open =

- Open the project's default preview page, which defaults to `http://localhost:<port>`. If [server.host](/config/server/host) is configured, it defaults to `http://<host>:<port>`.

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: true,
Expand All @@ -35,7 +35,7 @@ export default {

- Open the specified page:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://localhost:3000',
Expand All @@ -45,7 +45,7 @@ export default {

- Open the specified path, equivalent to `http://localhost:<port>/home`:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: '/home',
Expand All @@ -55,7 +55,7 @@ export default {

- Open multiple pages:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: ['/', '/about'],
Expand All @@ -65,7 +65,7 @@ export default {

- Open a non-localhost URL (used with proxy):

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://www.example.com',
Expand All @@ -82,19 +82,42 @@ To avoid `server.open` becoming invalid due to port changes, you can use one of
- Enable [server.strictPort](/config/server/strict-port).
- Use the `<port>` placeholder to refer to the current port number. Rsbuild will replace the placeholder with the actual port number it is listening on.

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://localhost:<port>/home',
},
};
```

## Open the specified browser
## Specify browser

Rsbuild by default will open the page in the system's default browser.
Rsbuild opens pages in the system default browser by default, and also supports specifying which browser to use when starting the dev server through the `BROWSER` environment variable.

On macOS, you can open the specified browser when dev server starts, by set environment variable `BROWSER`, support values:
### Browser name

Rsbuild uses the [open](https://github.com/sindresorhus/open) library to open the browser, you can refer to its [app options](https://github.com/sindresorhus/open?tab=readme-ov-file#app) to configure the value of `BROWSER`.

On different operating systems, you need to set the app name differently, take opening Chrome as an example:

```bash
# macOS
BROWSER="google chrome" npx rsbuild dev

# Linux
BROWSER="google-chrome" npx rsbuild dev

# Windows
# You need to use cross-env to set the environment variable
npm i cross-env -D
cross-env BROWSER="chrome" npx rsbuild dev
```

### AppleScript

On macOS, Rsbuild also supports opening the browser through AppleScript, which allows you to reuse existing browser tabs to open pages.

The following are the browser names supported by AppleScript:

- Google Chrome Canary
- Google Chrome Dev
Expand All @@ -108,18 +131,23 @@ On macOS, you can open the specified browser when dev server starts, by set envi
For example:

```bash
BROWSER="Google Chrome Canary" npx rsbuild dev --open
BROWSER="Google Chrome Canary" npx rsbuild dev
```

:::tip
You can set `BROWSER` in the local [.env.local](/guide/advanced/env-vars#env-file) file, which helps avoid impacting other developers.
:::
### Configure env variable

You can set the `BROWSER` environment variable in the local [.env.local](/guide/advanced/env-vars#env-file) file, so you don't need to manually set the environment variable every time you start the dev server, and it also avoids affecting other developers in the project.

```bash
# .env.local
BROWSER=chrome
```

## Callback

By using `open.before`, you can trigger a callback function before opening the page.

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: {
Expand All @@ -133,7 +161,7 @@ export default {

When using `open.before`, the page URLs can be configured via `open.target`.

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: {
Expand Down
58 changes: 43 additions & 15 deletions website/docs/zh/config/server/open.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ type Open =

- 打开项目的默认页面,默认为 `http://localhost:<port>`。如果配置了 [server.host](/config/server/host),则默认为 `http://<host>:<port>`。

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: true,
Expand All @@ -35,7 +35,7 @@ export default {

- 打开指定的页面:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://localhost:3000',
Expand All @@ -45,7 +45,7 @@ export default {

- 打开指定的路径,等价于 `http://localhost:<port>/home`:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: '/home',
Expand All @@ -55,7 +55,7 @@ export default {

- 打开多个页面:

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: ['/', '/about'],
Expand All @@ -65,7 +65,7 @@ export default {

- 打开一个非 localhost URL(配合 proxy 使用):

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://www.example.com',
Expand All @@ -82,19 +82,42 @@ Rsbuild server 监听的端口号可能会发生变更。比如,当端口被
- 开启 [server.strictPort](/config/server/strict-port)。
- 使用 `<port>` 占位符来指代当前端口号,Rsbuild 会将占位符替换为实际监听的端口号。

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: 'http://localhost:<port>/home',
},
};
```

## 打开指定浏览器
## 指定浏览器

Rsbuild 默认会在当前系统的默认浏览器中打开页面
Rsbuild 默认在系统默认浏览器中打开页面,同时也支持通过环境变量 `BROWSER` 来指定 dev server 启动时要使用的浏览器

在 macOS 上,通过设置环境变量 `BROWSER`,你可以指定 dev server 在启动时打开的浏览器,支持如下的值:
### 浏览器名称

Rsbuild 基于 [open](https://github.com/sindresorhus/open) 库来打开浏览器,你需要参考它的 [app 选项](https://github.com/sindresorhus/open?tab=readme-ov-file#app) 来配置 `BROWSER` 的值。

在不同的操作系统上,你需要设置的 app name 是不同的,以打开 Chrome 为例:

```bash
# macOS
BROWSER="google chrome" npx rsbuild dev

# Linux
BROWSER="google-chrome" npx rsbuild dev

# Windows
# 需要使用 cross-env 来设置环境变量
npm i cross-env -D
cross-env BROWSER="chrome" npx rsbuild dev
```

### AppleScript

在 macOS 上,Rsbuild 还额外支持通过 AppleScript 来打开浏览器,这允许你复用已有的浏览器标签页来打开页面。

以下是 AppleScript 支持的浏览器名称:

- Google Chrome Canary
- Google Chrome Dev
Expand All @@ -108,18 +131,23 @@ Rsbuild 默认会在当前系统的默认浏览器中打开页面。
比如:

```bash
BROWSER="Google Chrome Canary" npx rsbuild dev --open
BROWSER="Google Chrome Canary" npx rsbuild dev
```

:::tip
你可以将 `BROWSER` 设置在本地的 [.env.local](/guide/advanced/env-vars#env-文件) 文件中,这样能够避免影响其他开发者。
:::
### 环境变量配置

你可以将 `BROWSER` 设置在本地的 [.env.local](/guide/advanced/env-vars#env-文件) 文件中,这样能够避免每次启动 dev server 时都需要手动设置环境变量,同时也能避免影响项目的其他开发者。

```bash
# .env.local
BROWSER=chrome
```

## 回调函数

通过 `open.before`,可以在打开页面之前触发一个回调函数。

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: {
Expand All @@ -133,7 +161,7 @@ export default {

当使用 `open.before` 时,你可以通过 `open.target` 来配置页面的 URLs。

```js
```ts title="rsbuild.config.ts"
export default {
server: {
open: {
Expand Down
Loading