get-windows-shortcut-properties

A Node.js library to get the properties of a Windows .lnk or .url shortcut file.

This library is completely SYNCHRONOUS.

Install Instructions

Install Node/npm
npm install --save get-windows-shortcut-properties

Usage

Single File Example

const getWindowsShortcutProperties = require('get-windows-shortcut-properties');

if (process.platform === 'win32') {
  const output = getWindowsShortcutProperties.sync('../Sublime Text.lnk');

  if (output) {
    console.log(output);
  } else {
    console.log('There was an error');
  }
}

Multiple Files Example

const getWindowsShortcutProperties = require('get-windows-shortcut-properties');

if (process.platform === 'win32') {
  const output = getWindowsShortcutProperties.sync([
    '../Sublime Text.lnk',
    'C:\\Users\\Public\\Desktop\\Firefox.lnk'
  ]);
  if (output) {
    console.log(output);
  } else {
    console.log('There was an error');
  }
}

Custom Logger Single File Example

const getWindowsShortcutProperties = require('get-windows-shortcut-properties');

if (process.platform === 'win32') {
  const output = getWindowsShortcutProperties.sync('../Sublime Text.lnk', function (message, error) {
    console.log(message, error);
  });

  if (output) {
    console.log(output);
  } else {
    console.log('There was an error');
  }
}

Custom Logger Multiple Files Example

const getWindowsShortcutProperties = require('get-windows-shortcut-properties');

if (process.platform === 'win32') {
  const shortcuts = [
    '../Sublime Text.lnk',
    'C:\\Users\\Public\\Desktop\\Firefox.lnk'
  ];
  function customLogger (message, error) {
    console.log(message, error);
  }
  const output = getWindowsShortcutProperties.sync(shortcuts, customLogger);

  if (output) {
    console.log(output);
  } else {
    console.log('There was an error');
  }
}

Documentation

getWindowsShortcutProperties.sync API

First argument: filePath
- TYPE: String or Array of Strings
- DESCRIPTION: The path to the shortcut file you want the properties of, or an array of strings to multiple files
- REQUIREMENTS: Strings must point to a file that exists and ends in .lnk or .url
- PERFORMANCE: Passing in an array of files is significantly faster than running this library once for every file. Each run has a ~0.25s overhead cost of spinning up PowerShell. So we group all your files into one request and they run together. (meaning 100 individual runs = 25 seconds versus one run with 100 files passed in = 0.4s).
- WARNING: Passing in too many files at once will produce a PowerShell command that is too long to run. For me it worked with 92 files and no more. But it's all about the total command length produced by this library. So longer file paths will mean fewer files can be passed in at once. Relative paths are normalized by Node, so using them will not help or hurt.
Second argument: customLogger
- TYPE: function
- DESCRIPTION: This is an optional function that is called with a message and error object (if something fails, or you pass in bad inputs). Defaults to using console.error if not passed in.

getWindowsShortcutProperties.sync Output

Returns undefined if all files errored, or an Array of Objects for each successful file:

[
  {
    FullName: 'C:\\Users\\Owner\\Desktop\\DaVinci Resolve.lnk',
    Arguments: '',
    Description: 'Video Editor',
    Hotkey: '',
    IconLocation: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\ResolveIcon.exe,0',
    RelativePath: '',
    TargetPath: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\Resolve.exe',
    WindowStyle: '1',
    WorkingDirectory: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\'
  }
]

See Microsoft's Shortcut Documentation for information on these keys and their values.

If you pass in an array of files, and some succeed, you will get an array of the success and console errors for the other files (unless you pass in a customLogger function, in which case it gets called when errors occur).

getWindowsShortcutProperties.translate API

First argument: shortcutProperties
- TYPE: Array of Objects
- DESCRIPTION: Each object in the array is the properties for one shortcut, we convert this over to something more human readable.
Second argument: customLogger
- TYPE: function
- DESCRIPTION: This is an optional function that is called with a message and error object (if something fails, or you pass in bad inputs). Defaults to using console.error if not passed in.

getWindowsShortcutProperties.translate Output

Takes in the ouput of getWindowsShortcutProperties.sync, and then translates it into the Input for create-desktop-shortcuts (a different Node.js library).

const microsoftNamingConventions = [
  {
    FullName: 'C:\\Users\\Owner\\Desktop\\DaVinci Resolve.lnk',
    Arguments: '--foo',
    Description: 'Video Editor',
    Hotkey: 'Ctrl+F10',
    IconLocation: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\ResolveIcon.exe,0',
    RelativePath: '',
    TargetPath: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\Resolve.exe',
    WindowStyle: '1',
    WorkingDirectory: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\'
  }
];
const output = getWindowsShortcutProperties.translate(microsoftNamingConventions); // produces the below output
const output = [
  {
    filePath: 'C:\\Users\\Owner\\Desktop\\DaVinci Resolve.lnk',
    arguments: '--foo',
    comment: 'Video Editor',
    hotkey: 'Ctrl+F10',
    icon: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\ResolveIcon.exe,0',
    relativePath: '',
    targetPath: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\Resolve.exe',
    windowMode: 'normal',
    workingDirectory: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\'
  }
];

OS Support

Only works on Windows OS's that have PowerShell installed.

Credits

Author: The Jared Wilcurt

This repo was inspired by:

https://github.com/felixrieseberg/windows-shortcuts-ps

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.
This repo is written using require for imports. It would be nice to also support ESM imports.

Related Libraries:

create-desktop-shortcuts

nwutils/get-windows-shortcut-properties