The nativeDesktopApp API provides a set of application-level IPC commands that allow web applications to interact with native Native Desktop features such as application control, history management, and app information.

Application-related: Access and modify application-level details.
Navigation-related: Control and retrieve navigation state within the app.
Network-related: Manage network operations and monitor connectivity.
Notification-related: Send notifications to the user from the Native Desktop app.
Window-related: Get or set properties of the application window.

These commands are available only when the app is running inside the Native Desktop environment.

To safely use these APIs, always verify the runtime environment using isInNativeDesktop() from @native-desktop/core.

Custom IPCs

type TNativeDesktopPlugins = Record<string, any>; Represents a key–value map of custom plugin instances. Each key corresponds to a plugin name registered in the Native Desktop runtime, and each value exposes the plugin’s available methods or data. You can access all available plugins through the nativeDesktopPlugins() function. It returns an object containing all registered plugin APIs.

import { isInNativeDesktop, nativeDesktopPlugins } from '@native-desktop/core';

const usePlugins = async () => {
  if (!isInNativeDesktop()) {
    return;
  }

  const plugins = nativeDesktopPlugins();

  if (plugins) {
    console.log('Available plugins:', Object.keys(plugins));
  }
};

Example Usage of a Custom Plugin: Assume you have a plugin registered under the name fileManager that exposes methods like openFile() and saveFile().

if (isInNativeDesktop()) {
  const plugins = nativeDesktopPlugins();

  const fileManager = plugins?.fileManager;

  if (fileManager) {
    const file = await fileManager.openFile('/Users/demo/Documents/sample.txt');
    console.log('File content:', file.content);

    await fileManager.saveFile('/Users/demo/Documents/sample.txt', 'Updated content');
    console.log('File saved successfully!');
  }
}

`getAppUrl(): Promise<string>`

Returns the URL of the current Native Desktop application.

if (isInNativeDesktop()) {
  const appUrl = await window.nativeDesktopApp.getAppUrl();
  console.log('Native Desktop App URL:', appUrl);
}

`quit(): void`

Immediately closes the Native Desktop application.

if (isInNativeDesktop()) {
  window.nativeDesktopApp.quit();
}

`restart(): void`

Restarts the Native Desktop application.

Useful for applying configuration or environment changes.

if (isInNativeDesktop()) {
  window.nativeDesktopApp.restart();
}

`getHistory(): Promise<{ url: string; title: string; timestamp: number }[]>`

Retrieves the browsing history of the current Native Desktop app window.

if (isInNativeDesktop()) {
  const history = await window.nativeDesktopApp.getHistory();
  console.table(history);
}

`filterHistory(filters: { url?: string; title?: string }): Promise<{ url: string; title: string; timestamp: number }[]>`

Filters the application history based on a specific URL or title.

if (isInNativeDesktop()) {
  const filtered = await window.nativeDesktopApp.filterHistory({ title: 'Dashboard' });
  console.table(filtered);
}

`cleanHistory(): void`

Clears all stored browsing history within the current Native Desktop application context.

if (isInNativeDesktop()) {
  window.nativeDesktopApp.cleanHistory();
  console.log('Native Desktop app history cleared');
}

`canGoBack(): Promise<boolean>`

Checks if there is a previous page in the navigation history.

if (isInNativeDesktop()) {
  const canGoBack = await window.nativeDesktopNavigation.canGoBack();
  console.log('Can go back?', canGoBack);
}

`canGoForward(): Promise<boolean>`

Checks if there is a next page available in the navigation history.

if (isInNativeDesktop()) {
  const canGoForward = await window.nativeDesktopNavigation.canGoForward();
  console.log('Can go forward?', canGoForward);
}

`goBack(): void`

Navigates to the previous page in the current Native Desktop window’s history.

if (isInNativeDesktop()) {
  window.nativeDesktopNavigation.goBack();
}

`goForward(): void`

Navigates forward to the next page in the Native Desktop app’s navigation history.

if (isInNativeDesktop()) {
  window.nativeDesktopNavigation.goForward();
}

`cloneWindow(): void`

Creates a duplicate of the current Native Desktop application window, effectively cloning the app’s current state into a new window instance.

