MagicMirror²

https://docs.magicmirror.builders
Admin
MagicMirror² is an open-source modular smart mirror platform that allows users to convert a regular...
Tokens:25,100
Snippets:382
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### start()

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Lifecycle method called when all modules are loaded and the system is ready to boot.

```APIDOC
## start()

### Description
Called when the system is ready to boot. This is the appropriate place to define additional module properties or perform asynchronous initialization. The system waits for this method to settle if it returns a Promise.

### Example
```javascript
async start() {
	await customElements.whenDefined("my-custom-element");
	Log.log(this.name + ' is started!');
}
```
```

--------------------------------

### Start the application

Source: https://docs.magicmirror.builders/getting-started/installation.html

Launches the MagicMirror² application.

```shell
node --run start
```

--------------------------------

### Start application with X11 support

Source: https://docs.magicmirror.builders/getting-started/installation.html

Use this command instead of the standard start command if the system is using X11 instead of Wayland.

```shell
node --run start:x11
```

--------------------------------

### Define start method

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Use this method to initialize custom module properties when the system is ready.

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

--------------------------------

### Install application dependencies

Source: https://docs.magicmirror.builders/getting-started/installation.html

Installs the required dependencies for the application. Note that this process may take a significant amount of time.

```shell
node --run install-mm
```

--------------------------------

### Start application in client-only mode

Source: https://docs.magicmirror.builders/getting-started/installation.html

Connects to a remote MagicMirror² server instance.

```shell
node clientonly --address 192.168.1.5 --port 8080
```

--------------------------------

### Install electron-rebuild

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Install the electron-rebuild package as a development dependency.

```shell
npm install --save-dev @electron/rebuild
```

--------------------------------

### Create MagicMirror² Start Script

Source: https://docs.magicmirror.builders/configuration/autostart.html

Create and configure a shell script to launch the MagicMirror² application.

```shell
cd ~
nano mm.sh
```

```shell
cd ./MagicMirror
DISPLAY=:0 node --run start
```

```shell
chmod +x mm.sh
```

--------------------------------

### Start MagicMirror with Default Configuration

Source: https://docs.magicmirror.builders/configuration/introduction.html

Standard command to launch the application using the default configuration file.

```bash
cd ~/MagicMirror
node --run start
```

--------------------------------

### Start application in development mode

Source: https://docs.magicmirror.builders/getting-started/installation.html

Starts the application with Dev Tools enabled for debugging purposes.

```shell
node --run start:dev
```

--------------------------------

### Start application on Windows

Source: https://docs.magicmirror.builders/getting-started/installation.html

Specific startup command required for running the application on Windows environments.

```shell
node --run start:windows
```

--------------------------------

### Start periodic fetching

Source: https://docs.magicmirror.builders/module-development/weather-provider.html

Initiates the periodic fetcher when the provider starts.

```javascript
start() {
  this.fetcher?.startPeriodicFetch();
}
```

--------------------------------

### Configure Electron switches

Source: https://docs.magicmirror.builders/configuration/introduction.html

Example of passing specific command-line switches to the underlying Electron process.

```javascript
electronSwitches:["no-sandbox", { "js-flags": "--max-old-space-size=8192" }, { "password-store": "basic" }];
```

--------------------------------

### Install PM2

Source: https://docs.magicmirror.builders/configuration/autostart.html

Install the PM2 process manager globally via NPM.

```shell
sudo npm install -g pm2
```

--------------------------------

### Start MagicMirror with Alternate Configuration

Source: https://docs.magicmirror.builders/configuration/introduction.html

Use the MM_CONFIG_FILE environment variable to specify a custom configuration file path.

```bash
cd ~/MagicMirror
export MM_CONFIG_FILE=config/config2.js
node --run start
```

--------------------------------

### Start Server in Watch Mode

Source: https://docs.magicmirror.builders/core-development/debugging.html

Command to initiate the server with automatic file monitoring and reloading.

```sh
node --run server:watch
```

--------------------------------

### Implement Module Start Lifecycle

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Defines initialization logic for the module. Use the async variant for operations requiring promises, such as waiting for custom elements.

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

```javascript
async start() {
	await customElements.whenDefined("my-custom-element");
	Log.log(this.name + ' is started!');
}
```

--------------------------------

### Start MagicMirror on Custom Port

Source: https://docs.magicmirror.builders/configuration/introduction.html

Override the default port setting using the MM_PORT environment variable.

```bash
cd ~/MagicMirror
export MM_PORT=8081
node --run start
```

--------------------------------

### Manage MagicMirror² with PM2

Source: https://docs.magicmirror.builders/configuration/autostart.html

Commands to start, save, and control the MagicMirror² process via PM2.

```shell
pm2 start mm.sh
```

```shell
pm2 save
```

```shell
pm2 restart mm
```

```shell
pm2 stop mm
```

```shell
pm2 logs mm
```

```shell
pm2 show mm
```

--------------------------------

### Configure Electron window options

Source: https://docs.magicmirror.builders/configuration/introduction.html

Example of setting custom window dimensions and disabling fullscreen mode via electronOptions.

