{"id":20148329,"url":"https://github.com/nwutils/get-windows-shortcut-properties","last_synced_at":"2025-04-09T19:51:46.789Z","repository":{"id":143879680,"uuid":"453486916","full_name":"nwutils/get-windows-shortcut-properties","owner":"nwutils","description":"A Node.js library to get the properties of a Windows .lnk or .url shortcut file","archived":false,"fork":false,"pushed_at":"2023-11-25T19:19:33.000Z","size":104,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T14:05:56.851Z","etag":null,"topics":["desktop-shortcuts","nodejs","windows"],"latest_commit_sha":null,"homepage":"https://nwutils.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nwutils.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-29T18:40:14.000Z","updated_at":"2024-07-20T09:47:09.000Z","dependencies_parsed_at":"2024-06-19T20:03:35.832Z","dependency_job_id":"b1b4cf67-7e34-4119-8828-678fa8f60b64","html_url":"https://github.com/nwutils/get-windows-shortcut-properties","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwutils%2Fget-windows-shortcut-properties","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwutils%2Fget-windows-shortcut-properties/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwutils%2Fget-windows-shortcut-properties/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwutils%2Fget-windows-shortcut-properties/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nwutils","download_url":"https://codeload.github.com/nwutils/get-windows-shortcut-properties/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103903,"owners_count":21048244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-shortcuts","nodejs","windows"],"created_at":"2024-11-13T22:37:17.193Z","updated_at":"2025-04-09T19:51:46.768Z","avatar_url":"https://github.com/nwutils.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# get-windows-shortcut-properties\n\nA Node.js library to get the properties of a Windows .lnk or .url shortcut file.\n\nThis library is completely **SYNCHRONOUS**.\n\n\n## Install Instructions\n\n1. Install [Node/npm](https://nodejs.org)\n1. `npm install --save get-windows-shortcut-properties`\n\n\n## Usage\n\n**Single File Example**\n\n```js\nconst getWindowsShortcutProperties = require('get-windows-shortcut-properties');\n\nif (process.platform === 'win32') {\n  const output = getWindowsShortcutProperties.sync('../Sublime Text.lnk');\n\n  if (output) {\n    console.log(output);\n  } else {\n    console.log('There was an error');\n  }\n}\n```\n\n**Multiple Files Example**\n\n```js\nconst getWindowsShortcutProperties = require('get-windows-shortcut-properties');\n\nif (process.platform === 'win32') {\n  const output = getWindowsShortcutProperties.sync([\n    '../Sublime Text.lnk',\n    'C:\\\\Users\\\\Public\\\\Desktop\\\\Firefox.lnk'\n  ]);\n  if (output) {\n    console.log(output);\n  } else {\n    console.log('There was an error');\n  }\n}\n```\n\n**Custom Logger Single File Example**\n\n```js\nconst getWindowsShortcutProperties = require('get-windows-shortcut-properties');\n\nif (process.platform === 'win32') {\n  const output = getWindowsShortcutProperties.sync('../Sublime Text.lnk', function (message, error) {\n    console.log(message, error);\n  });\n\n  if (output) {\n    console.log(output);\n  } else {\n    console.log('There was an error');\n  }\n}\n```\n\n**Custom Logger Multiple Files Example**\n\n```js\nconst getWindowsShortcutProperties = require('get-windows-shortcut-properties');\n\nif (process.platform === 'win32') {\n  const shortcuts = [\n    '../Sublime Text.lnk',\n    'C:\\\\Users\\\\Public\\\\Desktop\\\\Firefox.lnk'\n  ];\n  function customLogger (message, error) {\n    console.log(message, error);\n  }\n  const output = getWindowsShortcutProperties.sync(shortcuts, customLogger);\n\n  if (output) {\n    console.log(output);\n  } else {\n    console.log('There was an error');\n  }\n}\n```\n\n\n## Documentation\n\n\n### getWindowsShortcutProperties.sync API\n\n* First argument: `filePath`\n  * **TYPE:** *String or Array of Strings*\n  * **DESCRIPTION:** The path to the shortcut file you want the properties of, or an array of strings to multiple files\n  * **REQUIREMENTS:** Strings must point to a file that exists and ends in `.lnk` or `.url`\n  * **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).\n  * **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.\n* Second argument: `customLogger`\n  * **TYPE:** *function*\n  * **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.\n\n\n### getWindowsShortcutProperties.sync Output\n\nReturns `undefined` if all files errored, or an Array of Objects for each successful file:\n\n```js\n[\n  {\n    FullName: 'C:\\\\Users\\\\Owner\\\\Desktop\\\\DaVinci Resolve.lnk',\n    Arguments: '',\n    Description: 'Video Editor',\n    Hotkey: '',\n    IconLocation: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\ResolveIcon.exe,0',\n    RelativePath: '',\n    TargetPath: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\Resolve.exe',\n    WindowStyle: '1',\n    WorkingDirectory: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\'\n  }\n]\n```\n\nSee [Microsoft's Shortcut Documentation](https://docs.microsoft.com/en-us/troubleshoot/windows-client/admin-development/create-desktop-shortcut-with-wsh) for information on these keys and their values.\n\n\nIf 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).\n\n\n### getWindowsShortcutProperties.translate API\n\n* First argument: `shortcutProperties`\n  * **TYPE:** *Array of Objects*\n  * **DESCRIPTION:** Each object in the array is the properties for one shortcut, we convert this over to something more human readable.\n* Second argument: `customLogger`\n  * **TYPE:** *function*\n  * **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.\n\n\n### getWindowsShortcutProperties.translate Output\n\nTakes in the ouput of `getWindowsShortcutProperties.sync`, and then translates it into the Input for `create-desktop-shortcuts` (a different Node.js library).\n\n```js\nconst microsoftNamingConventions = [\n  {\n    FullName: 'C:\\\\Users\\\\Owner\\\\Desktop\\\\DaVinci Resolve.lnk',\n    Arguments: '--foo',\n    Description: 'Video Editor',\n    Hotkey: 'Ctrl+F10',\n    IconLocation: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\ResolveIcon.exe,0',\n    RelativePath: '',\n    TargetPath: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\Resolve.exe',\n    WindowStyle: '1',\n    WorkingDirectory: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\'\n  }\n];\nconst output = getWindowsShortcutProperties.translate(microsoftNamingConventions); // produces the below output\nconst output = [\n  {\n    filePath: 'C:\\\\Users\\\\Owner\\\\Desktop\\\\DaVinci Resolve.lnk',\n    arguments: '--foo',\n    comment: 'Video Editor',\n    hotkey: 'Ctrl+F10',\n    icon: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\ResolveIcon.exe,0',\n    relativePath: '',\n    targetPath: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\Resolve.exe',\n    windowMode: 'normal',\n    workingDirectory: 'C:\\\\Program Files\\\\Blackmagic Design\\\\DaVinci Resolve\\\\'\n  }\n];\n```\n\n\n* * *\n\n\n## OS Support\n\nOnly works on Windows OS's that have PowerShell installed.\n\n\n* * *\n\n\n## Credits\n\nAuthor: The Jared Wilcurt\n\nThis repo was inspired by:\n\n* https://github.com/felixrieseberg/windows-shortcuts-ps\n\n\n* * *\n\n\n## How can you help improve this repo?\n\n* Report bugs in the GitHub issues\n* Request features\n* Fix reported bugs with a PR\n* Offer an async and sync mode, instead of just sync.\n* This repo is written using `require` for imports. It would be nice to also support ESM imports.\n\n\n* * *\n\n\n## Related Libraries:\n\n* [create-desktop-shortcuts](https://github.com/nwutils/create-desktop-shortcuts)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwutils%2Fget-windows-shortcut-properties","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnwutils%2Fget-windows-shortcut-properties","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwutils%2Fget-windows-shortcut-properties/lists"}