# Customizing the Electron BrowserWindow Configuration in chat-mcp: Options and Implementation

> Learn how to customize the Electron BrowserWindow configuration in ai-ql/chat-mcp. Explore options for size, appearance, security, and behavior by extending the BrowserWindow options.

- Repository: [AIQL/chat-mcp](https://github.com/ai-ql/chat-mcp)
- Tags: how-to-guide
- Published: 2026-02-23

---

**TLDR:** The **ai-ql/chat-mcp** repository enables **customizing the Electron BrowserWindow configuration** by extending the options object in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts), supporting all standard Electron window properties for size, appearance, security, and behavior.

The **ai-ql/chat-mcp** application renders its user interface through an Electron `BrowserWindow` instance created in the main process. While the default implementation prioritizes security, **customizing the Electron BrowserWindow configuration** allows developers to tailor window dimensions, visual styling, and behavioral characteristics to match specific deployment requirements or user preferences.

## Current Implementation in main.ts

The primary window is instantiated in [[`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts)](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) at line 111 using a minimal configuration:

```typescript
const mainWindow = new BrowserWindow({
  width: 1920,
  height: 1080,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: preloadPath
  }
});

```

This establishes a 1920×1080 pixel window with security-hardened `webPreferences`. Any standard Electron `BrowserWindow` constructor property can be added to this object to modify the window's behavior.

## Size and Layout Options

Control window dimensions and user resizing constraints by adding these properties to the configuration object:

- **`minWidth`** and **`minHeight`**: Define minimum dimensions in pixels to prevent the UI from breaking at small sizes. Example: `minWidth: 800, minHeight: 600`
- **`maxWidth`** and **`maxHeight`**: Set upper limits for window expansion. Example: `maxWidth: 2560, maxHeight: 1440`
- **`resizable`**: Boolean value allowing or preventing manual resizing. Defaults to `true`
- **`center`**: Automatically positions the window in the center of the primary display on launch
- **`fullscreen`**: Launch the application directly into fullscreen mode

## Appearance and Visual Styling

Modify the window chrome and loading experience with these **Electron BrowserWindow configuration** properties:

- **`title`**: Set the string displayed in the OS title bar or taskbar. Example: `title: 'Chat MCP'`
- **`backgroundColor`**: Specify a hex color code shown before the renderer content loads. Example: `backgroundColor: '#202020'`
- **`frame`**: Boolean to show or hide the native operating system window frame. Set to `false` to implement custom title bars
- **`transparent`**: Enable full window transparency for overlay-style applications
- **`titleBarStyle`**: macOS-specific option accepting `default`, `hidden`, or `hiddenInset` to customize the title bar appearance

## Web Preferences and Security Settings

The `webPreferences` object controls renderer process capabilities and security boundaries:

- **`nodeIntegration`**: Currently set to `false` to prevent exposing Node.js APIs to the renderer process, mitigating security risks
- **`contextIsolation`**: Enabled (`true`) to run preload scripts in an isolated context, protecting against prototype pollution attacks
- **`preload`**: References `preloadPath` pointing to [`src/preload/preload.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/preload/preload.ts), establishing a safe IPC bridge between main and renderer processes
- **`sandbox`**: Enable Chromium OS-level sandboxing with `sandbox: true` for additional process isolation
- **`webSecurity`**: Enforce same-origin policy and CORS restrictions
- **`enableRemoteModule`**: Explicitly disable the deprecated `remote` module with `false`

## Behavior and Performance Configuration

Control window interaction patterns and resource usage:

- **`show`**: Set to `false` to create the window hidden, allowing you to call `mainWindow.show()` only after content is ready to prevent visual flicker
- **`autoHideMenuBar`**: Hide the menu bar until the `Alt` key is pressed (Linux/Windows)
- **`skipTaskbar`**: Prevent the window from appearing in the system taskbar or dock
- **`alwaysOnTop`**: Keep the chat window floating above other applications
- **`focusable`**: Control whether the window can receive keyboard focus
- **`backgroundThrottling`**: Throttle JavaScript timers and animations when the application loses focus to conserve CPU
- **`webgl`**: Enable or disable WebGL support in the renderer process

## Practical Customization Example

To implement a frameless, centered window with minimum size constraints and a dark loading background while maintaining security:

```typescript
const mainWindow = new BrowserWindow({
  width: 1920,
  height: 1080,
  minWidth: 800,
  minHeight: 600,
  title: 'Chat MCP',
  backgroundColor: '#111111',
  frame: false,
  titleBarStyle: 'hidden',
  center: true,
  show: false,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: preloadPath,
    sandbox: true,
    webSecurity: true
  }
});

// Show window when ready
mainWindow.once('ready-to-show', () => {
  mainWindow.show();
});

```

This configuration preserves the security-focused defaults of **chat-mcp** while adding usability and visual polish.

## Key Files for Window Configuration

When **customizing the Electron BrowserWindow configuration**, reference these source files:

- **[`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts)**: Contains the `BrowserWindow` constructor and window lifecycle management. This is the primary location for adding configuration options.
- **[`src/preload/preload.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/preload/preload.ts)**: Defines the IPC bridge loaded via the `preload` path. Changes to `contextIsolation` or `sandbox` settings must align with this file's exports.
- **[`src/renderer/index.html`](https://github.com/ai-ql/chat-mcp/blob/main/src/renderer/index.html)**: The HTML entry point displayed within the window. Affected by `backgroundColor` and dimension settings.

## Summary

- The **chat-mcp** application initializes its main window in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) with security-first defaults including `nodeIntegration: false` and `contextIsolation: true`
- All standard Electron `BrowserWindow` options are available for **customizing the Electron BrowserWindow configuration**, including size constraints, visual styling, and behavioral controls
- The `webPreferences` object manages critical security boundaries, with the `preload` script providing controlled access to main process APIs
- Options like `frame`, `titleBarStyle`, and `backgroundColor` enable platform-specific customization without compromising the application's IPC security model

## Frequently Asked Questions

### How do I prevent the chat-mcp window from being resized below certain dimensions?

Add `minWidth` and `minHeight` properties to the `BrowserWindow` constructor options in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts). For example, setting `minWidth: 800, minHeight: 600` ensures the chat interface maintains usable proportions even when users attempt to shrink the window.

### What security settings must I preserve when customizing the window configuration?

Always maintain `nodeIntegration: false` and `contextIsolation: true` as implemented in the original codebase. These settings prevent renderer process scripts from accessing Node.js APIs or manipulating JavaScript prototypes. If you enable `sandbox: true`, verify that your [`src/preload/preload.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/preload/preload.ts) script correctly exposes only necessary IPC methods.

### Can I make the chat-mcp window frameless while keeping it draggable?

Yes. Set `frame: false` and `titleBarStyle: 'hidden'` in the BrowserWindow options, then add a draggable region in your renderer HTML using CSS `-webkit-app-region: drag`. This removes the native title bar while allowing users to drag the window by your custom header area, common in modern chat applications.

### Where is the preload script configured in the chat-mcp repository?

The `preloadPath` variable passed to `webPreferences.preload` in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) points to the compiled output of [`src/preload/preload.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/preload/preload.ts). This script establishes the secure communication bridge between the Electron main process and the renderer, enabling controlled access to native APIs while maintaining process isolation.