```javascript
electronOptions: { fullscreen: false, width: 800, height: 600 }
```

--------------------------------

### Define Module Configuration

Source: https://docs.magicmirror.builders/modules/configuration.html

Example structure for defining multiple modules within the MagicMirror configuration object.

```javascript
let config = {
  modules: [
    {
      module: "clock",
      position: "top_left",
    },
    {
      module: "compliments",
      position: "lower_third",
    },
    {
      module: "weather",
      position: "top_right",
      classes: "myclass1 myclass2",
      config: {
        weatherProvider: "openweathermap",
        type: "current",
        location: "New York",
        locationID: "5128581", //ID from http://bulk.openweathermap.org/sample/city.list.json.gz; unzip the gz file and find your city
        apiKey: "YOUR_OPENWEATHER_API_KEY",
      },
    },
  ],
};
```

--------------------------------

### Configure Animated Module

Source: https://docs.magicmirror.builders/modules/configuration.html

Example of applying animateIn and animateOut properties to a newsfeed module.

```javascript
{
  module: "newsfeed",
  position: "bottom_bar",
  animateIn: "slideInLeft",
  animateOut: "slideOutRight",
  config: {
    feeds: [
      {
        title: "New York Times",
        url: "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml"
      }
    ],
    showSourceTitle: true,
    showPublishDate: true,
    broadcastNewsFeeds: true,
    broadcastNewsUpdates: true
  }
},
```

--------------------------------

### Define a module with defaults and DOM generation

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

A functional example showing how to set default configuration and override the getDom method to render content.

```javascript
//helloworld.js:

Module.register("helloworld", {
  // Default module config.
  defaults: {
    text: "Hello World!",
  },

  // Override dom generator.
  getDom: function () {
    const wrapper = document.createElement("div");
    wrapper.innerHTML = this.config.text;
    return wrapper;
  },
});
```

--------------------------------

### Configure postinstall script

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Add the electron-rebuild command to the postinstall script in package.json to ensure modules are rebuilt after installation.

```js
...
"scripts": {
	...
	"postinstall": "./node_modules/.bin/electron-rebuild"
}
...
```

--------------------------------

### Translate Module Strings

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Basic usage of the translate wrapper and example JSON structure.

```javascript
this.translate("INFO"); //Will return a translated string for the identifier INFO
```

```json
{
  "INFO": "Really important information!"
}
```

--------------------------------

### Perform manual upgrade via terminal

Source: https://docs.magicmirror.builders/getting-started/upgrade-guide.html

Updates the MagicMirror² repository and runs the installation script to apply changes.

```shell
git pull && node --run install-mm
```

--------------------------------

### this.expressApp.get

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Defines a custom GET route on the MagicMirror Express application instance.

```APIDOC
## GET /:path

### Description
Defines a custom route on the MagicMirror Express instance to handle HTTP GET requests.

### Method
GET

### Endpoint
/:path

### Request Example
```javascript
this.expressApp.get("/foobar", function (req, res) {
	res.send("GET request to /foobar");
});
```
```

--------------------------------

### Configure remote access

Source: https://docs.magicmirror.builders/getting-started/installation.html

Example configuration for enabling remote connections by setting the address and IP whitelist.

```javascript
let config = {
	address: "0.0.0.0",	// default is "localhost"
	port: 8080,		// default
	ipWhitelist: ["127.0.0.1", "::ffff:127.0.0.1", "::1", "::ffff:172.17.0.1"], // default -- need to add your IP here
	...
};
```

--------------------------------

### Install Noto Color Emoji font

Source: https://docs.magicmirror.builders/configuration/raspberry.html

Installs the Noto Color Emoji package to enable colored emoji support on Raspberry Pi OS.

```shell
sudo apt install fonts-noto-color-emoji
```

--------------------------------

### Configure file watch targets

Source: https://docs.magicmirror.builders/configuration/introduction.html

Example of defining specific files to monitor for changes to trigger automatic server restarts.

```javascript
watchTargets: ["config/config.js", "config/custom.css", "modules/MMM-MyModule/MMM-MyModule.js"]
```

--------------------------------

### Configure Electron Window Position

Source: https://docs.magicmirror.builders/configuration/introduction.html

Use electronOptions to specify window coordinates, useful for multi-monitor setups.

```javascript
let config = {
	electronOptions: { x: 1920 },
	...
```

--------------------------------

### Start application in server-only mode

Source: https://docs.magicmirror.builders/getting-started/installation.html

Runs the application without a graphical window, typically for remote access.

```shell
node --run server
```

--------------------------------

### Configure Weather Provider in config.js

Source: https://docs.magicmirror.builders/module-development/weather-provider.html

Example configuration snippet to register the custom provider in the MagicMirror config file.

```javascript
{
  module: "weather",
  config: {
    weatherProvider: "yourprovider",
    type: "current" // or "forecast" / "hourly"
  }
}
```

--------------------------------

### Define Variables via Shell Export

Source: https://docs.magicmirror.builders/configuration/introduction.html

