# bt_app FAQ

## Why the window cannot be opened
 First run in the project directory:

```bash
./bt_app.exe run
```

 View the application name, running mode, entry file and error message output by the console. If there is neither `app.json` nor `index.html` in the current directory, the initialization boot page will be opened.

## Why entry failed to load
 Check by mode:

- `static`: `entry` must be a relative file within the project, such as `index.html`.
- `server`: `entry` must be a `http://` or `https://` address, and `server.bt` must start the corresponding service.
- `remote`: `entry` must be an accessible `http://` or `https://` address.

The `static` entry cannot write an absolute path and cannot contain `..`.

## Why the icon does not take effect
 Currently `app.icon` only supports the `.ico` file in the project:

```json
{
  "app": {
    "icon": "logo.ico"
  }
}
```

 If the icon does not exist during development and runtime, it will fall back to the built-in icon. If the icon file does not exist during packaging, it will fail directly.

## Why the taskbar icon and exe icon are inconsistent
 The running window icon is loaded by the WebView window, and the packaged exe icon is written to Windows PE resources by the build phase. Please confirm:

- `app.icon` points to the same `.ico`.
- `resources` or automatic resource collection contains this icon.
 - `bt_app.exe build` has been re-executed.
- Windows Explorer may cache old exe icons. You can change the file name or restart Explorer and try again.

## Why the port is occupied
`server` mode will execute `server.bt`. If the `net.listen` bound port is occupied by other processes, the service fails to start and a startup error page will be displayed in the window.

 Processing method:

 - Modify the `bind` port of `server.bt`.
 - Synchronous modification of `app.entry`.
 - Close the process occupying this port.

## What to do if Windows lacks WebView2
`bt_app`’s desktop window relies on WebView2 Runtime. When the window fails to start and prompts a WebView2-related error, install Microsoft Edge WebView2 Runtime and run it again.

## Can remote addresses control local capabilities?
 The current versions of `remote`, `server` and `static` pages will inject `window.bt` and allow calling `window.bt.call()` and window control capabilities. Therefore, the remote address must be a trusted address, and do not point `app.entry` to uncontrolled third-party pages.

## Whether devtools should be turned on during the development stage
 It can be turned on during the development stage to allow WebView to open developer tools:

```json
{
  "dev": {
    "watch": true,
    "delay": 500,
    "devtools": true,
    "console": true
  }
}
```

 The developer tools will not pop up automatically when file changes trigger hot reload; developers must open them manually when debugging the page. After

 is turned on, you can press `F12` or `Ctrl+Shift+I` to open the developer tools, or you can call it on the page:

```js
await window.bt.window.open_devtools()
```

 During the release phase, `dev.devtools` is usually closed, and `dev.console` is set to `false` as needed.

## Will it exit if the script or configuration is written incorrectly during development?
 The development directory will not exit directly due to project errors when running. When `app.json` fails to parse, the entry file is missing, `app.main` is missing, a script error occurs, or a runtime exception occurs, the window will display an error page and continue to monitor file changes; it will automatically reload after repair. Entering the error page will not force the debugging console to pop up, and the console will still be processed according to the last valid `dev.console` configuration.

## Which
 should be used when app.json and index.html exist at the same time? `app.json` will be used first. Only when there is no `app.json` in the root directory and `index.html` exists, the default `app.json` will be automatically generated and run. `<title>` in `index.html` does not overwrite the window title.

## Why the resource cannot be found after packaging
 Check whether `resources` contains the required files or directories:

```json
{
  "resources": [
    "index.html",
    "assets/**"
  ]
}
```

 The `static` entry, `main.bt`, `server.bt`, `app.json` and `app.icon` will be automatically completed. The default configuration generated without `app.json` will also contain `assets/**` for compatibility with common Vue/Vite build products. Other styles, scripts, and image directories referenced in the page must still be explicitly written to `resources`. If `exclude` is used, the final packed set is calculated as `resources - exclude`.

The project does not require `main.bt` if `"main": false` is already set. The old version's default `app.json` may still have `"main.bt"` remaining in `resources`. The new version build will skip this old resource item when the file does not exist; you can also manually delete it from `resources`.

## Why is the Vue3 or Vite project blank after opening it?
 First confirm that there are `index.html` and `assets/` under `dist/`. The first run after putting `bt_app.exe` into `dist/` will generate the default `app.json`, which contains `assets/**`. After re-executing `bt_app.exe build`, the Bundle will collect these resources.

`static` mode will load the default `index.html` entry as `bt://app/` and fall back to the entry HTML for routes without extensions, which is compatible with the root path deployment method of Vue Router `createWebHistory()`. Missing resources with extensions such as `.js`, `.css`, pictures, etc. will not be rolled back, and resource errors will continue to be returned, making it easier to locate packaging omissions.

If the Vue project also has `favicon.ico`, `logo.png`, `static/**` and other files that are not under `assets/`, please fill them in `app.json` and `resources`:

```json
{
  "resources": [
    "index.html",
    "assets/**",
    "favicon.ico"
  ]
}
```

## Why do the login states of dual-open applications affect each other?
WebView login state comes from Browser profile data such as cookies, localStorage, sessionStorage, etc. The default `app.storage` is `app`. The same application name will use the same persistent profile, so the login status will be shared when the same application is opened twice, similar to opening multiple windows under the same user configuration of an ordinary browser.

If you need two processes to not affect each other, for example, you can log in to two accounts on the same system at the same time, change `app.storage` to `private`:

```json
{
  "app": {
    "storage": "private"
  }
}
```

`private` mode will create a unique temporary profile every time it is started. Dual-open processes will not share Cookie/localStorage, so you can log in to different accounts at the same time. If you need to restore the behavior of all bt_apps in the old version sharing a global profile, you can set it to `global`.