puter.ui.launchApp()

Copy page
Websites Puter Apps Node.js Workers

Launches another app from within your app.

Syntax 

puter.ui.launchApp()
puter.ui.launchApp(appName)
puter.ui.launchApp(appName, args)
puter.ui.launchApp(options)

Parameters

appName (String)

Name of the app. If not provided, a new instance of the current app will be launched.

args (Object)

Arguments to pass to the app. If appName is not provided, these arguments will be passed to the current app.

options (Object)

Option Type Description
name String Name of the app. If not provided, a new instance of the current app will be launched.
args Object Arguments to pass to the app.
background Boolean If true, the app starts with its window hidden. Use it for an app launched to do work instead of being looked at, such as one serving an API to yours over its AppConnection. Defaults to false.
file_paths Array<String> Paths of existing files to open with the launched app.
items Array An array of FSItem objects to open with the launched app.
pseudonym String A pseudonym to launch the app under.

Without background, Puter creates and shows the window before the app's own code runs, so a service app cannot avoid briefly appearing on screen.

A background instance stays private to your app for as long as it is hidden: it has no running mark on its icon, and opening the app from Puter's app list starts a separate, ordinary instance for the user rather than handing them the one you are talking to. It can show itself at any time with puter.ui.showWindow(), and from that moment it is an ordinary window that the user can return to, hide, or close like any other.

A background app closes when the app that launched it closes: it was launched to serve that app, and the user never saw it. Once it has shown itself it keeps running on its own.

Return value

A Promise that will resolve to an AppConnection once the app is launched.

Errors

If the desktop cannot complete the launch, the promise rejects with code: 'ipc_handler_failed' and a message.

Examples

Launch the Editor app 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // launches the Editor app
        puter.ui.launchApp('editor');
    </script>
</body>
</html>

Launch an app in the background

Launching an app in the background to use it as a service, with no window appearing on screen:

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        (async () => {
            const service = await puter.ui.launchApp({
                name: 'contacts',
                args: { service: 'contacts-api' },
                background: true,
            });
            service.on('message', (msg) => console.log('from contacts:', msg));
            service.postMessage({ hello: 'there' });
        })();
    </script>
</body>
</html>

NEXT

parentApp()

PREVIOUS

contextMenu()