Set environment variables directly in the shell before starting the application.

```bash
cd ~/MagicMirror
export MY_ADDRESS=localhost
export MY_PORT=8080
export MY_HTTPS=false
node --run start
```

--------------------------------

### Identify Missing Module Errors

Source: https://docs.magicmirror.builders/core-development/debugging.html

Example of an error message indicating missing dependencies after a branch pull.

```text
App threw an error during load
Error: Cannot find module 'ansis'
Require stack:
```

--------------------------------

### MM.getModules()

Source: https://docs.magicmirror.builders/module-development/helper-methods.html

Retrieves an array of all currently loaded module instances. Note that this returns an empty array if modules have not finished starting; wait for the ALL_MODULES_STARTED notification.

```APIDOC
## MM.getModules()

### Description
Returns an array of all currently loaded module instances. The returned array provides chaining methods for filtering.

### Parameters
- None

### Returns
- **Array** - An array of module instances.
```

--------------------------------

### Initialize configuration file

Source: https://docs.magicmirror.builders/getting-started/installation.html

Creates the main configuration file by copying the provided sample.

```shell
cp config/config.js.sample config/config.js
```

--------------------------------

### Initialize custom CSS file

Source: https://docs.magicmirror.builders/configuration/customcss.html

Copy the sample configuration file to create your custom CSS file.

```sh
cp config/custom.css.sample config/custom.css
```

--------------------------------

### Create Chromium launcher script

Source: https://docs.magicmirror.builders/configuration/autostart.html

Commands to initialize the bin directory and create the Chromium startup script.

```shell
mkdir -p ~/bin
nano ~/bin/start-chromium.sh
```

--------------------------------

### Create systemd Service File

Source: https://docs.magicmirror.builders/configuration/autostart.html

Set up a user-level systemd service for MagicMirror².

```shell
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/magicmirror.service
```

```ini
[Unit]
Description=MagicMirror
After=graphical-session.target

[Service]
Type=simple
Restart=always
RestartSec=15
WorkingDirectory=%h/MagicMirror
ExecStart=/usr/bin/node --run start
```

--------------------------------

### Configure PM2 Startup

Source: https://docs.magicmirror.builders/configuration/autostart.html

Generate the command required to enable PM2 on system boot.

```shell
pm2 startup
```

--------------------------------

### Configure LXDE autostart

Source: https://docs.magicmirror.builders/configuration/autostart.html

Commands to create and edit the LXDE autostart configuration file.

```shell
mkdir -p ~/.config/lxsession/LXDE-pi
nano ~/.config/lxsession/LXDE-pi/autostart
```

--------------------------------

### Define module configuration

Source: https://docs.magicmirror.builders/modules/calendar.html

Sets up the calendar module with authentication and styling preferences.

```javascript
    config: {
      coloredText: false,
      coloredBorder: false,
      coloredSymbol: false,
      coloredBackground: false,
      calendars: [
        {
          url: 'https://www.calendarlabs.com/templates/ical/US-Holidays.ics',
          symbol: 'calendar',
          auth: {
              user: 'username',
              pass: 'SuperStrongPassword',
              method: 'basic'
          }
        },
      ],
    }
```

--------------------------------

### Run Configuration Checker

Source: https://docs.magicmirror.builders/modules/configuration.html

Execute the configuration checker to validate new position values during startup.

```bash
node --run config:check
```

--------------------------------

### Navigate to the repository directory

Source: https://docs.magicmirror.builders/getting-started/installation.html

Changes the current working directory to the cloned MagicMirror folder.

```shell
cd MagicMirror
```

--------------------------------

### Configure the helloworld module

Source: https://docs.magicmirror.builders/modules/helloworld.html

Add this configuration object to the modules array in config/config.js to enable the module.

```javascript
    {
      module: "helloworld",
      position: "bottom_bar", // This can be any of the regions.
      config: {
        // See 'Configuration options' for more information.
        text: "Hello world!",
      },
    },
```

--------------------------------

### this.show(speed, callback, options)

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Shows a module instance with optional animation speed, completion callback, and configuration options.

```APIDOC
## this.show(speed, callback, options)

### Description
Shows a module instance. This can be called on the current module or another module instance.

### Parameters
- **speed** (Number) - Optional - The speed of the show animation in milliseconds.
- **callback** (Function) - Optional - The callback function executed after the animation finishes.
- **options** (Object) - Optional - Configuration object containing `lockString` (String), `force` (Boolean), `onError` (Function), or `animate` (String).
```

--------------------------------

### Define MagicMirror Configuration Files

Source: https://docs.magicmirror.builders/configuration/introduction.html

Standard structure for MagicMirror configuration files. Ensure each instance uses a unique port to avoid conflicts.

```javascript
let config = {
	address: "0.0.0.0", // Can be whatever you set as your original.
	port: 8080, // Must be different than the other configuration file.
	ipWhitelist: [], // Can be whatever you set as your original.
	language: "en",
	timeFormat: 12,
	units: "imperial",
	//logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"],
	modules: [
	(insert module configurations here)
	] // end of modules
}; // end of config variable.
/*************** DO NOT EDIT BELOW ***************/
if (typeof module !== "undefined") {
	module.exports = config;
}
```

