create-desktop-shortcuts

Small, lightweight, cross-platform, built in validation!

100% Test Coverage, Automated Cross-Platform End-to-End tested

An easy, cross-platform, API to create desktop shortcuts with Node. (Works in NW.js too!)

This library is completely synchronous.

It uses 1 dependency, which has it's own single dependency

• create-desktop-shortcuts - small - 100% test coverage
  • which - small - 100% test coverage - used by 9 million projects
    • isexe - very small - used by 9 million projects

Installation

npm install --save create-desktop-shortcuts

Examples

Simple example:

const createDesktopShortcut = require('create-desktop-shortcuts');

const shortcutsCreated = createDesktopShortcut({
  windows: { filePath: 'C:\\path\\to\\executable.exe' },
  linux:   { filePath: '/home/path/to/executable'     },
  osx:     { filePath: '/home/path/to/executable'     }
});

if (shortcutsCreated) {
  console.log('Everything worked correctly!');
} else {
  console.log('Could not create the icon or set its permissions (in Linux if "chmod" is set to true, or not set)');
}

Advanced Example:

Each OS handles the concept of a shortcut icon slightly differently. So they each have a slightly different API, but I tried to keep them similar when they overlap.

const createDesktopShortcut = require('create-desktop-shortcuts');

const shortcutsCreated = createDesktopShortcut({
  // OPTIONAL: defaults to true
  onlyCurrentOS: true,
  // OPTIONAL: defaults to true
  verbose: true,
  /**
   * OPTIONAL: console.error is called by default if verbose: true.
   *
   * Your own custom logging function called with helpful warning/error
   * messages from the internal validators. Only used if verbose: true.
   *
   * @param {string} message  The human readable warning/error message
   * @param {object} error    Sometimes an error or options object is passed
   */
  customLogger: function (message, error) {
    console.log(message, error);
  },
  windows: {
    // REQUIRED: Path must exist
    filePath: 'C:\\path\\to\\executable.exe',
    // OPTIONAL: Defaults to the Desktop of the current user (by asking Windows specifically where it is located)
    outputPath: 'C:\\some\\folder',
    // OPTIONAL: defaults to the filePath file's name (without the extension)
    name: 'My App Name',
    // OPTIONAL
    comment: 'My App description',
    // OPTIONAL: File must exist and be ICO, EXE, or DLL
    icon: 'C:\\path\\to\\file.ico',
    // OPTIONAL
    arguments: '--my-argument -f \'other stuff\'',
    // OPTIONAL: defaults to 'normal'
    windowMode: 'normal',
    // OPTIONAL
    hotkey: 'ALT+CTRL+F'
  },
  linux: {
    // REQUIRED: Path must exist
    filePath: '/home/path/to/executable',
    // OPTIONAL: Defaults to the Desktop of the current user
    outputPath: '/home/some/folder',
    // OPTIONAL: defaults to the filePath file's name (without the extension)
    name: 'My App Name',
    // OPTIONAL
    description: 'My app description',
    // OPTIONAL: File must exist and be PNG or ICNS
    icon: '/home/path/to/file.png',
    // OPTIONAL: 'Application', 'Directory', or 'Link' (must logically match filePath)
    type: 'Application',
    // OPTIONAL: defaults to false
    terminal: false,
    // OPTIONAL: defaults to true
    chmod: true,
    // OPTIONAL
    arguments: '--my-argument -f'
  },
  osx: {
    // REQUIRED: Path must exist
    filePath: '/Applications/My App.app',
    // OPTIONAL: Defaults to the Desktop of the current user
    outputPath: '/home/some/folder',
    // OPTIONAL: defaults to the filePath file's name (without the extension)
    name: 'My App Name',
    // OPTIONAL: defaults to false
    overwrite: false
  }
});

// returns true if everything worked correctly, or false if it could not create the icon or set its permissions
console.log(shortcutsCreated);

Documentation

Global Settings

Windows Settings

Linux Settings

OSX Settings

OSX will automatically inherit the icon of the target you point to. It doesn't care if you point to a folder, file, or application.

