Skip to main content
To run a Deskofy application, you must create a configuration file in JSON5 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
There is no strict naming rule for configuration files, but it’s recommended to follow the format:<env>.deskofy.config.json5

​
File Structure

Below is the complete structure of the Deskofy configuration file. 
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: 
['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: 
[
  ['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.
Setting it as testing may cause unexpected behavior.

​
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.
Each icon path should be defined as an array of folder names ending with the icon file name.
Paths should be relative to the configuration file directory. 
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 istrue, the application will not display until the page finishes loading. If false, the application loads immediately, which may show a blank screen briefly.
It is recommended to set this to true.

​
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. 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.
Each file path should be defined as an array of folder names ending with the file name, for example: ['folder', 'sub-folder', 'splash.html'].
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: 
[
  ['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: 
[
  ['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.
These options should be used with caution and are generally intended for advanced scenarios or trusted environments.

​
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.
⌘I