```javascript
let config = {
	electronOptions: { x: 1920 },
	address: "0.0.0.0", // can be whatever you set as your original.
	port: 8081, // Must be different than the other configuration file.
	ipWhitelist: [], // can be whatever you set as your original.
	language: "en",
	timeFormat: 12,
	units: "imperial",
	//logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"],
	modules: [
	(insert module configurations here)
	] // end of modules
}; // end of config variable.
/*************** DO NOT EDIT BELOW ***************/
if (typeof module !== "undefined") {
	module.exports = config;
}
```

--------------------------------

### Override weather icon color

Source: https://docs.magicmirror.builders/configuration/customcss.html

Example of targeting a specific weather icon class to change its color in the custom CSS file.

```css
.wi-day-sunny {
  color: #ffff00;
}
```

--------------------------------

### LXDE autostart file content

Source: https://docs.magicmirror.builders/configuration/autostart.html

Required lines to add to the LXDE autostart file for kiosk mode.

```shell
@lxpanel --profile LXDE-pi
@pcmanfm --desktop --profile LXDE-pi
@xscreensaver -no-splash
@point-rpi
@sh /home/server/bin/start-chromium.sh
```

--------------------------------

### Validate Configuration File

Source: https://docs.magicmirror.builders/configuration/introduction.html

Check a specific configuration file for syntax errors before launching.

```bash
export MM_CONFIG_FILE=config/config2.js
node --run config:check
```

```log
[26.12.2023 18:13.12.972] [INFO]  Checking file...  /home/<user>/MagicMirror/config/config2.js
[26.12.2023 18:13.13.062] [INFO]  Your configuration file doesn't contain syntax errors :)
```

--------------------------------

### Set display environment variables

Source: https://docs.magicmirror.builders/configuration/autostart.html

Environment configuration to add to the systemd service file to resolve blank screen issues.

```shell
Environment=DISPLAY=:0
Environment=XAUTHORITY=%h/.Xauthority
```

--------------------------------

### Create an empty NodeHelper stub

Source: https://docs.magicmirror.builders/module-development/introduction.html

Use this minimal implementation when a module requires a public folder but does not need additional server-side logic.

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

--------------------------------

### Manage MagicMirror User Service

Source: https://docs.magicmirror.builders/configuration/autostart.html

Commands to control the MagicMirror service as a regular user. Run these without sudo.

```shell
# Reload systemd user config
systemctl --user daemon-reload

# Start MagicMirror now
systemctl --user start magicmirror

# Enable auto-start on boot (after user login)
systemctl --user enable magicmirror

# Restart MagicMirror
systemctl --user restart magicmirror.service

# Stop MagicMirror
systemctl --user stop magicmirror.service

# Disable auto-start
systemctl --user disable magicmirror.service
```

--------------------------------

### Headless Service Configuration

Source: https://docs.magicmirror.builders/configuration/autostart.html

Systemd service configuration for running MagicMirror in server-only mode without a GUI.

```ini
[Unit]
Description=MagicMirror
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=server
WorkingDirectory=/home/server/MagicMirror/
ExecStart=/usr/bin/node serveronly

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Set script permissions

Source: https://docs.magicmirror.builders/configuration/autostart.html

Command to make the Chromium launcher script executable.

```shell
chmod +x ~/bin/start-chromium.sh
```

--------------------------------

### Clone the MagicMirror repository

Source: https://docs.magicmirror.builders/getting-started/installation.html

Downloads the source code from the official GitHub repository.

```shell
git clone https://github.com/MagicMirrorOrg/MagicMirror.git
```

--------------------------------

### Implement getHeader()

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Returns a string to be displayed as the module header. Access the user's configured header via this.data.header.

```javascript
getHeader: function() {
	return this.data.header + ' Foo Bar';
}
```

--------------------------------

### Load External Stylesheets

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Returns an array of stylesheet paths to be loaded. Avoid external URLs to prevent boot stalls.

```javascript
getStyles: function() {
	return [
		'script.css', // will try to load it from the files defined in `js/vendor.js`, otherwise it will load it from the module folder.
		'font-awesome.css', // this file is defined in `js/vendor.js`, so it doesn't need to be available in the module folder.
		this.file('another_file.css'), // this file will be loaded straight from the module folder.
		'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css',  // this file will be loaded from the bootstrap cdn servers.
	]
}
```

--------------------------------

### Register a basic module

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

The minimal requirement for a MagicMirror² module definition.

```javascript
Module.register("modulename", {});
```

--------------------------------

### Implement getDom for manual DOM creation

Source: https://docs.magicmirror.builders/module-development/rendering.html

Returns an HTML Element to be displayed by the MagicMirror interface.

```javascript
getDom: function() {
	const wrapper = document.createElement("div");
	wrapper.innerHTML = 'Hello world!';
	return wrapper;
}
```

--------------------------------

### Configure environment variables in config.env

Source: https://docs.magicmirror.builders/configuration/introduction.html

Defines location, API keys, and calendar URLs for the application environment.

```bash
LAT=0.0
LON=0.0
MAPBOX_URL="http://example.url/1458562"
STRAVA_API_KEY="FakeKey1234"
OPENWEATHER_API_KEY="FakeKey4321"
CAL_URL1="https://calendar.google.com/calendar/ical/example@example.example/private-fakeaddress12445812581119058955b/basic.ics"
CAL_URL2="https://calendar.google.com/calendar/ical/example@example.example/private-fakeaddress2445812581119058955b/basic.ics"
CAL_URL3="https://calendar.google.com/calendar/ical/example@example.example/private-fakeaddress32445812581119058955b/basic.ics"
```

--------------------------------

### Default compliment configuration

Source: https://docs.magicmirror.builders/modules/compliments.html

Standard configuration structure using time-of-day keys and specific date keys.

```javascript
    config: {
      compliments: {
        anytime: [
          "Hey there sexy!"
        ],
        morning: [
          "Good morning, handsome!",
          "Enjoy your day!",
          "How was your sleep?"
        ],
        afternoon: [
          "Hello, beauty!",
          "You look sexy!",
          "Looking good today!"
        ],
        evening: [
          "Wow, you look hot!",
          "You look nice!",
          "Hi, sexy!"
        ],
        "....-01-01": [
          "Happy new year!"
        ]
      }
    }
