OverlayedOptions

All overlay configuration happens within your codebase, which gives full flexibility. The following properties can be passed into the overlayed function:

​

electron

The electron instance to use for the overlay. Note this should be globally imported from the electron package.

• Type
  electron: Electron;
  
• Example
  import { overlayed } from "@overlayed/app";
  import electron from "electron";
  
  const overlay = overlayed({
  	electron,
  	// ...
  });
  

​

applicationId

The id of the application, this can be found in the Overlayed Dashboard

• Type
  applicationId: string;
  
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	applicationId: "APPLICATION_ID_GOES_HERE",
  	// ...
  });
  

​

modules

The modules to load.

• Type
  interface OverlayedOptions<TModule extends GameModule> {
  	modules: TModule[];
  }
  
• Details Modules allow you to subscribe to a specific game, including:
  • Game Events
  • Overlay Events like when the game launches
• Example
  import * as Siege from "@overlayed/app/siege";
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	modules: [Siege.module()],
  	// ...
  });
  

​

keybinds

The app’s keybinds

• Type
  interface OverlayedOptions<TKeybind extends string> {
  	keybinds: OverlayedAppKeybindsConfig<TKeybind>[];
  }
  
  type OverlayedAppKeybindsConfig<TKeybind extends string> = Record<
  	TKeybind,
  	{
  		keys: OverlayedAppKeybindsConfigKey[];
  		mode: OverlayedAppKeybindsConfigMode;
  	}
  >;
  
  type OverlayedAppKeybindsConfigMode = "toggle" | "hold";
  type OverlayedAppKeybindsConfigKey =
  	| "ControlLeft"
  	| "AltLeft"
  	| "ShiftLeft"
  	| "AltRight"
  	| "ControlRight"
  	| "ShiftRight"
  	| (string & {});
  
• Details Keybinds require the array of KeyboardEvent#code and the mode of the keybind.
  • “Hold” will trigger the callback when the keybind is held down.
  • “Toggle” will trigger the callback when the keybind is toggled on and off.
  Read more here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	keybinds: {
  		toggleMainWindow: {
  			keys: ["ControlLeft", "KeyY"],
  			mode: "toggle",
  		},
  	},
  });
  

​

init

• Type
  	init?: boolean;
  
• Default: true
• Details Whether to initialize the overlay right when the function is called. Read more here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	init: false,
  });
  

​

universal

• Type
  	universal?: boolean;
  
• Default: false
• Details When true, the overlay will be loaded and attempt to render inside of all supported games. When false, only games registered under the modules array will be loaded. Read more here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	universal: true,
  });
  

​

debug

• Type
  	debug?: boolean;
  
• Default: false
• Details When enabled:
  • logger.debug() logs will be printed and saved to the log file
  Warning: Debug mode should be disabled in production environments as it can impact performance and generate large log files. Read more about logging here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	debug: process.env.NODE_ENV === "development",
  });
  

​

analytics

Analytics configuration.

• Type
  analytics?: {
  	webVitals?: boolean;
  	crashes?: boolean;
  };
  
• Default: { webVitals: true, crashes: true }
• Details webVitals: when true, windows created via overlay.windows report Core Web Vitals (LCP, INP, FCP, TTFB, CLS) as a web_vitals event once per page load. The window’s preload script must import @overlayed/app/preload. When false, the preload doesn’t collect any metrics and the main process doesn’t listen for them. Read more here. crashes: when true, app crashes are reported to Overlayed. When false, crash reporting is turned off. Read more here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	analytics: {
  		webVitals: false,
  	},
  });
  

​

featureFlags

A record of feature flag names to their default values. Keys provide typed access to remotely managed flags, values are used as defaults before the API responds or when a flag is missing.

• Type
  featureFlags?: Record<string, boolean>;
  
• Default: undefined
• Details Registered flag names enable type-safe access via overlay.featureFlags.get(flagName) and overlay.featureFlags.on(flagName, cb). Warnings are logged if a registered flag is not found in the API response. The featureFlags module also exposes a ready promise that resolves once the initial fetch completes. Read more here.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	featureFlags: { "new-scoreboard": false, "beta-hud": false },
  });
  
  // Optionally wait for flags before proceeding
  await overlay.featureFlags.ready;
  
  if (overlay.featureFlags.get("new-scoreboard")) {
  	// Feature is enabled
  }
  

​

navigationGuard

Configuration for the navigation guard applied to every window created via overlay.windows.

• Type
  navigationGuard?: {
  	allowedHosts?: string[];
  	windowOpenHandler?: (details: { url: string }) => "allow" | "external" | "deny" | undefined;
  };
  
• Default: undefined
• Details By default, top-frame navigation is restricted to your application’s own origin and the origin currently loaded in the window, and window.open to any other web URL opens in the system browser, but only right after a click or key press in the window. allowedHosts adds additional hosts the main frame may navigate to (e.g. an OAuth provider). windowOpenHandler overrides the window.open policy per-URL; return undefined to fall back to the default policy. See Navigation Guard for the full policy and examples.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	navigationGuard: {
  		allowedHosts: ["auth.ubisoft.com"],
  		windowOpenHandler: ({ url }) => {
  			if (new URL(url).host === "checkout.stripe.com") {
  				return "allow";
  			}
  			return undefined;
  		},
  	},
  });
  

​

site

• Type
  site?: {
  	manualUpdates?: boolean;
  };
  
• Default: { manualUpdates: false }
• Details Configuration for site (frontend) updates. When manualUpdates is true, your site will not automatically update when a new version is deployed. Instead, you can listen for the siteUpdateReady event on overlayed.updater.site and prompt users to update. See Site Updates for more information.
• Example
  import { overlayed } from "@overlayed/app";
  
  const overlay = overlayed({
  	site: {
  		manualUpdates: true,
  	},
  });
  
  // Listen for new site versions
  overlay.updater.site.on("siteUpdateReady", ({ version }) => {
  	overlay.log.info(`New site version available: ${version}`);
  });