App

Provides methods to manage application lifecycle.

import { app } from '@mobrowser/api';

Example 

import { app } from '@mobrowser/api';

console.log(app.name)
console.log(app.version)

Properties 

packaged 

readonly packaged: boolean;

Indicates whether the application is packaged (i.e., running in production mode) or running in development mode.

Example 

import { app } from '@mobrowser/api';

if (app.packaged) {
  console.log('Running in production')
}

url 

readonly url: string;

The URL of the application frontend entry point.

It can be different based on whether the application is running in the development or production mode. The value for each mode is configured in the mobrowser.conf.json file in the configurations section.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

const win = new BrowserWindow()
win.browser.loadUrl(app.url)

name 

readonly name: string;

The application name defined in the mobrowser.conf.json file.

version 

readonly version: string;

The application version defined in the mobrowser.conf.json file.

description 

readonly description: string;

The application description defined in the mobrowser.conf.json file.

copyright 

readonly copyright: string;

The application copyright information defined in the mobrowser.conf.json file.

schemes 

readonly schemes: string[];

Custom URL schemes (without ://) declared in mobrowser.conf.json as app.schemes. For example, "demoapp" allows demoapp://… links.

On macOS, these values populate CFBundleURLSchemes when the app bundle is branded.

When non-empty, the runtime registers the app as a handler so other software can open those schemes. Matching activations invoke the app.handle('openUrl', …) handler when it is registered.

launchInfo 

readonly launchInfo: LaunchInfo;

Contains information about the application launch, including whether it is the first run and the version that was previously launched.

Example 

import { app } from '@mobrowser/api';

if (app.launchInfo.isFirstRun) {
  console.log('Welcome!')
}

windows 

readonly windows: AppWindow[];

An array of all currently open application windows. This array is updated automatically as windows are created and closed.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

const win = new BrowserWindow()
win.setTitle('MyApp')
app.windows.forEach(win => console.log(win.title))

theme 

readonly theme: Theme;

The current application theme.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

const win = new BrowserWindow()
if (app.theme === 'dark') {
  win.setTitle('App (Dark Mode)')
}

menu 

readonly menu: Menu;

The application main menu.

trustedOrigins 

readonly trustedOrigins: string[];

Origins trusted by the application.

Trusted origins receive access to app-level capabilities that are otherwise reserved for the app origin. This includes the renderer-to-main RPC bridge (window.__MOBROWSER__.rpc) and automatic permission grants without invoking the requestPermissions handler. Trusted origins are also allowed as top-level in-app navigation targets; other remote origins are blocked by default.

The app renderer may additionally make cross-origin fetch/XMLHttpRequest requests to trusted origins without being blocked by the CORS policy, even when the destination does not send an Access-Control-Allow-Origin header (for example, an OAuth device-code endpoint). CORS remains fully enforced for every origin that is not listed here; the bypass applies only to requests initiated by the app’s own origin toward these destinations. This is intentionally scoped rather than disabling web security globally.

Automatically granted permissions include:

• camera access
• display-capture
• microphone access
• notifications
• persistent-storage access
• clipboard read and write access
• geolocation access
• audio and video capture access

To trust an origin without handling each framework permission request or adding per-handler RPC origin checks, add entries to app.trustedOrigins in mobrowser.conf.json. Each entry has the shape [scheme://][*.]host[:port]:

• Scheme (optional): when present, only that scheme is trusted, e.g. "https://foo.com". When omitted, the host is trusted over both http and https, e.g. "foo.com".
• Host (required): an exact host such as "foo.com" or "127.0.0.1", an IPv6 literal in brackets such as "[::1]", optionally prefixed with a single leading "*." wildcard label.
• Port (optional): an exact port such as ":8000", or ":*" for any port. When omitted, any port is trusted.

A leading "*." matches the subdomains of the host but not the host itself. "*.foo.com" trusts "a.foo.com" and "a.b.foo.com", but not "foo.com". To trust the apex as well, list it separately, e.g. ["*.foo.com", "foo.com"].

URL paths are not part of an origin and are ignored: "https://foo.com/app" is treated as "https://foo.com".

Entries that cannot be expressed as a scoped origin rule are ignored (a warning is logged) rather than widened to something broader than intended. This applies to:

• a bare scheme wildcard, e.g. "https://*" or "http://*";
• a wildcard anywhere other than the single leading label, e.g. "test.*.com", "*.foo.*.bar.com", or "api-*.foo.com";
• a malformed or out-of-range port, e.g. "http://foo.com:99999".

A leading wildcard on a public suffix, e.g. "*.com" or "*.co.uk", is accepted but strongly discouraged: it trusts a huge set of unrelated sites. Scope wildcards to a domain you control, e.g. "*.foo.com".

Example 

"trustedOrigins": [
  "https://foo.com",
  "http://foo.com:8000",
  "*.foo.com",
  "https://*.foo.bar.com",
  "http://127.0.0.1:*"
]

loginItemSettings 

readonly loginItemSettings: LoginItemSettings;

The current login-item settings for the application.

Example 

import { app } from '@mobrowser/api';

if (app.loginItemSettings.openAtLogin) {
  console.log('Launch at login is enabled')
}

permissions 

readonly permissions: AppPermissions;

Provides access to system permissions on macOS and Windows.

On Windows, getStatus() and openSystemSettings() support microphone and camera.

Example 

import { app } from '@mobrowser/api';

const permission = 'microphone'
let status = app.permissions.getStatus(permission)

if (status === 'notDetermined') {
  await app.permissions.request(permission)
  status = app.permissions.getStatus(permission)
}

if (status === 'denied') {
  app.permissions.openSystemSettings(permission)
}

Methods 

setMenu() 

setMenu(menu: Menu): void;

Sets the application main menu.

Example 

import { app } from '@mobrowser/api';

app.setMenu(new Menu({
  items: [
    new MenuItem({
      id: 'quit',
      label: 'Quit',
      action: (item: MenuItem) => {
        app.quit()
      }
    })
  ]
}))

setTheme() 

setTheme(theme: Theme): void;

Sets the application theme.

Example 

import { app } from '@mobrowser/api';

// Set the dark theme
app.setTheme('dark')

// Set the light theme
app.setTheme('light')

// Set the theme of the operating system
app.setTheme('system')

showMessageDialog() 

showMessageDialog(options: MessageDialogOptions): Promise<MessageDialogResult>;

Opens a message dialog with the given options.

Return value 

The result of the message dialog as a promise that resolves to a MessageDialogResult object.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

// Create a new window.
const win = new BrowserWindow()
win.setTitle('MyApp')
win.show()

// Show a message dialog.
const result = await app.showMessageDialog({
  parentWindow: win,
  title: 'Would you like to delete this conversation?',
  message: 'This conversation will be deleted from all of your devices. ' +
    'You cannot undo this action.',
  buttons: [
    { label: 'Cancel', type: 'secondary' },
    { label: 'Delete', type: 'primary' }
  ]
})

if (result.button.type === 'primary') {
  // The 'Delete' button was clicked.
}

showOpenDialog() 

showOpenDialog(options: OpenDialogOptions): Promise<OpenDialogResult>;

Opens a file open dialog with the given options.

Return value 

The result of the file open dialog as a promise that resolves to a OpenDialogResult object.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

// Create a new window.
const win = new BrowserWindow()
win.setTitle('MyApp')
win.show()

// Show a file open dialog.
const result = await app.showOpenDialog({
 parentWindow: win,
 title: 'Open Files',
 defaultPath: '/Users/john/Desktop',
 selectionPolicy: 'files',
 features: {
   allowMultiple: true,
   canCreateDirectories: true
 },
})

if (!result.canceled) {
  console.log('Selected paths: ', result.paths[0])
}

showSaveDialog() 

showSaveDialog(options: SaveDialogOptions): Promise<SaveDialogResult>;

Opens a file save dialog with the given options.

Return value 

The result of the file save dialog as a promise that resolves to a SaveDialogResult object.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

// Create a new window.
const win = new BrowserWindow()
win.setTitle('MyApp')
win.show()

// Show a file save dialog.
const result = await app.showSaveDialog({
  parentWindow: win,
  title: 'Save File',
  defaultPath: '/Users/john/Desktop',
  filters: [{ name: 'Text Files', extensions: ['txt'] }]
})

if (!result.canceled) {
  console.log('Selected path: ', result.path)
}

getPath() 

getPath(name: PathName): FilePath;

Gets the absolute path to a directory identified by the given name.

Return value 

The absolute path to the directory or an empty string if the path is not found.

Example 

import { app } from '@mobrowser/api';

// Get the path to the app resources directory.
const dirPath = app.getPath('appResources')
console.log(dirPath)

quit() 

quit(): void;

Quits the application, closing all windows and terminating the process.

Before anything is closed, the close handler of every open window is invoked with CloseWindowParams.isQuitting set to true. The quit proceeds only once all of them resolve, and is called off if any of them returns 'hide' or 'cancel'.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

const win = new BrowserWindow()
win.show()
const result = await app.showMessageDialog({
  parentWindow: win,
  title: 'Quit',
  message: 'Are you sure you want to quit?',
  buttons: [
    { label: 'Cancel', type: 'secondary' },
    { label: 'Quit', type: 'primary' }
  ]
})
if (result.button.type === 'primary') {
  app.quit()
}

restart() 

restart(): void;

Restarts the application, closing all windows and terminating the process.

The new application instance will use the same working directory and the command line arguments as the current one.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

const win = new BrowserWindow()
win.show()
const result = await app.showMessageDialog({
  parentWindow: win,
  title: 'Restart',
  message: 'Restart to apply the new settings?',
  buttons: [
    { label: 'Later', type: 'secondary' },
    { label: 'Restart', type: 'primary' }
  ]
})
if (result.button.type === 'primary') {
  app.restart()
}

setLoginItemSettings() 

setLoginItemSettings(settings: LoginItemSettings): void;

Configures the application’s login-item settings on Windows and macOS.

Example 

import { app } from '@mobrowser/api';

app.setLoginItemSettings({
  openAtLogin: true,
  args: ['--hidden'], // Windows only
})

checkForUpdate() 

checkForUpdate(source: string): Promise<AppUpdate | undefined | string>;

Checks for an available application update.

Available only on Windows and macOS.

The source must use HTTPS. Plain HTTP is rejected unless it points to localhost, which is permitted for local development only.

Return value 

A promise that resolves to the application update object if an update is available, or undefined if no update is available. The promise rejects if the update check fails.

Example 

import { app, AppUpdate } from '@mobrowser/api';

const result = await app.checkForUpdate('https://app.com/updates')
if (!result) {
  // No update is available or do nothing.
} else if (typeof result === 'string') {
  // An error occurred while checking for updates.
} else {
  // An update is available.
  const appUpdate: AppUpdate = result
  console.log('Update available: ', appUpdate.version)
}

Events 

‘activated’ 

on(event: 'activated', listener: () => void): void;
off(event: 'activated', listener: () => void): void;

Emitted when the application is activated. On macOS, this event can be triggered by various actions, such as clicking the Dock icon or switching to the application using Cmd+Tab. On Windows and Linux, this event is not triggered because these platforms do not have the same concept of application activation.

Example 

import { app, BrowserWindow } from '@mobrowser/api';

app.on('activated', () => {
  if (app.windows.length === 0) {
    const win = new BrowserWindow({
      size: { width: 800, height: 650 },
    })
    win.browser.loadUrl(app.url)
    win.show()
  }
})

‘allWindowsClosed’ 

on(event: 'allWindowsClosed', listener: () => void): void;
off(event: 'allWindowsClosed', listener: () => void): void;

Emitted when all windows have been closed.

If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app. However, if you subscribe, you control whether the app quits or not. For example, you can call app.quit() to quit, or do nothing to keep the app running.

Example 

import { app } from '@mobrowser/api';

app.on('allWindowsClosed', () => {
  // On macOS it is common for applications to stay open
  // until the user explicitly quits.
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

Handlers 

openUrl 

handle(action: 'openUrl', handler: (url: string, queryParams: Record<string, string>) => void): void;
removeHandler(action: 'openUrl'): void;

Invoked when the app is activated via a custom URL scheme associated with the application in mobrowser.conf.json as app.schemes.

A custom URL scheme allows external sources to trigger the application.

myapp://open?file=123&mode=edit

When a user opens such a link:

• If the app is not running → it will be launched
• The URL is passed to the app for handling

You can use this handler to react to the passed URL and perform actions accordingly. For example, you can just activate the app and show a specific window or parse the URL query parameters and perform actions based on them.

This handler covers only URLs that arrive while the app is already running. A URL the app was launched to open is reported instead by {@link LaunchInfo.url | app.launchInfo.url}, which the main script reads synchronously at startup. The two routes are disjoint, on every platform: a launch URL never reaches this handler, and a URL that arrives later never appears in launchInfo.

The handler receives the full URL string (including fragment, if present) and a plain object of decoded query parameters (duplicate keys keep the last value). app.launchInfo.url is the raw string only; parse it with new URL(...) if you need its parts.

Example 

import { app } from '@mobrowser/api';

// URLs that arrive later, while the app is running.
app.handle('openUrl', (url: string, queryParams: Record<string, string>) => {
  console.log('URL:', url, queryParams)
})

// The URL the app was launched to open, known before this line runs.
if (app.launchInfo.url) {
  openWindowFromUrl(app.launchInfo.url)
} else {
  showMainWindow()
}

openFile 

handle(action: 'openFile', handler: (path: string) => void): void;
removeHandler(action: 'openFile'): void;

Registers a handler invoked when the operating system asks a running app to open a file — a Finder or Explorer double-click, “Open with”, a drag onto the dock icon, or open -a <App> file.

This handler covers only files that arrive while the app is already running. A file the app was launched to open is reported instead by {@link LaunchInfo.files | app.launchInfo.files}, which the main script reads synchronously at startup — see the example below. The two routes are disjoint, on every platform: a launch files never reach this handler, and a file that arrives later never appears in launchInfo.

File types are declared per platform under app.bundle.<platform>.fileAssociations in mobrowser.conf.json. Each entry has an extensions array (without the leading dot); some fields are platform-specific:

"bundle": {
  "macOS": {
    "fileAssociations": [
      {
        "extensions": ["myapp"],
        "name": "MyApp File",
        "isPackage": false,
        "icon": "assets/doc.icns"
      }
    ]
  },
  "Windows": {
    "fileAssociations": [
      {
        "extensions": ["myapp"],
        "name": "MyApp File",
        "icon": "assets/doc.ico"
      }
    ]
  },
  "Linux": {
    "fileAssociations": [
      {
        "extensions": ["myapp"],
        "name": "MyApp File",
        "mimeType": "application/x-myapp",
        "icon": "assets/doc.png"
      }
    ]
  }
}

Register the handler as a top-level statement in the main script. A file that arrives while no handler is registered is dropped, not queued — nothing is replayed to a handler registered later.

Example 

import { app } from '@mobrowser/api';

// Files that arrive later, while the app is running.
app.handle('openFile', (path: string) => {
  openFileEditor(path)
})

// Files the app was launched to open, known before this line runs.
if (app.launchInfo.files.length > 0) {
  app.launchInfo.files.forEach(openFileEditor)
} else {
  showMainWindow()
}