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

# Introduction

> How to deploy your Overlayed Application

## 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 Type | Description                                        |
| ----------- | -------------------------------------------------- |
| App Bundle  | Contains your Electron application code            |
| Site Bundle | Contains your static site assets (js,html,css,etc) |

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

### Your first bundle

1. Make sure you have the [Overlayed CLI](/packages/cli) installed.

2. Configure your [overlayed.config.ts](/packages/overlayed-config) file to include the files you want to bundle:

```ts overlayed.config.ts theme={null}
import { defineConfig } from "@overlayed/app";

export default defineConfig({
	applicationId: "YOUR_APPLICATION_ID",
	app: {
		include: ["dist-electron/**/*"],
	},
	site: {
		include: ["dist-site/**/*"],
	},
});
```

3. Run `overlayed bundle` to bundle your site, app, or both.

<Info>You may run our CLI locally or in a CI/CD pipeline - completely up to your workflow.</Info>

### 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](https://github.com/overlayed-gg/examples/tree/main/examples/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](https://overlay.dev/channels) 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](/deployment/updates) 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](https://overlay.dev/settings).

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](/essentials/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"`.