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.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
- Make sure you have the Overlayed CLI installed.
- Configure your overlayed.config.ts file to include the files you want to bundle:
overlayed.config.ts
- Run
overlayed bundleto 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 publicstable 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
overlayed releases createreleases a bundle to a channel.overlayed bundle --release <channel>bundles and releases in one step, the app first and then the site with its minimum app version set to the new app version.overlayed releases promotereleases what’s on one channel to another, e.g.betatostable.overlayed releases publish,rolloutandcancelpublish a draft, raise a rollout, or cancel or revoke a release.
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.
- 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).
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.
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 athttps://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".
