# How to Configure URL Parameters at Startup in Draw.io Desktop Using urlParams.json

> Learn how to configure urlParams.json at startup in Draw.io Desktop. Easily set startup URL parameters for custom editor configurations. Get started now.

- Repository: [draw.io/drawio-desktop](https://github.com/jgraph/drawio-desktop)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Create a [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json) file in the application root directory containing a JSON object of query parameters; Draw.io Desktop automatically reads this file at startup and appends the parameters to the editor URL before the Electron window loads.**

The **drawio-desktop** repository wraps the Draw.io web editor in an Electron application. By leveraging a configuration file named **urlParams.json**, you can inject any supported URL query parameters—such as developer mode, theme settings, or UI toggles—without modifying the source code or recompiling the application.

## How urlParams.json Works in Draw.io Desktop

In [`src/main/electron.js`](https://github.com/jgraph/drawio-desktop/blob/main/src/main/electron.js), the main process checks for the existence of [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json) immediately before creating the **BrowserWindow**. If the file is present, its contents are parsed and transformed into a query string using the **`URLSearchParams`** API, then appended to the local [`index.html`](https://github.com/jgraph/drawio-desktop/blob/main/index.html) URL loaded by the window.

The implementation follows these steps as defined in the source:

1. Resolves the file path via **`path.join(app.getAppPath(), 'urlParams.json')`**.
2. Validates existence using **`fs.existsSync`**.
3. Reads the file with **`fs.readFileSync`** and parses the JSON.
4. Converts the object to a query string.
5. Concatenates the string to the file URL passed to **`mainWindow.loadURL`**.

```javascript
// src/main/electron.js
let urlParams = '';
try {
    const paramsPath = path.join(app.getAppPath(), 'urlParams.json');
    if (fs.existsSync(paramsPath)) {
        const raw = fs.readFileSync(paramsPath, 'utf8');
        const json = JSON.parse(raw);
        const query = new URLSearchParams(json).toString();
        if (query) {
            urlParams = `?${query}`;
        }
    }
} catch (e) {
    console.error('Failed to load urlParams.json:', e);
}

// Applied when loading the editor
mainWindow.loadURL(`file://${path.join(__dirname, '../drawio/src/main/webapp/index.html')}${urlParams}`);

```

If the file is missing, unreadable, or contains invalid JSON, the error is caught and logged to the console, and the application falls back to loading the editor without additional parameters.

## Creating and Formatting urlParams.json

### File Location

Place [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json) in the **application root directory**—the same folder that contains [`package.json`](https://github.com/jgraph/drawio-desktop/blob/main/package.json). For packaged production builds, locate the file in the same directory as the Draw.io Desktop executable so that **`app.getAppPath()`** resolves correctly.

### JSON Structure

The file must contain a single JSON object where each key becomes a query parameter name and each value becomes the parameter value. All values are coerced to strings during URL construction.

```json
{
  "dev": "1",
  "embed": "1",
  "gapi": "0",
  "lightbox": "0"
}

```

This example results in the following URL being loaded inside the **BrowserWindow**:

```

file:///.../drawio/src/main/webapp/index.html?dev=1&embed=1&gapi=0&lightbox=0

```

## Practical Configuration Examples

### Enable Developer Mode

To start the application with developer tools enabled and diagnostic logging active:

```json
{
  "dev": "1",
  "chrome": "0"
}

```

### Configure Embed Settings

For a minimal interface suitable for embedded diagram editing:

```json
{
  "embed": "1",
  "toolbar": "false",
  "nav": "false"
}

```

### Dynamic Parameter Generation

You can programmatically generate [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json) before launch to inject environment-specific configuration:

```javascript
const fs = require('fs');
const path = require('path');

const params = {
  dev: process.env.DRAWIO_DEV || '0',
  theme: process.env.DRAWIO_THEME || 'kennedy',
  lang: 'en'
};

fs.writeFileSync(
  path.join(__dirname, 'urlParams.json'),
  JSON.stringify(params, null, 2)
);

```

After writing the file, start the desktop application to apply the dynamic settings.

## Verifying Applied Parameters

To confirm that parameters are correctly injected:

1. Launch Draw.io Desktop with DevTools enabled (set the environment variable `DRAWIO_ENV=dev` or press `Ctrl+Shift+I`).
2. Open the Console tab.
3. Execute the following:

```javascript
console.log(window.location.href);

```

The output should display the full file protocol URL, including the query string constructed from [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json).

## Summary

- **urlParams.json** provides a declarative, code-free method to configure startup URL parameters in the drawio-desktop application.
- The file must reside in the application root and contain valid JSON key-value pairs.
- [`src/main/electron.js`](https://github.com/jgraph/drawio-desktop/blob/main/src/main/electron.js) handles detection and parsing using `fs.existsSync`, `fs.readFileSync`, `JSON.parse`, and `URLSearchParams`.
- Parameters are appended to the local [`index.html`](https://github.com/jgraph/drawio-desktop/blob/main/index.html) path before `mainWindow.loadURL` executes.
- Errors during file reading or parsing are logged but do not block application startup.

## Frequently Asked Questions

### Where should I place the urlParams.json file?

Place the file in the application root directory alongside [`package.json`](https://github.com/jgraph/drawio-desktop/blob/main/package.json). For packaged builds, ensure it sits in the same folder as the executable binary so that `app.getAppPath()` locates it correctly.

### What happens if the JSON is malformed?

If `JSON.parse` throws an exception or the file cannot be read, the error is caught by the try-catch block in [`src/main/electron.js`](https://github.com/jgraph/drawio-desktop/blob/main/src/main/electron.js) and logged via `console.error`. The application continues launching but loads the editor without any additional URL parameters.

### Can I use urlParams.json with the packaged desktop application?

Yes. This configuration method works for both development environments (`npm start`) and production distributions. Ensure the file is copied into the packaged app’s root directory during your build pipeline or placed there manually after installation.

### Are there any limitations on which URL parameters work?

Any parameter supported by the web version of Draw.io can be passed via [`urlParams.json`](https://github.com/jgraph/drawio-desktop/blob/main/urlParams.json). However, parameters that require external network resources—such as live Google Drive integration or specific cloud APIs—may function differently or be disabled in the offline desktop environment depending on Electron's sandbox and CSP settings.