Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.overlayed.gg/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
Bundle TypeDescription
App BundleContains your Electron application code
Site BundleContains your static site assets (js,html,css,etc)
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
import { defineConfig } from "@overlayed/app";

export default defineConfig({
	applicationId: "YOUR_APPLICATION_ID",
	app: {
		include: ["dist-electron/**/*"],
	},
	site: {
		include: ["dist-site/**/*"],
	},
});
  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.

​
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.

​
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

​
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".