What Is Magic Mirror Configuration and How Does It Work?
Magic mirror configuration is the process of editing a single JavaScript file — config.js — to control everything your MagicMirror² smart mirror displays, from the clock and weather to news feeds and custom modules.
Here’s a quick overview of what you can do in config.js:
- Set global settings — language, time format (12 or 24-hour), and metric vs. imperial units
- Add or remove modules — enable a weather widget, disable the newsfeed, or add new ones
- Control module placement — choose from 11+ screen positions like
top_left,bottom_bar, ormiddle_center - Customize appearance — add CSS classes, headers, and entrance/exit animations
- Validate and restart — check for syntax errors and apply changes by restarting the app
MagicMirror² is an open-source smart mirror platform built on Node.js and Electron, designed to run on a Raspberry Pi. It has earned over 23,000 stars on GitHub — a sign of just how popular DIY smart mirrors have become.
The entire system runs on a modular architecture. Each widget (clock, weather, calendar) is a separate module. The config.js file is where you wire them all together, defining what shows up, where it appears, and how it behaves.
One forum user described the experience perfectly when starting out: finding what to change feels overwhelming at first — but once you understand that almost everything lives in one file, it gets much simpler.
Getting Started with Magic Mirror Configuration
When we first dive into smart mirrors, the terminal window is our best friend. To understand magic mirror configuration, we have to look at how the software is structured. Most of the magic happens inside a folder named MagicMirror/config.
If you have followed our Step-by-step smart mirror setup, you already have the software installed. Now, we need to tell that software what to do. The “brain” of your display is the config.js file. However, when you first install the software, this file doesn’t actually exist yet! Instead, you’ll find a template that we use to get started.
According to the Introduction to MagicMirror² Configuration, the directory structure is quite strict. You must be in the ~/MagicMirror/config directory to make these changes. If you try to edit files elsewhere, the mirror simply won’t pick up the updates.
Locating and Editing the Main Magic Mirror Configuration File
To find your configuration file, open your terminal and type:
cd ~/MagicMirror/config
Once you are in this folder, you will likely see a file named config.js.sample. To edit files on a Raspberry Pi, we usually use an editor called nano. It’s a simple, text-based editor that works right inside your terminal.
However, a common hurdle for beginners is the “Permission Denied” error. Because these are system-level files, you often need to use sudo (which stands for “superuser do”) to gain editing rights. For a smoother experience, some users prefer “Midnight Commander” (mc), which provides a visual file manager interface. You can install it by running sudo apt-get install mc.
If you are Configuring the Raspberry Pi, the way you edit the file matters. A single missing comma or a misplaced bracket can cause the whole screen to go black.
Creating Your First config.js from the Sample
Since the fresh installation only provides a sample, our first task is to create a working copy. We do this using the cp (copy) command. In your terminal, run:
cp config.js.sample config.js
This creates a real config.js file based on the Official config.js sample. Now, when you open this file, you’ll see a JavaScript object. Don’t let the code scare you! It’s mostly a list of settings wrapped in curly braces {} and brackets [].
Each module is an entry in a list. If you want to change something, you find the right section, change the text inside the quotation marks, and save the file. In nano, you save by pressing CTRL+O and exit with CTRL+X.
Mastering Module Placement and Customization
One of the coolest parts of magic mirror configuration is deciding where everything goes. You aren’t stuck with a static layout. You can move the clock to the bottom, put the weather in the center, or have news scrolling across the top.
Available Module Positions and How to Change Them
MagicMirror² uses a grid system to place modules. When you look at the Module Configuration Guide, you’ll see a variety of “regions.” Each module in your config.js has a position property.
Here is a breakdown of the standard positions we can use:
| Position Name | Location on Screen |
|---|---|
top_bar |
Very top, centered |
top_left |
Top left corner |
top_center |
Top middle area |
top_right |
Top right corner |
upper_third |
Below the top row |
middle_center |
Dead center of the mirror |
lower_third |
Above the bottom row |
bottom_left |
Bottom left corner |
bottom_right |
Bottom right corner |
bottom_bar |
Very bottom, centered |
fullscreen_above |
Overlays everything |
If you put two modules in the same position, like top_left, they will stack on top of each other in the order they appear in your config file. For those who want more control, you can even dive into Customizing the MagicMirror UI by modifying the index.html classes or adding specific alignment rules in your custom.css file.
Disabling or Removing Unwanted Modules
Sometimes, less is more. If you find the default newsfeed distracting or the “compliments” module a bit too cheesy, you don’t have to delete the code entirely.
The cleanest way to remove a module is to add disabled: true; inside that module’s configuration block. This tells the mirror to ignore that section of the code without you having to delete it. This is great for Advanced UI customization because it allows you to toggle features on and off as you test your design. You can also use hiddenOnStartup: true; if you want the module to load but remain invisible until a specific event (like a gesture or voice command) triggers it.
Configuring Core Modules: Clock and Weather
The clock and weather are the bread and butter of any smart mirror. Setting these up correctly requires a bit of attention to detail, especially when dealing with time formats and API keys.
Adjusting the Magic Mirror Configuration for Time and Units
By default, MagicMirror² often uses a 24-hour clock and metric units (Celsius/Kilometers). If you prefer a 12-hour format or Imperial units (Fahrenheit/Miles), you need to adjust the global settings at the top of your config.js.
According to the Clock Module Documentation, you can change the timeFormat property. Setting it to 12 will give you the standard AM/PM display, while 24 keeps it in military time. Similarly, changing units from metric to imperial will update the weather and other measurement-based modules.
If you are following our Coding guide for MagicMirror, you’ll know that localization is also key. You can change the language property (e.g., from en to fr or es) to ensure dates and days of the week are displayed in your native tongue.
Setting Up the Weather Module for Your Location
To get the weather working, you need more than just a line of code; you need data. Most users use OpenWeatherMap, which requires a free API key. Once you have your key, you’ll need to input it into the apiKey field in your magic mirror configuration.
In our Smart mirror JavaScript setup, we explain that you also need your location’s coordinates. You can find your lat (latitude) and lon (longitude) easily via Google Maps.
For a more modern approach, the JavaScript setup for smart mirrors suggests using providers like OpenMeteo, which sometimes don’t even require an API key for basic use. Don’t forget to set the fetchInterval—this determines how often the mirror checks for weather updates. Setting it to 10 minutes (600,000 milliseconds) is usually a good balance between fresh data and saving battery/bandwidth.
Advanced Tweaks: Animations, CSS, and Validation
Once the basics are set, it’s time to make the mirror feel “premium.” This involves smooth transitions and custom styling.
Custom Styles and Animations
As of version 2.25.0, MagicMirror² supports built-in animations using the animate.css library. You can add animateIn and animateOut properties to any module. For example, you could have your newsfeed slideInLeft when it updates and slideOutRight when it finishes. This adds a layer of polish that makes the DIY project feel like a professional product.
For deeper visual changes, we use the custom.css file. Instead of hacking the main module files, you should always put your style overrides here. This ensures that when you update your MagicMirror software, your custom colors and fonts don’t get wiped out. You can learn more about this in our UI customization part 3.
The configDeepMerge property is another advanced tool. It allows you to merge your custom settings with the module’s internal defaults more effectively, which is particularly useful for complex modules with many nested settings.
Validating Syntax and Restarting the Magic Mirror Configuration
The most frustrating part of magic mirror configuration is saving your file, restarting, and seeing a “MagicMirror²” logo with nothing else on the screen. This usually means there is a syntax error—like a missing comma.
Before you restart, always run the validation tool. In your terminal, go to the MagicMirror folder and run:
npm run config:check
This command will tell you exactly which line has an error. If everything looks good, you can restart. If you use PM2 (a process manager), you can simply type pm2 restart mm. If you are running it manually, stop the current process with CTRL+C and run npm start again.
For a more robust setup, our Complete smart mirror program guide recommends using an mm.sh script to handle these restarts automatically. This ensures that if the power dips or the app crashes, your mirror comes right back to life without you needing to plug in a keyboard.
Frequently Asked Questions about Magic Mirror Configuration
Why am I getting a “Permission Denied” error when editing?
This happens because the config.js file is protected by the system. To fix this, always prefix your edit command with sudo. For example: sudo nano ~/MagicMirror/config/config.js. This gives you the administrative privileges needed to save your changes.
How do I add a header to a specific module?
Most modules support a header property. Inside the module’s configuration block in config.js, simply add header: "My Custom Title",. This will place a small, styled title directly above that module on the mirror’s display.
Can I run multiple instances of the same module?
Yes! This is a common practice for weather and calendars. You might want one weather module showing your current city and another showing the forecast for your upcoming vacation spot. Just add the module block to the modules array twice, each with its own unique config settings.
Conclusion
Mastering magic mirror configuration is the gateway to making your smart mirror truly your own. While it might seem technical at first, it’s all about one file and a few basic rules of logic. Always keep a backup of your working config.js before making big changes—that way, if something breaks, you can revert in seconds.
We have seen the community grow tremendously, with the repository now boasting over 23,000 stars. This popularity means that if you run into a problem, someone on the forums has likely already solved it. Whether you are adjusting the clock to a 12-hour format or adding complex animations, the flexibility of MagicMirror² is what makes it the gold standard for DIY smart displays.
Ready to take the next step? Explore more smart mirror hardware to find the perfect frame or monitor for your project. Happy building!