```

--------------------------------

### Create System-wide Service File

Source: https://docs.magicmirror.builders/configuration/autostart.html

Command to open the systemd service file for editing with root privileges.

```shell
sudo nano /etc/systemd/system/magicmirror.service
```

--------------------------------

### getTemplate()

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Provides the path to a Nunjucks template file for rendering the module component.

```APIDOC
## getTemplate()

### Description
Returns the file path to a Nunjucks template used to render the module. Used as an alternative to `getDom()`.

### Returns
- **String** - The path to the .njk template file.
```

--------------------------------

### Module.register(name, properties)

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Registers a new module with the MagicMirror² system. This is the entry point for defining module behavior and configuration.

```APIDOC
## Module.register(name, properties)

### Description
Registers a module definition with the system. The module must be defined in a file named after the module (e.g., modulename.js).

### Parameters
- **name** (String) - Required - The name of the module.
- **properties** (Object) - Required - An object containing module properties, methods, and default configurations.

### Example
```javascript
Module.register("helloworld", {
  defaults: {
    text: "Hello World!"
  },
  getDom: function () {
    const wrapper = document.createElement("div");
    wrapper.innerHTML = this.config.text;
    return wrapper;
  }
});
```
```

--------------------------------

### Configure Watch Targets

Source: https://docs.magicmirror.builders/core-development/debugging.html

Configuration snippet for defining files to monitor for changes in config.js.

```js
let config = {
  watchTargets: [
    "config/config.js",
    "config/custom.css",
    "modules/MMM-MyModule/MMM-MyModule.js",
    "modules/MMM-MyModule/node_helper.js",
  ],
  // ... rest of config
};
```

--------------------------------

### Manage Visibility Locking

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Demonstrates how modules use lock strings to manage visibility states when multiple modules request hide or show actions.

```javascript
moduleA.hide(0, { lockString: "module_b_identifier" });
```

```javascript
moduleA.lockStrings == ["module_b_identifier"];
moduleA.hidden == true;
```

```javascript
moduleA.hide(0, { lockString: "module_c_identifier" });
```

```javascript
moduleA.lockStrings == ["module_b_identifier", "module_c_identifier"];
moduleA.hidden == true;
```

```javascript
moduleA.show(0, { lockString: "module_b_identifier" });
```

--------------------------------

### Use Variables in Configuration Files

Source: https://docs.magicmirror.builders/configuration/introduction.html

Use placeholders like ${VARIABLE} to redact sensitive information from configuration files before sharing them publicly.

```javascript
let config = {
  address: "0.0.0.0",
  port: 8080,
  ipWhitelist: [],

  language: "de",
  logLevel: ["INFO", "LOG", "WARN", "ERROR"],
  timeFormat: 24,
  units: "metric",

  modules: [
    {
      module: "MMM-RAIN-MAP",
      position: "bottom_left",
      config: {
        animationSpeedMs: 400,
        colorizeTime: false,
        defaultZoomLevel: 8,
        displayTime: true,
        displayClockSymbol: true,
        displayOnlyOnRain: false,
        extraDelayLastFrameMs: 2000,
        markers: [
          { lat: ${LAT}, lng: ${LON}, color: "black" },
        ],
        mapPositions: [
          { lat: ${LAT}, lng: ${LON}, zoom: 9, loops: 1 },
          { lat: ${LAT}, lng: ${LON}, zoom: 8, loops: 1 },
          { lat: ${LAT}, lng: ${LON}, zoom: 7, loops: 1 },
          { lat: ${LAT}, lng: ${LON}, zoom: 6, loops: 1 },
        ],
        mapUrl: "${MAPBOX_URL}",
        mapHeight: "320px",
        mapWidth: "520px",
        updateIntervalInSeconds: 300,
      }
    },
    {
      module: "MMM-Strava",
      header: "Strava",
      position: "bottom_left",
      config: {
        client_id: "16228",
        client_secret: "${STRAVA_API_KEY}",
        activities: ["ride"],
        period: "recent",
        stats: ["count", "distance", "elevation", "achievements"],
        auto_rotate: true,
        updateInterval: 20000,
        reloadInterval: 3600000,
        showPrivateStats: true,
        limitPrivateStats: 1200,
        digits: 0
      }
    },
    {
      module: "MMM-OpenWeatherForecast",
      header: "Wetter",
      position: "top_center",
      config: {
        apikey: "${OPENWEATHER_API_KEY}",
        latitude: "${LAT}",
        longitude: "${LON}",
        showHourlyForecast: false,
        colored: false,
        iconset: "3c",
        label_days: ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
        concise: false,
        forecastHeaderText: "",
        label_sunriseTimeFormat: "k:mm",
        label_high: "",
        label_low: "",
        displayKmhForWind: true
      }
    },
    {
      module: "calendar",
      header: "Termine",
      position: "top_right",
      config: {
        timeFormat: "absolute",
        showEnd: false,
        dateFormat: "DD.MM.",
        maximumEntries: 10,
        maximumNumberOfDays: 70,
        colored: true,
        calendars: [
          {
            symbol: "subway",
            url: "${CAL_URL1}"
          },
          {
            symbol: "cake-candles",
            url: "${CAL_URL2}"
          },
          {
            symbol: "angle-right",
            color: "#999999",
            url: "${CAL_URL3}"
          }
        ]
      }
    },
  ]
};

