DesktopOverlays

Packaging and publishing ​

You author a bundle as a folder and publish it to the Steam Workshop from inside the app. The app packages and uploads the folder for you, and other users install it by subscribing. There is no file to copy or send by hand.

Create a bundle in the app ​

You don't have to hand-write the folder. Open the Workshop, go to Your bundles, and press Create bundle:

  • Create from Library — pick one or more media items you've already imported. Each becomes a content entry, the files are copied into the bundle, and the desktop-overlays.config.json is generated for you. You can use one of the picked items (or your own image) as the thumbnail.
  • Create Custom — start from a blank index.html with a generated config, ready for you to build a custom HTML overlay.

Either way you're asked for a name, description, version, and author, and the bundle is created under Documents/DesktopOverlays/my-bundles/<name> (you can change the location). It then shows up in Your bundles, ready to tweak and publish.

Before you publish ​

Get the bundle right in preview first:

  • The manifest validates and the overlay loads. See Manifest reference.
  • Every capability you use is in permissions, and the reasons are honest. See Permissions.
  • Remote URLs are covered by network.* permissions. See Assets and networking.
  • A thumbnail is set, since it represents the bundle in the library and the Workshop. See Thumbnails for the accepted formats.
  • tags describe the bundle so browsers can find it, and mature is set if the content needs it. See tags and mature content.
  • version reflects this release.

Keep development files out ​

A development folder often holds files that should not ship: source folders before a build, node_modules, build output, source maps. Use the ignore field in the manifest to leave them out of the published bundle.

jsonc
"ignore": ["node_modules", "src/**", "*.map", "*.ts"]
  • * matches within a path segment, ** across segments, ? a single character.
  • A pattern with no slash matches at any depth, like a .gitignore rule.
  • desktop-overlays.config.json is always kept.

Anything that the running overlay needs at runtime must not be ignored. Ignore sources and tooling, not the assets your index.html actually loads.

Publish ​

Publish to the Steam Workshop from inside the app. The app packages your folder, applying ignore, and uploads it as a Workshop item with your name, description, thumbnail, and tags. If mature is true, the item is flagged as mature content on Steam.

Thumbnails ​

The Workshop accepts a raster preview image. The app converts your thumbnail before upload so it always lands in a supported format:

  • png, svg, and webp are flattened onto an opaque background and converted to JPG (transparency renders unpredictably in Steam's UI).
  • jpg is uploaded as-is.
  • gif is uploaded as-is, so an animated thumbnail keeps moving in the Workshop.

If the conversion fails for some reason, the bundle still publishes, just without a preview image.

Update ​

To release a new version, bump version in the manifest and publish again from the same folder. The existing Workshop item is updated in place rather than creating a new one. Subscribers receive the update.

If an update changes permissions to request new capabilities, each user is shown the consent screen again before the update applies, so a new capability is never granted silently. See Permissions.

How users install your bundle ​

From a user's side:

  1. They browse the Workshop inside the app and subscribe to your bundle. The browser can sort results, filter by your tags, and (off by default) include mature content.
  2. Steam downloads it.
  3. The app shows the consent screen with your requested permissions and reasons.
  4. If they approve, the bundle is installed and appears in their overlay list. If they decline, nothing is installed and the subscription is undone.

On later launches, the app keeps installed bundles in sync with the user's Workshop subscriptions.