Skip to main content

Bundles

Bundles are a zip containing all files necessary to run your application. Bundles are uploaded via our CLI, processed by our server, and later can be turned into a Release.
Your overlay requires both an App bundle and a Site bundle, and you must create a release for each. The App release builds your Electron installer, and the Site release deploys your frontend to the CDN. Missing either bundle or either release will prevent your overlay from working in production.
Anything your app needs at runtime must be included in the bundle. The server does not run npm install for you during the build process — only the files you bundle are available in production.

Your first bundle

  1. Make sure you have the Overlayed CLI installed.
  2. Configure your overlayed.config.ts file to include the files you want to bundle:
overlayed.config.ts
  1. Run overlayed bundle to bundle your site, app, or both.
You may run our CLI locally or in a CI/CD pipeline - completely up to your workflow. To bundle, release and promote from GitHub Actions, follow Shipping from GitHub Actions.

App Bundle Build Format

Your compiled Electron code must output ESM (ES Modules). @overlayed/app is an ESM-only package and cannot be loaded as CommonJS. Ensure your build tooling (e.g. tsc, tsdown, esbuild) outputs .mjs files or that your package.json includes "type": "module". If you see Cannot use import statement outside a module after installing a release, your app bundle is being loaded as CJS. See the ts-vue-example for a working example of a correctly configured ESM build.

Channels

Channels allow you to deploy your application to a subset of users. This is useful for beta testing, early access programs, or paid tiers. Channels may be public or private, and by default every app has a public stable channel. We highly recommend creating a private channel for development and testing. Go here to manage your channels. To move specific users onto a channel, or hold them on a release, use update rules.

Releases

Create a release once you have a bundle ready to deploy. Releases are scoped to a channel. You also may set:
  • Scheduled release date (or instant)
  • Rollout percentage (e.g. 50% of users)
  • Release notes
  • Drafted release
Create releases in the dashboard, or with the CLI:

Changing a Rollout

Once a release is published and built, you can change its rollout from the actions on the release’s page in the dashboard, or through the API. This works for app and site releases.

Pausing and resuming

Pause rollout stops a release reaching more players:
  • A paused app release is kept only by players who already have it. New players and new installs get the previous release, and the channel’s download link serves the previous release too.
  • A paused site release holds at the percentage it was at when you paused it. A timed rollout stops ramping.
Resume rollout carries on from where it was paused. For a timed rollout that hadn’t finished, you choose what happens to its schedule:
  • By default, its start and end both move later by how long it was paused, so the ramp carries on from the percentage it was paused at. A rollout from 0% on Monday to 100% on Friday, paused at 25% on Tuesday and resumed on Wednesday, is still at 25% and now reaches 100% on Saturday.
  • Keeping the schedule leaves the start and end where they are, so the ramp catches up at once (50% in the example).
An instant rollout carries on at the same percentage either way. By default, a start time it was waiting for also moves later by how long it was paused.

Setting any percentage

You can set an instant rollout to any percentage from 0 to 100, higher or lower, including on a release that had no percentage (which reaches everyone). Lowering it rolls the players outside the new percentage back to the previous release they’re eligible for.

Changing or stopping a timed rollout

  • You can change the end time at any time, even after the ramp has started or finished. Moving it later lowers the current percentage and rolls the players outside it back.
  • You can change the start time only before the rollout starts.
  • Stop rollout stops it rolling out further: it stays at its current percentage of players as an instant rollout, which you can then set to any percentage. It isn’t available before the ramp starts; change the start time instead.
To set a percentage on a timed rollout, use Stop rollout first. All of these changes also work while a release is paused.

When players see a change

  • App players see it on their app’s next update check, which runs when your app calls checkForUpdates(). Players who are rolled back get the older build as described in Rollbacks.
  • Site players get it within about a minute, the next time the site loads in their app. With manual site updates, they get it once your app applies the update.

From the API

Changing a rollout needs the Owner, Manager or Maintainer role. The CLI’s overlayed releases rollout only raises a published release’s rollout; lower it, pause it or change its schedule from the dashboard or the API.

App Releases

When an app is released, we build an electron installer from your bundle file and host it on our CDN. You’ll need to implement app updating in your app to handle the update. All app releases are signed by our trusted certificate.

Site Releases

When a site is released, we’ll deploy your static files to our CDN and make them available at https://yoursite.overlayedapps.com. This URL is accessible here. Our servers will route the user to the correct version of your site based on the channel and app release version.

Safe Site Releases

If you make a site change that depends on an app version (e.g. a new IPC call, or a change to a previous IPC call), you must set a minimum app version for the release. This ensures that users will not get the site update until they’ve updated to that app version, preventing runtime errors.

Troubleshooting

”Configuration Required” message from the loaded site

This usually means you’re loading the production URL during local development. See Local Development for the correct dev/prod URL pattern.

”Cannot use import statement outside a module”

Your app bundle output is CJS but @overlayed/app requires ESM. Ensure your build outputs ESM format and your package.json includes "type": "module".