Shortcuts and URL Shortcuts

Two array properties cover all shortcut needs:

• shortcuts – Windows .lnk shortcuts (Start menu, Desktop, custom locations). For MSIX these become app entries in the Start menu / All Apps list.
• urlShortcuts – Web .url shortcuts that open in the user's default browser.

Applies to: MSI and MSIX.

MSIX requires at least one shortcuts entry. Without it, the OS has no idea what to surface as the "app". Validation will fail with at least one msix shortcut required.

---

shortcuts – application shortcuts

Properties

Property	Type	Required	Default	Description
target	string	yes	–	The exe/file the shortcut launches. Usually a path inside the package ($.installDir\\MyApp.exe).
name	string	no	filename of target minus extension	Display name.
location	string	no	see below	Folder where the shortcut is created.
arguments	string	no	–	Command-line arguments passed to target.
workingDirectory	string	no	–	Working directory for the shortcut.
description	string	no	–	Tooltip text on hover.
icon	string	no	icon extracted from target	Source .ico/.png/.exe/.dll. Append ,index for an exe/dll icon.

Default location

• If the package has one shortcut: %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\
• If the package has more than one shortcut: %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\$.packageName\ (a sub-folder named after your package)

You can always override location:

{
  "target":   "$.installDir\\MyApp.exe",
  "location": "%PUBLIC%\\Desktop"
}

warning

The user's desktop is private. Validation will warn you with "It is not recommended to create a shortcut on the user's desktop as it is their private space." Use the public desktop (%PUBLIC%\Desktop) if you really want one.

Examples

Minimal Start menu shortcut

"shortcuts": [
  { "target": "$.installDir\\MyApp.exe" }
]

Creates My Application.lnk in the Start menu.

Branded shortcut with description and custom icon

"shortcuts": [
  {
    "target":      "$.installDir\\MyApp.exe",
    "name":        "My Application",
    "description": "My Application does amazing things",
    "icon":        "installer-assets\\notes-icon.ico",
    "workingDirectory": "%USERPROFILE%\\Documents"
  }
]

Multiple shortcuts under a package folder

"shortcuts": [
  {
    "target": "$.installDir\\MyApp.exe",
    "name":   "My Application"
  },
  {
    "target":    "$.installDir\\MyApp.exe",
    "name":      "My Application (Safe Mode)",
    "arguments": "--safe-mode"
  }
]

Because there is more than one entry, both shortcuts appear in the Start menu under My Application/.

Public desktop shortcut

"shortcuts": [
  {
    "target":   "$.installDir\\MyApp.exe",
    "location": "%PUBLIC%\\Desktop",
    "name":     "My Application"
  }
]

---

urlShortcuts – web URL shortcuts

.url files that open in the default browser when launched.

Properties

Property	Type	Required	Default	Description
name	string	yes	–	The shortcut's file name (without .url). Must be unique across all urlShortcuts.
url	string	yes	–	An HTTP or HTTPS URL.
location	string	no	same logic as shortcuts.location	Folder where the .url file is created.

Example

"urlShortcuts": [
  {
    "name": "My Application - Documentation",
    "url":  "https://docs.mycompany.example.com"
  },
  {
    "name": "My Application - Support",
    "url":  "https://support.mycompany.example.com"
  }
]

Creates My Application - Documentation.url and My Application - Support.url in the Start menu folder.

---

MSI vs MSIX behavior

Aspect	MSI	MSIX
Required?	No	Yes – at least one shortcuts entry.
location	Honored exactly.	Mostly ignored. MSIX exposes the shortcut as an app entry in the Start menu. The system controls the placement.
Icon source	Resolved at build time, embedded in MSI.	Embedded in the manifest as the package logo. Multiple sizes auto-generated.
arguments, workingDirectory, description	All honored.	All honored where the MSIX manifest supports them.
Multiple shortcuts	Sub-folder created automatically.	Each entry is a separate app entry.

---

Validation rules

Validator	Applies to	Catch
required	target, urlShortcuts.name, urlShortcuts.url	Cannot be null/empty.
valid path	target	Must be a syntactically valid path.
valid http url	urlShortcuts.url	Must be a real HTTP/HTTPS URL.
valid icon source	icon	Must point to .ico, .png, .exe, or .dll.
at least one msix shortcut required	array	At least one entry needed when building MSIX.
unique url shortcut name	urlShortcuts.name	All name values must be unique.

You will also see warnings about the user's desktop and shortcuts placed outside Start Menu\Programs. They are best-practice guardrails, not blockers.

---

---