if (isInNativeDesktop()) {
  window.nativeDesktopNavigation.cloneWindow();
  console.log('Cloned current Native Desktop window');
}

`getStatus(): Promise<{ online: boolean }>`

Checks the current network connectivity state of the Native Desktop application.

if (isInNativeDesktop()) {
  const status = await window.nativeDesktopNetwork.getStatus();
  console.log('Network status:', status.online ? 'Online' : 'Offline');
}

`onStatusChange(callback: (status: { online: boolean }) => void): void`

Listens for changes in the network connectivity status. The provided callback is triggered whenever the connection goes online or offline.

if (isInNativeDesktop()) {
  window.nativeDesktopNetwork.onStatusChange((status) => {
    console.log('Network changed:', status.online ? 'Online' : 'Offline');
  });
}

`speedTest(): Promise<any>`

Performs a network speed test and returns performance metrics.

if (isInNativeDesktop()) {
  const result = await window.nativeDesktopNetwork.speedTest();
  console.log('Speed test results:', result);
}

`show(options: TNotificationOptions): void`

Displays a native system notification. You can customize the title, body, icon, and add custom action buttons.

if (isInNativeDesktop()) {
  window.nativeDesktopNotification.show({
    title: 'Update Available',
    body: 'A new version of your app is ready to install.',
    icon: '/assets/update-icon.png',
    actions: [{ type: 'button', text: 'Restart Now' }],
  });
}

`setBadge(count: number): void`

Sets an application badge (e.g., dock or taskbar icon counter) to indicate unread messages, notifications, or pending tasks.

if (isInNativeDesktop()) {
  window.nativeDesktopNotification.setBadge(5); // shows "5" badge
}

`clear(): void`

Clears all active notifications and resets the badge counter.

if (isInNativeDesktop()) {
  window.nativeDesktopNotification.clear();
}

`showAlert(options: TAlertOptions): Promise<void>`

Displays a modal alert dialog with customizable title, message, and buttons.

if (isInNativeDesktop()) {
  await window.nativeDesktopNotification.showAlert({
    type: 'info',
    title: 'Welcome',
    message: 'Your project was created successfully!',
    buttons: ['OK'],
  });
}

`showConfirm(options: TConfirmOptions): Promise<number>`

Displays a confirmation dialog with multiple buttons and returns the index of the button the user clicked.

if (isInNativeDesktop()) {
  const choice = await window.nativeDesktopNotification.showConfirm({
    title: 'Confirm Exit',
    message: 'Are you sure you want to quit the application?',
    buttons: ['Cancel', 'Quit'],
  });

  if (choice === 1) {
    console.log('User confirmed quit');
  }
}

`minimize(): void`

Minimizes the current Native Desktop application window.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.minimize();
}

`maximize(): void`

Maximizes the current Native Desktop window to full size.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.maximize();
}

`unmaximize(): void`

Restores the Native Desktop window to its previous (non-maximized) size.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.unmaximize();
}

`close(): void`

Closes the current Native Desktop window.

If it’s the main window, the application will likely quit.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.close();
}

`toggleFullScreen(): void`

Toggles the current window between fullscreen and windowed mode.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.toggleFullScreen();
}

`focus(): void`

Brings the current Native Desktop window to the foreground and focuses it.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.focus();
}

`open(url?: string, config?: any): void`

Opens a new Native Desktop window. You can optionally pass a URL and configuration object (for window options, size, etc.).

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.open('https://docs.nativedesktop.com', {
    width: 1000,
    height: 700,
    resizable: true,
  });
}

`getBounds(): any`

Retrieves the current window’s size and position. Returns an object similar to { x, y, width, height }.

if (isInNativeDesktop()) {
  const bounds = window.nativeDesktopWindow.getBounds();
  console.log('Current window bounds:', bounds);
}

`setBounds(bounds: any): void`

Sets or updates the window’s position and size.

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.setBounds({ width: 1200, height: 800 });
}

`isMaximized(callback: (event: any, state: boolean) => void): any`

Registers a listener to detect changes in the window’s maximized state. The callback receives a state boolean (true = maximized, false = restored).