NOTE: If overwrite is set to false and a matching file already exists, a console.error will occur to inform you of this, however create-desktop-shortcuts will still report successful (return true). This console.error can be hidden by setting verbose to false, or using a customLogger to intercept it.

Special paths

The filePath for all OS's can be set to an executable name directly if it is available in the user's PATH. For example, if you set it to 'node' or 'python' or 'cmd' and the user can access those from PATH variables, it will work automatically. But the file must exist and must be an actual executable, otherwise you should hard code the value.

The filePath and outputPath can use environment variables on Windows, like '%appData%'. See the "Add to start menu" section below for more examples.

The filePath and outputPath can start with ~ or / on Linux or OSX and the paths will be resolved automatically.

Add to start menu

Here are the documented paths you can use for the outputPath to create a shortcut in the start menu.

OSX doesn't have a "Start menu" nor an official means of adding items to the dock.

In Windows 8+ it might be possible to pin a "tile" in the start menu, but that looks difficult, and out of scope for this library. If someone else created a Node library for pinning tiles to the start menu this line of the README should be updated to link to it.

OS Support

End-to-end tests run on every commit using:

• Ubuntu latest with Node v8.3.0
• Ubuntu latest with Node v18.x.x
• Windows latest with Node v8.3.0
• Windows latest with Node v18.x.x
• OSX latest with Node v8.3.0
• OSX latest with Node v18.x.x

Manually Tested on:

• Windows XP with Node v4.4.5
• Windows 7 with Node v4.0.0, v8, v10, v12, v13.13.0 (last supported Node version for Win 7)
• Windows 10 with Node v12, v14, v15
• Ubuntu 16, 20 with Node v12
• OSX 10.11 with Node v7.3.0
• NW.js v0.14.7 (LTS), v0.30.0, v0.50.0

Credits

Author: The Jared Wilcurt

Parts of the windows.vbs were copied/modified based on:

• https://www.vbsedit.com/html/a239a3ac-e51c-4e70-859e-d2d8c2eb3135.asp
• https://forums.techguy.org/threads/solved-vbscript-create-a-shortcut-within-a-folder.886401/

How can you help improve this repo?

• Report bugs in the GitHub issues
• Request features
• Fix reported bugs with a PR
• Offer an async and sync mode, instead of just sync.
  • Note: Make sure it can still run in older versions of NW.js
• Help with any of the known issues listed below
• This repo is written using require for imports. I would endorse anyone that wants to create a fork of this repo written in ESM that drops support for older Node versions and is written with async support (maybe promises?). Maybe call it create-desktop-shortcuts-esm or something.

Running locally for development

1. Install Volta (Runs the Node/npm version based on the repo's package.json automatically)
2. Fork/Clone the repo with git
3. npm install
4. You can run npm t to run all unit tests
5. You can edit the manual-testing.js file to try things out locally with npm run manual-test
6. npm run lint to see linting errors, npm run fix to attempt to fix them automatically
7. npm run debug to run Node's debugger tool with your manual test
8. npm run debug-test to run the debugger against a specific test

Known issues & limitations

1. Windows: If WScript does not like what is passed to it, it displays a Windows Dialog with an error on the line that failed. I have no idea how to turn that off, so I've just added in tons of validation checks to prevent anything from being passed in to it that could cause this. But may still occur if you pass in junk that gets by the validation checks.
2. Linux: No real recourse if the script does not have permission to run chmod on Linux. You would just need to run it again with sudo or something. If you have ideas, create an issue or PR.
3. OSX: I know of no way to set a custom icon image on OSX. It will just always use the same icon the executable had (or file type if linking to an .html file for example)
4. Windows/Linux: May want to add in overwrite option for Windows and Linux too. This would require deleting the existing shortcut. Deleting files is something that each OS sucks at in different ways and would require pulling in something like fs-extra or a similar dependency. If you need this, you can reference this implementation code example.
5. OSX: To my knowledge there is no way to pass in arguments with a shortcut. If anyone knows how, make an issue with details.

Related Libraries

• get-windows-shortcut-properties