Skip to main content

Framework Developer Guide

Great open-source software is a result of the collaboration of enthusiastic developers. Anyone can help Neutralino by contributing code and reporting bugs. This document explains how to start contributing Neutralinojs.

Note that this guide is for contributors. If you are getting started with Neutralinojs app development, you can start from here.

Setup and build the framework#

First, clone the main repository.

git clone
cd neutralinojs


No need for separate compilers because Linux distributions usually have GNU C/C++ compilers installed already.

Install GTK, webkit, boost and other required libraries


If you are using a newer version of Ubuntu, some libraries may be pre-installed.

sudo apt-get install \
libboost-all-dev \
libgtk-3-dev \
libwebkit2gtk-4.0-37 \
libwebkit2gtk-4.0-dev \


sudo dnf install \
@development-tools \
libappindicator-gtk3.x86_64 \
gtk3 \
webkit2gtk3.x86_64 \
webkit2gtk3-devel.x86_64 \

Compile the Neutralinojs framework.

bash # [ia32, x64, armhf, arm64]


Install the latest Visual Studio IDE. Neutralinojs compilation on Windows will use MSVC (aka cl.exe) C++ compiler. Install Boost libraries via Chocolatey.

choco install boost-msvc-14.1

Compile the Neutralinojs framework.

./build_windows.bat # [ia32, x64, armhf, arm64]


Install Xcode Command Line Tools. Install Boost libraries via Homebrew.

brew install boost@1.76

Compile the Neutralinojs framework.

bash # [ia32, x64, armhf, arm64]

Setup and build the client#

Neutralinojs apps communicate with the Neutralinojs process via a WebSocket connection. This WebSocket connection gets initiated by the Neutralinojs client.

Clone the client repository to the same directory where you downloaded the main repository.

git clone
cd neutralino.js

Install developer dependencies.

npm install

Executing the test app#

The main repository has a simple test application that you can use during development related activities. You can enter the following command from the main repository to build and update the test app's client.

bash ./scripts/

Now run the newly compiled test app with the following command.

./bin/neutralino-linux_x64 --load-dir-res


Testing is a crucial part in every development activity. Every pull request in the main codebase will trigger the following automated tests.

  • Builds on Linux, macOS, and Windows with x64 machines.
  • Integration test suite.

However, you can run our integration test suite from your local computer too with the following command from the main codebase's directory.

cd spec
npm install
npm run test

It's always good to run the test suite for the module you've updated with the following command.

npm run test <module> # Eg: npm run test filesystem

If you need to run tests for the extensions module, make sure to enter npm install from ./bin/extensions/sampleextension first.

The above command will run test only for the given module.

Project directory structure#



  • api: The native API implementation and controllers. Written in REST API style.
  • auth: Authentication and permissions-related logic.
  • bin: Test app source code.
  • lib: Third-party libraries' source files.
  • server: WebSocket/HTTP communication endpoints.
  • spec: Integration/API test suite.

Client library#


  • src/api: JavaScript API frontend and implementaion.
  • src/browser: Browser-related API implementation.
  • src/debug: Developer mode features.
  • src/ws: WebSocket client implementaion.

Contribution guidelines#

Before, contributing to the codebase, please check the following things.

  • Discuss the feature/improvement/bug-fix with the Neutralinojs team via GitHub discussions.
  • Get familiar with the code style. There is no specific code style guide yet, but, the codebase inherits some guidelines from the Google C++ code style guide.
  • Become familiar with all modules in the codebase.
  • Avoid adding new features to only one platform.

Thanks for helping us to make Neutralinojs better!