Skip to main content

neutralino.config.json

neutralino.config.json file contains the application configuration details. Every Neutralinojs app typically loads the following keys from the config file.

  • applicationId
  • url
  • defaultMode

However, having a config file is not mandatory to start a Neutralinojs app since the Neutralinojs framework often loads reasonable defaults for all configuration options.

You can develop Neutralinojs apps with a well-structured configuration file. Or, you can start the framework without a configuration file using CLI arguments, as shown in the following code snippet:

# Loading a remote URL
./framework-bin --url=https://neutralino.js.org/docs

# Launches a local static web app
./framework-bin --url="/" --document-root="/resources/" --window-title="My web app" --enable-server --enable-native-api

Primary​

The following configuration values cannot be overridden in different Neutralinojs modes.

applicationId: string​

Unique string to identify your application. Eg: js.neutralino.sample

version: string​

Application version. Eg: 2.4.22

defaultMode: string​

Mode of the application. Accepted values are window, browser, cloud, and chrome.

General​

You can override the following configuration values from different modes. For example, you can use a specific URL in root-level and another URL in window-mode-level, as shown below.

{
    "url": "/"
    "modes": {
        "window": {
            "url": "/#window-mode"
        }
    }
}

port: number​

The port of your application. If the value is 0, Neutralinojs will use a random available port.

enableServer: boolean​

Enables or disables the background server (Disables static file servering feature and native API messaging). If you load a remote URL to the webview, you can set this option to false. Make sure to set this option to true if you load resources from local sources. The default value is false.

enableNativeAPI: boolean​

Enables or disables the native API. If you want to use any native API functions, you can set this option to true. The default value is false.

singlePageServe: boolean​

Activates SPA (Single Page App) serving. When this option is enabled, the static server module serves the primary index.html file for sub-directory requests only if another index.html doesn't exist in a specific sub-directory. The default value for this option is false.

tokenSecurity: string​

Neutralinojs uses a client-server communication pattern with a local WebSocket to handle native calls. This local server is protected with an auto-generated token. This option defines the security implementation for the token.

Accepts the following values:

  • one-time (Recommended) : Server sends the access token only once, and the client persists it in the sessionStorage. If another client (Eg: browser) tries to access the app, NE_RT_INVTOKN error message will be shown instead of the application. Using this option is recommended since it reduces security issues.

  • none : Server sends the access token always, so any new client can see the application.

The default value becomes one-time if this setting is not specified by the developer.

danger

If you are using native APIs that can access your computer's internals such as os, filesystem, modules, never use none option since any new client can use those APIs.

url: string​

The entry URL of the application. Neutralinojs will initially load this URL. This property accepts both relative and absolute URLs. See following examples.

"url": "/"

The above config loads http://localhost:<port>/ URL initially (internally /index.html is loaded). You can use remote urls too.

"url": "http://example.com"

documentRoot: string​

Sets the document root for the static server. For example, if you need to use resources directory as the document root, you can use setup documentRoot as follows.

{
    "documentRoot": "/resources/",
    "url": "/"
}

Make sure to configure url properly with the document root. The following configuration is wrong, it instructs the static server to fetch resources from ./resources/resources.

{
    "documentRoot": "/resources/",
    "url": "/resources/"
}

However, you can use a sub-directory in URL, as shown below.

{
    "documentRoot": "/",
    "url": "/resources/"
}

exportAuthInfo: boolean​

Exports authentication details to the ${NL_PATH}/.tmp/auth_info.json file with the following JSON structure.

{
    "port": "<port>",
    "accessToken": "<access_token>"
}

You can use the above authentication details to connect with Neutralinojs from external processes by using WebSocket as an IPC mechanism.

enableExtensions: boolean​

Enables/disables extensions. Learn more about this option here

extensions: object[]​

An array of extension definitions. Learn more about this option here

nativeBlockList: string[]​

An array of native methods needs to be blocked from the frontend of the application. The wildcard character * is allowed inside entries.

{
    "nativeBlockList": ["os.execCommand"],
    "nativeBlockList": ["app.*"]
}

nativeAllowList: string[]​

An array of native methods needs to be allowed from the frontend of the application. The wildcard character * is allowed inside entries.

