DOCSEARCHbyAlgolia
Submit Docs

node-auto-launch

repository·master·Indexed 21 days ago

https://github.com/teamwork/node-auto-launch

A Node.js utility to enable or disable auto-launching of applications or executables at system startup or user login across Windows, macOS, Linux, and FreeBSD. It provides an AutoLaunch class with methods to enable, disable, and check the status of auto-launching, with specific support for Electron, NW.js, and Windows Store apps.

Tokens
1.7K
Snippets
5
Records
10
Agent score
26%

What's inside node-auto-launch

  1. How auto-launch works on different platforms

    master

    The mechanism used to achieve auto-launch varies by operating system:

    • Linux / FreeBSD: Creates a .desktop file in ~/.config/autostart/.
    • macOS (AppleScript - Default): Uses AppleScript to instruct System Events to add/remove a Login Item. The app will appear in System Preferences > Users & Groups > Login Items.
    • macOS (Launch Agent): Adds a .plist file to the user's Library/LaunchAgents directory. This method is faster and better for daemons, but the app will not appear in the user's Login Items list.
    • Windows: Adds a registry entry under \HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run.

    Note for macOS users: Both AppleScript and Launch Agent methods are not Mac App Store friendly and may cause rejection due to sandboxing restrictions.

  2. Configure auto-launch for Windows Store apps

    master

    Standard executable paths do not work for sandboxed Windows Store (Appx) packages. To auto-launch a Windows Store app, you must use the explorer.exe shell:AppsFolder\ syntax with your app's specific identifiers.

    Format: explorer.exe shell:AppsFolder\DEV_ID.APP_ID!PACKAGE_NAME

    How to find your path:

    1. Install a beta version of your app from the Microsoft Store.
    2. Open the Windows apps folder by running shell:AppsFolder in the Win+R dialog.
    3. Create a shortcut to your app on the Desktop.
    4. Right-click the shortcut, select Properties, and copy the content of the Target field.
    new autoLaunch({
  name: 'APP_NAME',
  path: 'explorer.exe shell:AppsFolder\DEV_ID.APP_ID!PACKAGE_NAME',
  isHidden: true
});

  4. Basic usage of auto-launch

    master

    To auto-launch an application, create a new AutoLaunch instance with the app's name and absolute path, then call .enable(). You can also check the current status using .isEnabled().

    Note: For NW.js and Electron apps, the path option is optional as the library will attempt to auto-detect it using process.execPath.

    var AutoLaunch = require('auto-launch');

var minecraftAutoLauncher = new AutoLaunch({
	name: 'Minecraft',
	path: '/Applications/Minecraft.app',
});

minecraftAutoLauncher.enable();

//minecraftAutoLauncher.disable();


minecraftAutoLauncher.isEnabled()
.then(function(isEnabled){
	if(isEnabled){
	    return;
	}
	minecraftAutoLauncher.enable();
})
.catch(function(err){
    // handle error
});

  5. Configure the AutoLaunch constructor

    master

    The AutoLaunch constructor accepts an options object to define how your application should be launched.

    OptionTypeDescription
    nameStringRequired. The name of your app.
    pathStringOptional (for NW.js/Electron). The absolute path to your app.
    isHiddenBooleanOptional. If true, instructs the OS to launch the app in hidden mode. Defaults to false.
    macObjectOptional. Mac-specific configuration options.
    mac.useLaunchAgentBooleanOptional. If true, uses a Launch Agent instead of AppleScript. Defaults to false.

  6. Initialize AutoLaunch with new AutoLaunch(options)

    master

    To use node-auto-launch, instantiate the AutoLaunch class. You must provide a name for the application. You can optionally provide a path to the executable and an options object to configure behavior.

    Mandatory Parameter:

    • name: A non-empty string representing the application name.

    Optional Parameters:

    • path: The absolute path to the application executable. If not provided, the path is only automatically detected if the application is running in an Electron, NW.js, or node-webkit environment (using process.execPath). For all other environments, providing an absolute path is required.
    • options: An object to fine-tune launch behavior:
      • launchInBackground: A boolean. If true, the application will attempt to launch in the background (e.g., using --hidden on certain platforms).
      • mac: A configuration object for macOS:
        • useLaunchAgent: A boolean. If true, uses a file-based Launch Agent. If false (default), uses AppleScript to add the app as a Login Item.
      • extraArgs: An array of additional command-line arguments to pass during launch.
    import AutoLaunch from 'node-auto-launch';

const launch = new AutoLaunch({
  name: 'My App',
  path: '/absolute/path/to/my/app',
  options: {
    launchInBackground: true,
    mac: {
      useLaunchAgent: true
    },
    extraArgs: ['--some-flag']
  }
});

  7. Enable, disable, and check auto-launch status with AutoLaunch

    master

    The AutoLaunch instance provides three primary methods to manage the application's startup behavior:

    • enable(): Enables the application to launch automatically on system startup. Returns a Promise.
    • disable(): Disables the application's auto-launch capability. Returns a Promise.
    • isEnabled(): Checks whether the application is currently configured to launch on startup. Returns a Promise that resolves to a Boolean.
    import AutoLaunch from 'node-auto-launch';

const launch = new AutoLaunch({ name: 'My App' });

// Enable auto-launch
await launch.enable();

// Check if it is enabled
const enabled = await launch.isEnabled();
console.log(`Is enabled: ${enabled}`);

// Disable auto-launch
await launch.disable();