/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {module.exports = config;}
```

--------------------------------

### Implement Weather Provider Class

Source: https://docs.magicmirror.builders/module-development/weather-provider.html

The base structure for a custom weather provider, including initialization, lifecycle methods, and data parsing.

```javascript
const HTTPFetcher = require("#http_fetcher");

class YourProvider {
  constructor(config) {
    this.config = config;
    this.locationName = null;
    this.fetcher = null;
    this.onDataCallback = null;
    this.onErrorCallback = null;
  }

  setCallbacks(onData, onError) {
    this.onDataCallback = onData;
    this.onErrorCallback = onError;
  }

  initialize() {
    this.fetcher = new HTTPFetcher("https://your.api/endpoint", {
      reloadInterval: this.config.updateInterval,
      logContext: "weatherprovider.yourprovider",
    });

    this.fetcher.on("response", async (response) => {
      const data = await response.json();
      this.onDataCallback(this.parseWeather(data));
    });

    this.fetcher.on("error", (errorInfo) => this.onErrorCallback(errorInfo));
  }

  start() {
    this.fetcher?.startPeriodicFetch();
  }

  stop() {
    this.fetcher?.clearTimer();
  }

  parseWeather(data) {
    return { temperature: data.temp };
  }
}

module.exports = YourProvider;
```

--------------------------------

### Check service logs

Source: https://docs.magicmirror.builders/configuration/autostart.html

Commands to view systemd service logs for troubleshooting.

```shell
journalctl --user -u magicmirror -f          # for user service
sudo journalctl -u magicmirror -f            # for system service
```

--------------------------------

### Load External Scripts

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Returns an array of script paths to be loaded by the module. Avoid external URLs to prevent boot stalls.

```javascript
getScripts: function() {
	return [
		'script.js', // will try to load it from the files defined in `js/vendor.js`, otherwise it will load it from the module folder.
		'moment.js', // this file is defined in `js/vendor.js`, so it doesn't need to be available in the module folder.
		this.file('another_file.js'), // this file will be loaded straight from the module folder.
		'https://code.jquery.com/jquery-2.2.3.min.js',  // this file will be loaded from the jquery servers.
	]
}
```

--------------------------------

### .enumerate(callback)

Source: https://docs.magicmirror.builders/module-development/helper-methods.html

Executes a provided function on every module instance in the current selection.

```APIDOC
## .enumerate(callback)

### Description
Performs an action on all selected modules by executing the provided callback function for each instance.

### Parameters
- **callback** (Function) - Required - A function that receives the module instance as an argument.
```

--------------------------------

### Minimum MagicMirror² Configuration

Source: https://docs.magicmirror.builders/configuration/introduction.html

Defines the base structure for the config.js file, including the mandatory module export for the application.

```javascript
let config = {
  modules: [
    {
      module: "clock",
      position: "fullscreen_above",
      config: {},
    },
  ],
};

