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

# Overlayed Config

> Setting up the overlayed.config.ts file

Each overlay must define an `overlayed.config.ts` file in the root of the project. This file is read by the
[CLI](/packages/cli) - `overlayed init` takes the `applicationId` from it, and `overlayed bundle` uses it to know which
files make up your **app bundle** and your **site bundle**.

<Info>
  For every option and its type, see the [OverlayedConfig reference](/packages/overlayed-config). For a step-by-step
  walkthrough of tuning the bundles, see [Configuring App & Site Bundles](/guides/configuring-app-site-bundles).
</Info>

## Example

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

const env = loadEnv(process.env.NODE_ENV ?? "development", process.cwd(), "VITE_");

export default defineConfig({
	applicationId: env.VITE_APPLICATION_ID,
	app: {
		include: ["out/**/*", "node_modules/@electron-toolkit/**"],
	},
	site: {
		baseDir: "./out/renderer",
		include: ["**/*"],
	},
});
```

## The Two Bundles

`overlayed bundle` produces two independent zips from this one config. Each is described by its own key.

| Key    | Bundle | Contains                                                    |
| ------ | ------ | ----------------------------------------------------------- |
| `app`  | App    | Your compiled Electron code and its runtime `node_modules`. |
| `site` | Site   | Your built frontend (static `html`, `js`, `css`, assets).   |

<Info>
  Anything your app needs at runtime must be listed in `include`. The server does **not** run `npm install` during the
  build - only the files you bundle are available in production. See [Understanding Bundles](/deployment/introduction).
</Info>

## applicationId

The application ID from the [Overlayed Dashboard](https://overlay.dev/settings/applications). It must be a valid ULID,
and must match the `applicationId` you pass to `overlayed()` at runtime.

Rather than hard-coding it, load it from an environment variable so the same config works across your applications and
CI:

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

const env = loadEnv(process.env.NODE_ENV ?? "development", process.cwd(), "VITE_");

export default defineConfig({
	applicationId: env.VITE_APPLICATION_ID,
	// ...
});
```

## Choosing what to include

`include` takes a [glob](https://www.npmjs.com/package/glob) pattern (or array of patterns). Paths are resolved relative
to the config file, or to [`baseDir`](#basedir) when set.

* **App bundle** - point it at your compiled output plus any `node_modules` your app loads at runtime:

  ```ts theme={null}
  app: {
  	include: ["out/**/*", "node_modules/@electron-toolkit/**"],
  }
  ```

* **Site bundle** - point it at your built frontend. Setting `baseDir` to your build output lets you keep the pattern
  as a simple `**/*`:

  ```ts theme={null}
  site: {
  	baseDir: "./out/renderer",
  	include: ["**/*"],
  }
  ```

<Tip>
  `package.json` and `node_modules/@overlayed/app` are always added to the app bundle, so you never need to list them
  yourself.
</Tip>

## baseDir

The directory that `include` and `exclude` patterns are resolved from. Defaults to the location of the
`overlayed.config.ts` file. Set it to bundle from a build output directory without repeating the prefix in every
pattern - `baseDir: "./out/renderer"` with `include: ["**/*"]` bundles everything under `out/renderer`.

## Excluding files

Trim a broad `include` with `exclude` (a glob string or array). It's the cleanest way to keep a wide net like
`node_modules/**` while dropping the parts you don't ship:

```ts overlayed.config.ts theme={null}
export default defineConfig({
	applicationId: env.VITE_APPLICATION_ID,
	app: {
		include: ["out/**/*", "node_modules/**"],
		exclude: [
			"**/*.map", // source maps
			"**/*.md", // package readmes
			"**/test/**", // dependency test folders
			"node_modules/.bin/**",
		],
	},
});
```

The `overlayed.config.ts` file is always excluded from both bundles, and the **app** bundle additionally drops any
`installer` folder for you. The site bundle only excludes `overlayed.config.ts`, so add an explicit `exclude` if a broad
site `include` could otherwise pick up an `installer` directory.

## Distribution only

The `site` bundle is only consumed when you deploy - during local development your frontend is served by its own dev
server. This is why the distribution examples annotate the site `include` with a comment: it does nothing until you run
`overlayed bundle` to ship a release.

## More Info

See the full [OverlayedConfig reference](/packages/overlayed-config) for every option, including the advanced
`nodeModulesDir`, `resolvePackageVersion`, `resolveCommitHash`, and `debug` fields.