{
    "nativeAllowList": ["os.getEnv"],
    "nativeAllowList": ["storage.*"]
}

globalVariables: object​

A key-value-based JavaScript object of custom global variables.

logging.enabled: boolean​

Enables or disables the logging feature.

logging.writeToLogFile: boolean​

Enables or disables log file. If this setting is false, the framework won't write log to neutralinojs.log, and it will write logs to standard streams.

serverHeaders: object​

Custom headers for the static server and Websocket handshake process. For example, the following configuration sends a custom header with every outgoing HTTP response.

{
    "serverHeaders": {
        "Test-Header-Option": "Value"
    }
}

dataLocation: string​

Configures the internal framework data files storage directory.

Accepts the following values:

  • app (default): Stores framework data files within the app directory.

  • system : Stores framework data files within the system application data directory (i.e., /home/username/.local/share/<applicationId> on GNU/Linux systems). App developers can obtain the current data directory string from the NL_DATAPATH global variable.

storageLocation: string​

Configures the Neutralinojs storage location.

Accepts the following values:

  • app (default): Stores .neustorage files within .storage directory of the app directory.

  • system : Stores .neustorage files within the system application data directory (i.e., /home/username/.local/share/<applicationId>/.storage on GNU/Linux systems).

Window mode​

The following configuration values are used when the application runs with the window mode.

modes.window.title: string​

Title of the native window.

modes.window.width: number​

Width of the native window.

modes.window.height: number​

Height of the native window.

modes.window.minWidth: number​

Minimum width of the native window.

modes.window.minHeight: number​

Minimum height of the native window.

modes.window.maxWidth: number​

Maximum width of the native window.

modes.window.maxHeight: number​

Maximum height of the native window.

modes.window.x: number​

Left position (x) of the native window.

modes.window.y: number​

Right position (y) of the native window.

modes.window.center: boolean​

Centers the native app window initially.

modes.window.transparent: boolean​

Enables the transparent native window mode for the application instance. If the transparency mode is activated, users can see through the webview if the webpage background uses transparent background colors. Partial transparency can be activated using the rgba() CSS color function. You can use this feature to create semi-transparent windows, windows with custom shadows, and custom-shaped window frames.

The default value is false for this option.

info

Unlike in other platforms, Windows native window becomes borderless (window controls will be hidden) with the activation of the transparent mode.

modes.window.fullScreen: boolean​

Activates the full-screen mode.

modes.window.icon: string​

Application icon's file name. You can directly point to an image file in the resources directory. We recommend you to choose a transparent PNG file.

modes.window.alwaysOnTop: boolean​

Activates the top-most mode.

modes.window.enableInspector: boolean​

Automatically opens the developer tools window.

modes.window.borderless: boolean​

Activates the borderless mode.

modes.window.maximize: boolean​

Launches the application maximized.

modes.window.resizable: boolean​

Make the window resizable or not. The default value is true.

modes.window.hidden: boolean​

Make the window invisible. This setting can be used to develop background services.

modes.window.exitProcessOnClose: boolean​

If this setting is true, the app process will exit when the user clicks on the close button. Otherwise, the framework will dispatch the windowClose event.

modes.window.useSavedState: boolean​

Save and load the primary window state (width, height, x, y, values and maximized status) automatically. The default value is true.

modes.window.extendUserAgentWith: string​

Extends the default webview-specific user agent string with a custom suffix. If this value is not set, the webview sets the default user agent from the platform-specific rendering engine (i.e., WebKit on GNU/Linux).

modes.window.injectGlobals: boolean​

Injects global variables directly to the webview instance. If you use this feature, you don't need to include __neutralino_globals.js or neutralino.js file to receive Neutralinojs global variables to your web app.

modes.window.injectClientLibrary: boolean​

Injects global variables and the client library implementation directly to the webview instance. If you use this feature, you don't need to include the client library manually via the neutralino.js file or from the @neutralinojs/lib NPM module.

modes.window.injectScript: string​

Injects a preload JavaScript file to the webview instance from the app bundle. This script file will be executed before webapp resources and after window.injectGlobals and window.injectClientLibrary scripts, so you can write initialization scripts using Neutralinojs API within this source file.