/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {module.exports = config;}
```

--------------------------------

### Use Environment Variables in config.js

Source: https://docs.magicmirror.builders/configuration/introduction.html

Template configuration values using ${VARIABLE} syntax, which are resolved at runtime.

```javascript
let config = {
	address: "${MY_ADDRESS}",
	port: ${MY_PORT},
	useHttps: ${MY_HTTPS},
};
/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {module.exports = config;}
```

```javascript
let config = {
  address: "localhost",
  port: 8080,
  useHttps: false,
};
/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {module.exports = config;}
```

--------------------------------

### Implement getTemplate() and Nunjucks Template

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Provides a path to a Nunjucks template for rendering. Use in conjunction with getTemplateData to pass dynamic content.

```javascript
getTemplate: function() {
  return 'MMM-Example.njk';
}
```

```nunjucks
<div>
  <header>
    {{ "INFO" | translate }}
  </header>

  <p class="hello">
    {{ prompt }}
  </p>
</div>
```

--------------------------------

### getStyles()

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Method to request additional CSS files to be loaded by the module.

```APIDOC
## getStyles()

### Description
Returns an array of strings representing stylesheet files to load. Use `this.file('filename.css')` for files within the module folder.

### Returns
- **Array** - A list of stylesheet paths or URLs.
```

--------------------------------

### Enable CORS Proxy with Whitelist

Source: https://docs.magicmirror.builders/configuration/cors.html

Restricts proxy access to a specific list of allowed domains. This is the recommended, more secure configuration.

```javascript
  cors: "allowWhitelist",
  corsDomainWhitelist: ["example.com", "api.mapbox.com"],
```

--------------------------------

### Enable CORS Proxy for All Domains

Source: https://docs.magicmirror.builders/configuration/cors.html

Configures the proxy to allow requests to any URL. Only recommended for instances not exposed to the public internet.

```javascript
  cors: "allowAll",
```

--------------------------------

### getHeader()

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Retrieves the string to be displayed as the module's header.

```APIDOC
## getHeader()

### Description
Returns the header string for the module. If not implemented, the system defaults to the user's configured header.

### Returns
- **String** - The header text.
```

--------------------------------

### Define stop method

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Implement cleanup logic here to close connections or stop processes during server shutdown.

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

--------------------------------

### Define Minimum Version Requirement

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Specify the minimum MagicMirror framework version required for the module to run.

```javascript
requiresVersion: "2.1.0",
```

--------------------------------

### Default Public Folder Route

Source: https://docs.magicmirror.builders/module-development/node-helper.html

The default configuration for serving static files from the module's public folder.

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

--------------------------------

### Define Translation Files

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Returns a dictionary mapping language codes to their respective JSON translation files.

```javascript
getTranslations: function() {
	return {
			en: "translations/en.json",
			de: "translations/de.json"
	}
}
```

--------------------------------

### Importing Logger in node_helper.js

Source: https://docs.magicmirror.builders/module-development/logger.html

Include this line at the top of your node_helper.js file to enable logging functionality.

```javascript
const Log = require("logger");
```

--------------------------------

### Enable Debug Logging

Source: https://docs.magicmirror.builders/core-development/debugging.html

Configuration to increase log verbosity by adding DEBUG to the logLevel array.

```js
let config = {
  // ...
  logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging
  // ...
};
```

--------------------------------

### Configure cron-based compliments

Source: https://docs.magicmirror.builders/modules/compliments.html

Use cron syntax to schedule specific compliments for certain times and days.

```javascript
    config: {
      compliments: {
        "48-50 16-18 * * 5,6": [
          "Happy Hour!", "Its a Party"
        ]
      }
    }
```

```javascript
    config: {
        compliments: {
            "* 20-21 31 10 *": [
                "Boo!!"
            ]
        }
    }
```

--------------------------------

### Manage MagicMirror systemd service

Source: https://docs.magicmirror.builders/configuration/autostart.html

Standard systemd commands to control the MagicMirror service state.

```shell
sudo systemctl daemon-reload
sudo systemctl start magicmirror
sudo systemctl enable magicmirror
sudo systemctl restart magicmirror.service
sudo systemctl stop magicmirror.service
sudo systemctl disable magicmirror.service
```

--------------------------------

### Chromium launcher script content

Source: https://docs.magicmirror.builders/configuration/autostart.html

Shell script to launch Chromium in kiosk mode with specific flags.

```shell
#!/bin/sh

set -e

CHROMIUM_TEMP=~/tmp/chromium
rm -Rf ~/.config/chromium/
rm -Rf $CHROMIUM_TEMP
mkdir -p $CHROMIUM_TEMP

chromium-browser \
        --disable \
        --disable-translate \
        --disable-infobars \
        --disable-suggestions-service \
        --disable-save-password-bubble \
        --disk-cache-dir=$CHROMIUM_TEMP/cache/ \
        --user-data-dir=$CHROMIUM_TEMP/user_data/ \
        --start-maximized \
        --kiosk http://localhost:8080 &
```

--------------------------------

### Configure Alert Module

Source: https://docs.magicmirror.builders/modules/alert.html

Add this object to the modules array in config/config.js to enable the alert module.

```javascript
    {
      module: "alert",
      config: {
        // The config property is optional.
        // See 'Configuration options' for more information.
      }
    },
