Overlayed Config

Each overlay must define an overlayed.config.ts file in the root of the project. This file is read by the 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.

For every option and its type, see the OverlayedConfig reference. For a step-by-step walkthrough of tuning the bundles, see Configuring App & Site Bundles.

Example

overlayed.config.ts

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

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.

applicationId

The application ID from the Overlayed Dashboard. 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:

overlayed.config.ts

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 pattern (or array of patterns). Paths are resolved relative to the config file, or to baseDir when set.

App bundle - point it at your compiled output plus any node_modules your app loads at runtime:
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 **/*:
site: { baseDir: "./out/renderer", include: ["**/*"], }

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

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:

overlayed.config.ts

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 for every option, including the advanced nodeModulesDir, resolvePackageVersion, resolveCommitHash, and debug fields.

Get Started

Essentials

Windows

Keybinds

Notices

Feature Flags

Event & Log Tracking

Logging

Deployment

Ads

Advanced

Extras

Example

The Two Bundles

applicationId

Choosing what to include

baseDir

Excluding files

Distribution only

More Info

​Example

​The Two Bundles

​applicationId

​Choosing what to include

​baseDir

​Excluding files

​Distribution only

​More Info

Example

The Two Bundles

applicationId

Choosing what to include

baseDir

Excluding files

Distribution only

More Info