Chrome mode​

The following configuration values are used when the application starts with the chrome mode.

modes.chrome.width: number​

Width of the chrome window.

modes.chrome.height: number​

Height of the chrome window.

modes.chrome.args: string​

Additional command-line arguments for the Chrome process. Read more about chrome mode from here

CLI​

The following configuration values are used for the neu CLI.

cli.binaryName: string​

Binary file name of your application. If it is myapp, all binaries will use myapp-<platform>_<arch> format.

cli.resourcesPath: string​

Path of your application resources.

cli.resourcesExclude: string​

Regex pattern to exclude files from final app bundle. For example, the following configuration will exclude all the TypeScript source files from the final build:

{
    "resourcesExclude" : ".*\\.ts$|.*\\.tsx$"
}

cli.extensionsPath: string​

Path of your application extensions.

cli.extensionsExclude: string​

Regex pattern to exclude files from the extensions directory of the final app package. For example, the following configuration will exclude .log and .info files:

{
    "extensionsExclude" : ".*\\.log$|.*\\.info$"
}

cli.clientLibrary: string​

Filename of the Neutralinojs JavaScript library.

cli.binaryVersion: string​

Neutralinojs server version. Get nightly builds by using the nightly tag.

cli.clientVersion: string​

Neutralinojs client version. Get nightly builds by using the nightly tag.

cli.autoReloadExclude: string​

A JavaScript regular expression to exclude files from the auto-reload file watcher. For example, the following configuration will disable auto-reloading for SASS stylesheets (.scss).

{
    "autoReloadExclude": ".*\\.scss$"
}

Use | character to set multiple regular expressions, as shown below.

{
    "autoReloadExclude": ".*\\.scss$|.*\\.less$"
}

cli.frontendLibrary: object​

Enables frontend development tools (HMR, etc) for the neu run command. Learn more about frontend framework integration from here

cli.hostProject.projectPath: string​

Sets the project path of the host project. This path will be used as the current directory while executing the host-project-related commands.

cli.hostProject.initCommand: string​

A command that gets executed after downloading an host app template with the neu create command.

cli.hostProject.devCommand: string​

This command will run with the neu run command to start the host project.

cli.hostProject.buildCommand: string​

The neu build command will execute this command before generating the app bundle, so you can generate bundled version of host project code.

cli.hostProject.buildPath: string​

Location where the final read-to-distribute host project files will be stored after the execution of buildCommand. Files in this folder are copied into the app bundle path after the execution of neu build command.

cli.distributionPath: string​

Sets the build path for neu CLI. For example, if you need to get the built binaries in build folder instead of dist, you can set the distributionPath as follows:

{
    "distributionPath": "/build",
}

The default value for distributionPath is /dist.

cli.copyItems: string[]​

Copies non-resource items (configurations, scripts, etc.) to the final application bundle. Supports files and directories:

{
    "copyItems": ["/scripts", "/myConf.json"]
}

Windows-specific options​

There are additional configuration options that define metadata and appearance of executables for Windows platform. These fields must be placed in the root of neutralino.config.json. Every field is optional.

applicationName: string​

The human-readable application name. Fills in the ProductName field of the executable.

applicationIcon: string​

The location of the executable's icon relative to neutralino.config.json. The icon must be in PNG format. If it is not set, an icon from modes.window.icon will be chosen instead. If modes.window.icon does not point to a PNG file, too, a default Neutralino.js icon will be used.

author: string​

The developer of the application. Fills in the CompanyName field of the executable.

description: string​

A description of the executable file. This usually describes the purpose of your application. Fills in the FileDescription field of the executable.

Copyright information. Fills in the LegalCopyright field of the executable.

Example configuration:

{
    "applicationId": "cook.pancake.bakery",
    "version": "1.2.0",
    "applicationName": "Pancake Bakery",
    "author": "Sweet Pancakes LLC",
    "description": "Digital recipe book for pancakes from all over the world",
    "copyright": "Copyright © Sweet Pancakes LLC 2042. All rights reserved.",
    "applicationIcon": "buildAssets/appIcon.png",
    "cli": {
        "binaryName": "pancakebakery"
    }
}