MagicMirror² DocsMagicMirror² Docs
Donate
Discord
Forum
GitHub
Donate
Discord
Forum
GitHub
  • Getting Started

    • Introduction
    • Requirements
    • Installation & Usage
    • Upgrade Guide
  • Configuration

    • Introduction
    • Autostart your MagicMirror²
    • Raspberry Specific
  • Modules

    • Introduction
    • Module Configuration
    • Default Modules

      • Alert
      • Calendar
      • Clock
      • Compliments
      • Hello World
      • News Feed
      • Update Notification
      • Weather Module
    • Animation Guide
  • Module Development

    • Introduction
    • The Core module file
    • The Node Helper
    • MagicMirror Helper Methods
    • Logger
    • Notifications
    • Weather Module Weather Provider Development
    • How to write good documentation
  • About

    • MagicMirror² Manifesto
    • Contributing Guidelines
    • Donate
    • Support
    • License

The Node Helper

The node helper (node_helper.js) is a Node.js script that is able to do some backend task to support your module. For every module type, only one node helper instance will be created. For example: if your MagicMirror uses two calendar modules, there will be only one calendar node helper instantiated.

Note: Because there is only one node helper per module type, there is no default config available within your module. It's your task to send the desired config from your module to your node helper.

In its most simple form, the node_helper.js file must contain:

const NodeHelper = require("node_helper");
module.exports = NodeHelper.create({});

Of course, the above helper would not do anything useful. So with the information above, you should be able to make it a bit more sophisticated.

Available module instance properties

this.name

String

The name of the module

this.path

String

The path of the module

this.expressApp

Express App Instance

This is a link to the express instance. It will allow you to define extra routes.

Example:

start: function() {
	this.expressApp.get("/foobar", function (req, res) {
		res.send("GET request to /foobar");
	});
}

Note: By default, a public path to your module's public folder will be created:

this.expressApp.use("/" + this.name, express.static(this.path + "/public"));

this.io

Socket IO Instance

This is a link to the IO instance. It will allow you to do some Socket.IO magic. In most cases you won't need this, since the Node Helper has a few convenience methods to make this simple.

requiresVersion:

Introduced in version: 2.1.0.

A string that defines the minimum version of the MagicMirror framework. If it is set, the system compares the required version with the users version. If the version of the user is out of date, it won't run the module.

Note: Since this check is introduced in version 2.1.0, this check will not be run in older versions. Keep this in mind if you get issue reports on your module.

Example:

requiresVersion: "2.1.0",

Subclassable module methods

init()

This method is called when a node helper gets instantiated. In most cases you do not need to subclass this method.

start()

This method is called when all node helpers are loaded and the system is ready to boot up. The start method is a perfect place to define any additional module properties:

Example:

start: function() {
	this.mySpecialProperty = "So much wow!";
	Log.log(this.name + " is started!");
}

stop()

This method is called when the MagicMirror server receives a SIGINT command and is shutting down. This method should include any commands needed to close any open connections, stop any sub-processes and gracefully exit the module.

Example:

stop: function() {
	Log.log("Shutting down MyModule");
	this.connection.close();
}

socketNotificationReceived: function(notification, payload)

With this method, your node helper can receive notifications from your modules. When this method is called, it has 2 arguments:

  • notification - String - The notification identifier.
  • payload - AnyType - The payload of a notification.

Note: The socket connection is established as soon as the module sends its first message using sendSocketNotification.

Example:

socketNotificationReceived: function(notification, payload) {
	Log.log(this.name + " received a socket notification: " + notification + " - Payload: " + payload);
},

Module instance methods

Each node helper has some handy methods which can be helpful building your module.

this.sendSocketNotification(notification, payload)

  • notification - String - The notification identifier.
  • payload - AnyType - (Optional) The payload of a notification.

If you want to send a notification to your module, use the sendSocketNotification(notification, payload). Only the module of your module type will receive the socket notification.

Note: Since all instances of your module will receive the notifications, it's your task to make sure the right module responds to your messages.

Example:

this.sendSocketNotification("SET_CONFIG", this.config);

Reminder

sendSocketNotification sends a notification from the helper to all the instances of your module.

Using native node modules in your node_helper

If you want use native node modules within electron you need to recompile them for electron. To do so you have to install electron-rebuild.

npm install --save-dev @electron/rebuild

and run it after every install (package.json example):

...
"scripts": {
	...
	"postinstall": "./node_modules/.bin/electron-rebuild"
}
...
Help us improve this page!
Last Updated:: 4/30/25, 8:00 PM
Prev
The Core module file
Next
MagicMirror Helper Methods