if (isInNativeDesktop()) {
  window.nativeDesktopWindow.isMaximized((_event, state) => {
    console.log('Window maximized?', state);
  });
}

Quick Start

Getting started

Tips and Tricks

User Guide

IPC Commands

Custom IPCs

`getAppUrl(): Promise<string>`

`quit(): void`

`restart(): void`

`getHistory(): Promise<{ url: string; title: string; timestamp: number }[]>`

`filterHistory(filters: { url?: string; title?: string }): Promise<{ url: string; title: string; timestamp: number }[]>`

`cleanHistory(): void`

Navigation-relates IPCs

`canGoBack(): Promise<boolean>`

`canGoForward(): Promise<boolean>`

`goBack(): void`

`goForward(): void`

`cloneWindow(): void`

`getStatus(): Promise<{ online: boolean }>`

`onStatusChange(callback: (status: { online: boolean }) => void): void`

`speedTest(): Promise<any>`

`show(options: TNotificationOptions): void`

`setBadge(count: number): void`

`clear(): void`

`showAlert(options: TAlertOptions): Promise<void>`

`showConfirm(options: TConfirmOptions): Promise<number>`

`minimize(): void`

`maximize(): void`

`unmaximize(): void`

`close(): void`

`toggleFullScreen(): void`

`focus(): void`

`open(url?: string, config?: any): void`

`getBounds(): any`

`setBounds(bounds: any): void`

`isMaximized(callback: (event: any, state: boolean) => void): any`

Quick Start

Getting started

Tips and Tricks

User Guide

​Custom IPCs

​Application-related IPCs

​getAppUrl(): Promise<string>

​quit(): void

​restart(): void

​getHistory(): Promise<{ url: string; title: string; timestamp: number }[]>

​filterHistory(filters: { url?: string; title?: string }): Promise<{ url: string; title: string; timestamp: number }[]>

​cleanHistory(): void

​Navigation-relates IPCs

​canGoBack(): Promise<boolean>

​canGoForward(): Promise<boolean>

​goBack(): void

​goForward(): void

​cloneWindow(): void

​Network-related IPCs

​getStatus(): Promise<{ online: boolean }>

​onStatusChange(callback: (status: { online: boolean }) => void): void

​speedTest(): Promise<any>

​Notification-related IPCs

​show(options: TNotificationOptions): void

​setBadge(count: number): void

​clear(): void

​showAlert(options: TAlertOptions): Promise<void>

​showConfirm(options: TConfirmOptions): Promise<number>

​Window-related IPCs

​minimize(): void

​maximize(): void

​unmaximize(): void

​close(): void

​toggleFullScreen(): void

​focus(): void

​open(url?: string, config?: any): void

​getBounds(): any

​setBounds(bounds: any): void

​isMaximized(callback: (event: any, state: boolean) => void): any

Custom IPCs

Application-related IPCs

`getAppUrl(): Promise<string>`

`quit(): void`

`restart(): void`

`getHistory(): Promise<{ url: string; title: string; timestamp: number }[]>`

`filterHistory(filters: { url?: string; title?: string }): Promise<{ url: string; title: string; timestamp: number }[]>`

`cleanHistory(): void`

Navigation-relates IPCs

`canGoBack(): Promise<boolean>`

`canGoForward(): Promise<boolean>`

`goBack(): void`

`goForward(): void`

`cloneWindow(): void`

Network-related IPCs

`getStatus(): Promise<{ online: boolean }>`

`onStatusChange(callback: (status: { online: boolean }) => void): void`

`speedTest(): Promise<any>`

Notification-related IPCs

`show(options: TNotificationOptions): void`

`setBadge(count: number): void`

`clear(): void`

`showAlert(options: TAlertOptions): Promise<void>`

`showConfirm(options: TConfirmOptions): Promise<number>`

Window-related IPCs

`minimize(): void`

`maximize(): void`

`unmaximize(): void`

`close(): void`

`toggleFullScreen(): void`

`focus(): void`

`open(url?: string, config?: any): void`

`getBounds(): any`

`setBounds(bounds: any): void`

`isMaximized(callback: (event: any, state: boolean) => void): any`