```

--------------------------------

### Animate and update a module element

Source: https://docs.magicmirror.builders/modules/animate.html

Demonstrates updating element content and applying an animation with a timeout to remove it.

```javascript
...
// select element ("myDivSample")
let test = document.getElementById("myDivSample")
// apply pretty update of this element
test.textContent = "Hello AnimateCSS!"
// add an "flipInX" animation type to "myDivSample" with 1 sec duration
addAnimateCSS("myDivSample", "flipInX", 1)
setTimeout(() => {
  // remove animation after 1sec
  removeAnimateCSS("myDivSample", "flipInX")
}, 1000)
...
```

--------------------------------

### Configure Weather Module

Source: https://docs.magicmirror.builders/modules/weather.html

Add this object to the modules array in config/config.js to enable the weather module.

```javascript
    {
      module: "weather",
      position: "top_right",
      config: {
        // See 'Configuration options' for more information.
        type: "current",
      },
    },
```

--------------------------------

### Logging messages with Log

Source: https://docs.magicmirror.builders/module-development/logger.html

Use these methods to output info, log, or error messages to the console.

```javascript
Log.info("info");
Log.log("log");
Log.error("error");
```

--------------------------------

### Enumerate over selected modules

Source: https://docs.magicmirror.builders/module-development/helper-methods.html

Execute a callback function for every module instance in the filtered selection.

```javascript
MM.getModules().enumerate(function (module) {
  Log.log(module.name);
});
```

--------------------------------

### Configure the Calendar Module

Source: https://docs.magicmirror.builders/modules/calendar.html

Add this object to the modules array in config/config.js to enable the calendar module.

```javascript
    {
      module: "calendar",
      position: "top_left", // This can be any of the regions. Best results in left or right regions.
      config: {
        // The config property is optional.
        // If no config is set, an example calendar is shown.
        // See 'Configuration options' for more information.
      },
    },
```

--------------------------------

### nunjucksEnvironment()

Source: https://docs.magicmirror.builders/module-development/rendering.html

Access the Nunjucks environment to register custom filters.

```APIDOC
## nunjucksEnvironment()

### Description
Returns the Nunjucks environment instance, allowing for the addition of custom filters via the addFilter method.

### Example
```javascript
this.nunjucksEnvironment().addFilter("space", function (str) {
  return str.split("").join(" ");
});
```
```

--------------------------------

### Configure weather-based compliments

Source: https://docs.magicmirror.builders/modules/compliments.html

Map weather condition keys to arrays of messages to display based on current weather status.

```javascript
    config: {
      compliments: {
        day_sunny: [
          "Today is a sunny day",
          "It's a beautiful day"
        ],
        snow: [
          "Snowball battle!"
        ],
        rain: [
          "Don't forget your umbrella"
        ]
      }
    }
```

--------------------------------

### Node Helper Lifecycle Methods

Source: https://docs.magicmirror.builders/module-development/node-helper.html

Methods that can be subclassed to handle the lifecycle of a node helper module.

```APIDOC
## init()
This method is called when a node helper gets instantiated.

## loaded()
This method is called after the node helper is loaded and its name and path properties have been set, but before start() is called.

## start()
This method is called when all node helpers are loaded and the system is ready to boot up.

## stop()
This method is called when the MagicMirror server receives a SIGINT command and is shutting down.
```

--------------------------------

### Nunjucks Template Methods

Source: https://docs.magicmirror.builders/module-development/rendering.html

Methods for defining and providing data to Nunjucks templates.

```APIDOC
## getTemplate()

### Description
Returns the file path to the Nunjucks template (.njk) file used for rendering.

## getTemplateData()

### Description
Returns an object containing the data to be injected into the Nunjucks template.

### Example
```javascript
getTemplate: function() {
  return "MMM-MyModule.njk";
},

getTemplateData: function() {
  return {
    list: ["item 1", "item 2", "item 3"],
  };
}
```
```

--------------------------------

### this.updateDom(speed|options)

Source: https://docs.magicmirror.builders/module-development/core-module-file.html

Requests the MagicMirror core to update the module's DOM element.

```APIDOC
### this.updateDom(speed|options)

#### Description
Triggers a DOM update for the module. If a speed or options object is provided, the update can be animated.

#### Parameters
- **speed** (Number) - Optional. Animation speed in milliseconds.
- **options** (Object) - Optional. Configuration for animation speed and type (in/out rules).
```

--------------------------------

### Configure Nunjucks templates and data

Source: https://docs.magicmirror.builders/module-development/rendering.html

Defines the template file path and the data object passed to the template for rendering.

```javascript
getTemplate: function() {
  return "MMM-MyModule.njk";
},

getTemplateData: function() {
  return {
    list: ["item 1", "item 2", "item 3"],
  };
}
```

```nunjucks
<ul>
  {% for item in list %}
  <li>{{ item }}</li>
  {% endfor %}
</ul>
```

```html
<ul>
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
</ul>
```

--------------------------------

### Combine module filtering methods

Source: https://docs.magicmirror.builders/module-development/helper-methods.html

Chain multiple filtering methods to refine the selection of module instances.

```javascript
let modules = MM.getModules()
  .withClass("classname1")
  .exceptWithClass("classname2")
  .exceptModule(aModule);
```
Tokens:
Raw