index.d.ts (5041B)
1 import {type ChildProcess} from 'node:child_process'; 2 3 export type Options = { 4 /** 5 Wait for the opened app to exit before fulfilling the promise. If `false` it's fulfilled immediately when opening the app. 6 7 Note that it waits for the app to exit, not just for the window to close. 8 9 On Windows, you have to explicitly specify an app for it to be able to wait. 10 11 @default false 12 */ 13 readonly wait?: boolean; 14 15 /** 16 __macOS only__ 17 18 Do not bring the app to the foreground. 19 20 @default false 21 */ 22 readonly background?: boolean; 23 24 /** 25 __macOS only__ 26 27 Open a new instance of the app even it's already running. 28 29 A new instance is always opened on other platforms. 30 31 @default false 32 */ 33 readonly newInstance?: boolean; 34 35 /** 36 Specify the `name` of the app to open the `target` with, and optionally, app `arguments`. `app` can be an array of apps to try to open and `name` can be an array of app names to try. If each app fails, the last error will be thrown. 37 38 The app name is platform dependent. Don't hard code it in reusable modules. For example, Chrome is `google chrome` on macOS, `google-chrome` on Linux and `chrome` on Windows. If possible, use `apps` which auto-detects the correct binary to use. 39 40 You may also pass in the app's full path. For example on WSL, this can be `/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe` for the Windows installation of Chrome. 41 42 The app `arguments` are app dependent. Check the app's documentation for what arguments it accepts. 43 */ 44 readonly app?: App | readonly App[]; 45 46 /** 47 Allow the opened app to exit with nonzero exit code when the `wait` option is `true`. 48 49 We do not recommend setting this option. The convention for success is exit code zero. 50 51 @default false 52 */ 53 readonly allowNonzeroExitCode?: boolean; 54 }; 55 56 export type OpenAppOptions = { 57 /** 58 Arguments passed to the app. 59 60 These arguments are app dependent. Check the app's documentation for what arguments it accepts. 61 */ 62 readonly arguments?: readonly string[]; 63 } & Omit<Options, 'app'>; 64 65 export type AppName = 66 | 'chrome' 67 | 'firefox' 68 | 'edge' 69 | 'browser' 70 | 'browserPrivate'; 71 72 export type App = { 73 name: string | readonly string[]; 74 arguments?: readonly string[]; 75 }; 76 77 /** 78 An object containing auto-detected binary names for common apps. Useful to work around cross-platform differences. 79 80 @example 81 ``` 82 import open, {apps} from 'open'; 83 84 await open('https://google.com', { 85 app: { 86 name: apps.chrome 87 } 88 }); 89 ``` 90 */ 91 export const apps: Record<AppName, string | readonly string[]>; 92 93 /** 94 Open stuff like URLs, files, executables. Cross-platform. 95 96 Uses the command `open` on macOS, `start` on Windows and `xdg-open` on other platforms. 97 98 There is a caveat for [double-quotes on Windows](https://github.com/sindresorhus/open#double-quotes-on-windows) where all double-quotes are stripped from the `target`. 99 100 @param target - The thing you want to open. Can be a URL, file, or executable. Opens in the default app for the file type. For example, URLs open in your default browser. 101 @returns The [spawned child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess). You would normally not need to use this for anything, but it can be useful if you'd like to attach custom event listeners or perform other operations directly on the spawned process. 102 103 @example 104 ``` 105 import open, {apps} from 'open'; 106 107 // Opens the image in the default image viewer. 108 await open('unicorn.png', {wait: true}); 109 console.log('The image viewer app quit'); 110 111 // Opens the URL in the default browser. 112 await open('https://sindresorhus.com'); 113 114 // Opens the URL in a specified browser. 115 await open('https://sindresorhus.com', {app: {name: 'firefox'}}); 116 117 // Specify app arguments. 118 await open('https://sindresorhus.com', {app: {name: 'google chrome', arguments: ['--incognito']}}); 119 120 // Opens the URL in the default browser in incognito mode. 121 await open('https://sindresorhus.com', {app: {name: apps.browserPrivate}}); 122 ``` 123 */ 124 export default function open( 125 target: string, 126 options?: Options 127 ): Promise<ChildProcess>; 128 129 /** 130 Open an app. Cross-platform. 131 132 Uses the command `open` on macOS, `start` on Windows and `xdg-open` on other platforms. 133 134 @param name - The app you want to open. Can be either builtin supported `apps` names or other name supported in platform. 135 @returns The [spawned child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess). You would normally not need to use this for anything, but it can be useful if you'd like to attach custom event listeners or perform other operations directly on the spawned process. 136 137 @example 138 ``` 139 import open, {openApp, apps} from 'open'; 140 141 // Open Firefox. 142 await openApp(apps.firefox); 143 144 // Open Chrome in incognito mode. 145 await openApp(apps.chrome, {arguments: ['--incognito']}); 146 147 // Open default browser. 148 await openApp(apps.browser); 149 150 // Open default browser in incognito mode. 151 await openApp(apps.browserPrivate); 152 153 // Open Xcode. 154 await openApp('xcode'); 155 ``` 156 */ 157 export function openApp(name: App['name'], options?: OpenAppOptions): Promise<ChildProcess>;