bt_app FAQ

bt_app FAQ

Why the window cannot be opened

First run in the project directory:

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:

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:

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:

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:

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:

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:

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.