> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deskofy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration File

To run a Deskofy application, you must create a configuration file in [JSON5](https://json5.org) format (not plain JSON).

The default configuration file name is `deskofy.config.json5`, and it is recommended to use this file during development.

You can also create separate configuration files for different environments, for example:

* `staging.deskofy.config.json5`
* `production.deskofy.config.json5`

<Note>
  There is **no strict naming rule** for configuration files, but it’s recommended to follow the format:`<env>.deskofy.config.json5`
</Note>

# File Structure

Below is the complete structure of the **Deskofy configuration file**.

```typescript theme={null}
type TDeskofyConfigSchema = {
  environment: string; // Required
  name: string; // Required
  description: string;
  author: string;
  packageName: string; // Required
  version: string;
  domain: string; // Required
  icons: {
    mac: string[];
    windows: string[];
    linux: string[];
  };
  windowStartup: {
    shouldShowBeforeLoadingComplete: boolean;
    shouldEnableSplashScreen: boolean;
  };
  windowSize: {
    height: number;
    width: number;
    minHeight: number;
    minWidth: number;
  };
  windowLayout: {
    shouldHideTitleBar: boolean;
    shouldEnableFrame: boolean;
    shouldDisableAutoHideCursor: boolean;
    shouldHaveRoundCorners: boolean;
    shouldEnableShadows: boolean;
  };
  windowOptions: {
    shouldMovable: boolean;
    shouldMinimizable: boolean;
    shouldMaximizable: boolean;
    shouldClosable: boolean;
    shouldFocusable: boolean;
    shouldFullscreenable: boolean;
    shouldRestoreState: boolean;
  };
  windowColors: {
    dark: string;
    light: string;
  };
  externalLinks: {
    shouldOpenNonAppLinksExternally: boolean;
  };
  htmlPages: {
    splashScreen: string[];
    offline: string[];
    httpNotAllowed: string[];
  };
  plugins: string[][];
  rendererPlugins: string[][];
  development: {
    shouldOpenDevToolsWhenRun: boolean;
  };
  highRisk: {
    shouldLoadHTTPDomains: boolean;
    shouldEnableWebSecurity: boolean;
    shouldAllowRunningInsecureContent: boolean;
    shouldEnableExperimentalFeatures: boolean;
  };
};
```

## Rules for Path-specific Fields

These details are explained in the related sections, but they are reiterated here for clarity. In the configuration file, **all file paths must be specified as an array of strings**.

For example, if you need to reference a file located at `assets/icons/mac/mac.icns`, the path should be defined as:

```json theme={null}
['assets', 'icons', 'mac', 'mac.icns'] // Path is assets/icons/mac/mac.icns
```

It is important to always use the **exact file path** in the configuration. However, for **plugins**, you must reference the **compiled JavaScript file** rather than the TypeScript source. For instance, if you create a plugin at `src/samplePlugin.ts`, it will be compiled to `runtime/samplePlugin.js` when building or running the project. In this case, the path in the configuration should be set as:

```json theme={null}
[
  ['runtime', 'samplePlugin.js'] // Path is runtime/samplePlugin.js
]
```

This ensures that Deskofy loads the correct runtime files instead of the original TypeScript sources.

# Configuration Fields

## Environment `environment`

The `environment` field identifies the current environment for the application. Although Deskofy runs on **Node.js** and supports the `NODE_ENV` variable, the framework itself does not use `NODE_ENV`. You can set `environment` based on your deployment target. \*\*Do not use \*\*`testing` as the environment name, as it is reserved for internal development.

<Warning>
  Setting it as `testing` may cause unexpected behavior.
</Warning>

## Name `name`

The `name` field defines the name of your application and is also used during the build process.

## Description `description`

The `description` field allows you to add a brief description of your project.

## Author `author`

The `author` field specifies the author of the project, which can be an individual, a team, a company, or an organization. There is no strict format, but a recommended style is: `<Name> (<Email>)`.

## Package Name `packageName`

The `packageName` field is mainly used by the Node.js ecosystem. When defining this value, follow the standard naming conventions used in `package.json`.

## Version `version`

The `version` field represents the current version of your application. It should follow **semantic versioning** with `major.minor.patch` format. Examples include `1.0.0`, `1.0.1`, or `12.9.8`.

## Domain `domain`

The `domain` field specifies the starting URL of the application. When the app runs, this URL will be opened automatically. It can be either an `http` or `https` URL.

## Icons `icons`

The `icon` field sets the application icon paths. You must provide separate icons for **Windows**, **Linux**, and **macOS**.

<Note>
  Each icon path should be defined as an array of folder names ending with the icon file name.
</Note>

Paths should be relative to the configuration file directory.

```json theme={null}
icons: {
  mac: ['folder', 'mac', 'icon.icns'],        // Path: folder/mac/icon.icns
  windows: ['folder', 'windows', 'icon.ico'], // Path: folder/windows/icon.ico
  linux: ['folder', 'linux', 'icon.png']      // Path: Folder/linux/icon.png
}
```

## Window Startup `windowStartup`

The `windowStartup` field defines how the application launches

### ` shouldShowBeforeLoadingComplete`

If this is`true`, the application will not display until the page finishes loading. If `false`, the application loads immediately, which may show a blank screen briefly.

<Note>
  It is recommended to set this to `true`.
</Note>

### `shouldEnableSplashScreen`

If this is `true`, a splash screen will be displayed while the page loads. You can provide a custom HTML splash screen; otherwise, the default splash screen is used. The splash screen only appears if the page loading takes noticeable time; in most cases, the page loads immediately.

## Window Size `windowSize`

The `windowSize` field defines the default dimensions of the main application window:

### `height`

The default height of the application window defines its initial vertical size when the app launches. The value must be greater than `0`.

### `width`

The default width of the application window sets its initial horizontal size. Like height, it must also be greater than `0`.

### `minHeight`

The minimum height specifies the smallest vertical size the window can be resized to. It must be greater than `0` and less than the default height. Users will not be able to resize the window below this value.

### `minWidth`

The minimum width defines the smallest horizontal size the window can be resized to. It must be greater than `0` and less than the default width. Users cannot reduce the window width below this limit.

## Window Layout `windowLayout`

The `windowLayout` field contains nested properties to control the main window’s appearance and behavior:

### `shouldHideTitleBar`

The `shouldHideTitleBar` property, when set to `true`, hides the default OS-specific title bar from the window. This is useful when creating a custom title bar or a frameless window design.

### `shouldEnableFrame`

The `shouldEnableFrame` property controls the visibility of the application frame. If set to `false`, the standard window frame is removed, allowing for a fully customized window appearance.

### `shouldDisableAutoHideCursor`

The `shouldDisableAutoHideCursor` property determines cursor behavior while typing. When set to `true`, the cursor will remain visible instead of automatically hiding, which can improve usability in certain input-heavy applications.

### `shouldHaveRoundCorners`

The `shouldHaveRoundCorners` property enables OS-specific rounded corners on the window when set to `true`. This provides a more modern and native look, particularly on macOS and Windows.

### `shouldEnableShadows`

The `shouldEnableShadows` property adds default OS-specific shadows to the window when set to `true`. This enhances visual depth and distinguishes the application window from the background, improving overall aesthetics and user experience.

## Window Options `windowOptions`

### `shouldMovable`

The `shouldMovable` property determines whether the application window can be moved by the user. When set to `true`, users can drag the window around the screen; setting it to `false` locks the window in place.

### `shouldMinimizable`

The `shouldMinimizable` property controls whether the window can be minimized. If `true`, the minimize button is enabled, allowing users to send the window to the taskbar or dock.

### `shouldMaximizable`

The `shouldMaximizable` property defines whether the window can be maximized to fill the screen. When set to `true`, the maximize button is active; if `false`, users cannot expand the window.

### `shouldClosable`

The `shouldClosable` property determines if the window can be closed by the user. If `true`, the close button is enabled; setting it to `false` prevents accidental or manual closure of the application.

### `shouldFocusable`

The `shouldFocusable` property controls whether the window can receive focus. If `true`, the window can be selected and interacted with; if `false`, it remains unfocused and ignores user input.

### `shouldFullscreenable`

The `shouldFullscreenable` property specifies whether the window can enter fullscreen mode. When set to `true`, users can toggle fullscreen, providing a distraction-free experience.

### `shouldRestoreState`

The `shouldRestoreState` property determines whether the window should remember its last position and size between sessions. If `true`, the application restores the previous window state on launch, enhancing user continuity.

## Window Colors `windowColors`

The `windowColors` property allows you to define default colors for the application window based on the operating system’s theme.

### `dark`

The `dark` field specifies the window color when the OS is in **dark mode**. This ensures that the application visually matches the user’s system theme and maintains readability and aesthetic consistency.

### `light`

The `light` field defines the window color when the OS is in **light mode**. Using this color ensures that the window blends seamlessly with the system’s light theme, providing a cohesive user experience.

## External Links `externalLinks`

The `externalLinks` property controls how links that lead outside the application are handled.

### `shouldOpenNonAppLinksExternally`

The `shouldOpenNonAppLinksExternally` field, when set to `true`, ensures that any link not part of the Deskofy application opens in the user’s default web browser instead of within the app window. This prevents unexpected navigation inside the application and maintains a clear separation between internal and external content.

## HTML Pages `htmlPages`

The `htmlPages` property defines custom HTML pages that the application can display in specific states.

<Note>
  Each file path should be defined as an array of folder names ending with the file name, for example: `['folder', 'sub-folder', 'splash.html']`.
</Note>

For each HTML page used by the application, **specific file names are recognized automatically**. If the HTML files match these names, Deskofy will identify and use them correctly without additional configuration. The recognized files are:

* `splash-screen.html`: used for the loading state of the application.
* `not-allowed.html`: displayed when a requested page cannot be loaded or is not allowed.
* `offline.html`: shown when the application is offline or cannot access the internet.

Using these specific file names ensures that the application correctly handles different runtime states automatically.

### `splashScreen`

The `splashScreen` field specifies the HTML page shown during the **loading state** of the application. These page appear while the main content is initializing, providing visual feedback to the user.

### `offline`

The `offline` field defines the HTML page displayed when the application detects **no internet connection**. This allows you to show a user-friendly offline message or interface. File path follow the same array structure as other HTML pages.

### `httpNotAllowed`

The `httpNotAllowed` field specifies the HTML page shown when a requested page **cannot be loaded**. This ensures users receive clear feedback when navigation fails. File path must also be defined as arrays of folder names ending with the file name.

## Plugins `plugins`

The `plugins` field is a string path array that allows you to define custom plugins for your application.

Each entry must point to the **compiled JavaScript file**, not the original TypeScript source. For example, if your plugin source is located at `/src/plugin.ts` and it compiles to `runtime/plugin.js`, you should set the path as:

```json theme={null}
[
  ['runtime'], ['plugin.js'] // Path is runtime/plugin.js
]
```

This ensures that the Deskofy framework loads the correct runtime files for your plugins.

## Renderer Plugins `rendererPlugins`

The `prendererPlugins` field is a string path array that allows you to define custom renderer plugins for your application.

Each entry must point to the **compiled JavaScript file**, not the original TypeScript source. For example, if your plugin source is located at `/src/rendererPlugin.ts` and it compiles to `runtime/rendererPlugin.js`, you should set the path as:

```json theme={null}
[
  ['runtime'], ['rendererPlugin.js'] // Path is runtime/rendererPlugin.js
]
```

This ensures that the Deskofy framework loads the correct runtime files for your plugins.

## Development `development`

The `development` field provides options specifically for **development mode**.

### `shouldOpenDevToolsWhenRun`

The `shouldOpenDevToolsWhenRun` property, when set to `true`, automatically opens the browser or Electron **developer tools** each time the application starts. This is useful for debugging, inspecting elements, and monitoring console output during development. It should generally be disabled in production builds to prevent exposing developer tools to end users.

## HighRisk `highRisk`

The `highRisk` field contains settings that can impact application security and stability.

<Warning>
  These options should be used **with caution** and are generally intended for advanced scenarios or trusted environments.
</Warning>

### `shouldLoadHTTPDomains`

The `shouldLoadHTTPDomains` property, when set to `true`, allows the application to load content over **insecure HTTP** connections. This can be useful for testing or internal sites but may expose users to security risks.

### `shouldEnableWebSecurity`

The `shouldEnableWebSecurity` property controls the browser’s security policies. If set to `false`, standard web security restrictions (such as same-origin policy) are disabled, which can be useful for development but is unsafe for production.

### `shouldAllowRunningInsecureContent`

The `shouldAllowRunningInsecureContent` property permits the execution of **mixed content**, such as scripts or resources loaded over HTTP within an HTTPS page. Enabling this can compromise security, so it should only be used in controlled environments.

### `shouldEnableExperimentalFeatures`

The `shouldEnableExperimentalFeatures` property activates **experimental Electron / browser features** that may not be stable or fully supported. This allows testing of new APIs but may introduce unpredictable behavior in the application.