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

Create a 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, the main process checks for the existence of 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 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.

// 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 in the application root directory—the same folder that contains 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.

{
  "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:

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

Configure Embed Settings

For a minimal interface suitable for embedded diagram editing:

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

Dynamic Parameter Generation

You can programmatically generate urlParams.json before launch to inject environment-specific configuration:

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:

console.log(window.location.href);

The output should display the full file protocol URL, including the query string constructed from 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 handles detection and parsing using fs.existsSync, fs.readFileSync, JSON.parse, and URLSearchParams.
• Parameters are appended to the local 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. 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}