Add instructions for upgrading node when upgrade of MM fails

[dathbe]

The last two times I have tried to upgrade MM, I have encountered errors because my node version was not correct. Thus, I think we should include information here about how one would properly go about upgrading node. I have included in this PR what works for me, but I am FAR from an expert in node.

[sdetweil]

but you have to install n too. doesn't work on windows.

[dathbe]

I would guess there's a big chunk of users on debian or another similar linux flavor, and if they're all going to encounter this issue, I feel like we should include some kind of instruction. Even if it's noted that it only applies to linux install.

[sdetweil]

my upgrade script does all that

[khassel]

I think installing node is unrelated to mm, yes, it is required but the users should be able to google the things they need. Other thing is that there is not one method for installing node but several. I'm not for adding this to our docs here because it is outdated to fast.

[dathbe]

From the MM install instructions:

Can't we give some kind of similar pointer for upgrading?

[dathbe]

my upgrade script does all that

Which script is that? npm run install-mm? That's the script I used, and i encountered the error relating to node version.

I'm just trying to make this as easy as possible on users. Yes, I was able to Google the answer pretty quickly, but I have to do that each time I upgrade MM because it's not something I commit to memory. If we put some instructions on the upgrade page, it makes this more user friendly.

[khassel]

we can clearify docs and add e.g. an upgrade section, my point is that I don't want details concerning node in the docs which are changing to fast ...

[dathbe]

we can clearify docs and add e.g. an upgrade section, my point is that I don't want details concerning node in the docs which are changing to fast ...

That's fine. There's already an upgrade section, we just need to point people to some resources on node so they don't have to go floating around to find answers themselves and potentially find bad info.

For what it's worth, this was my upgrade experience:

1. Receive notification on my mirror that MM was out of date. (amazing!)
2. Go to the MM website to look up upgrade instructions because upgrades happen rarely enough I haven't committed it to memory.
3. Find that there are simple instructions for upgrading that involve one line of code I can paste. (yay!)
4. Run the one line of upgrade code.
5. Find that the first half of the code does not work because git reports that I have modified files.
6. Read the documentation to find I need to run git status to figure out what I supposedly changed.
7. Find that I have apparently changed package-lock.json. (This is potentially my fault, of course, but I don't recall doing anything with this package-lock file).
8. Remove package-lock.json.
9. Run the one line of upgrade code.
10. Find that the code still fails because git reports that I have modified files.
11. Run git status again.
12. Find that it now is upset that I have removed package-lock.json.
13. Read the documentation to find I need to run git restore package-lock.json to re-load the file from the repository.
14. Run the one line of upgrade code.
15. Find that the second part of the code doesn't work because my node version is out of date.
16. Search the interwebs for information on how I would upgrade my version of node.
17. Find an answer and paste the code into my terminal, praying that it won't do anything weird.
18. Run the one line of upgrade code.
19. Profit.

[khassel]

so we could e.g. add a sentence here that maybe a nodejs update is required

[dathbe]

so we could e.g. add a sentence here that maybe a nodejs update is required

That's what this PR does.

[khassel]

yes, but you are using a specific command for upgrading which maybe is not installed. I would like to see something like
(maybe a native english speaker can prettify this if needed)

Your upgrade may fail if you do not have the version of node required by the
latest release of MagicMirror². In this case you have to install the needed node version first.

[sdetweil]

my upgrade script is same place as install script
https://github.com/sdetweil/MagicMirror_scripts

[sdetweil]

and i post notes to the forum
https://forum.magicmirror.builders/topic/19271/version-2-30-0-requires-updated-nodejs-warning-for-pi0w-installations

[sdetweil]

and for 2.31, which has instructions on how to get back if you accidentally did the git pull, and CANNOT upgrade node

https://forum.magicmirror.builders/topic/19558/version-2.31.0-april-1-2025-requires-updated-nodejs-warning-for-pi0w-installations

[sdetweil]

AND IF your MagicMirror implementation uses any modules that have gpio interaction, buttons, pir...

you MAY have to run electron-rebuild on them
because we upgraded electron and nodejs

and my upgrade script handles all that too

[KristjanESPERANTO]

I like the intention of the pull request. But I agree with @khassel, since there is no standard way for all platforms, we should not refer to a specific one in our documentation.

I, for example, prefer nvm as it is much more flexible and updates don't require sudo - this is also recommended on the node.js website for our main target platform (Linux). n is not even mentioned there.

Instead of recommending one way, it might make sense to recommend in our installation section to use a version manager for the node installation, which is offered on the official node website (https://nodejs.org/en/download).

In the update section of our documentation we could then say that you should update using the version manager that was selected during node installation.

[dathbe]

I went looking on the Node repository for upgrade instructions, and they basically boil down to "just reinstall it". Let me review the resources Kristjan provided and I'll propose something new. It might not be for a bit, so if someone whats to jump on it, great.

[dathbe]

my upgrade script is same place as install script
https://github.com/sdetweil/MagicMirror_scripts

Perhaps the solution is to reference your upgrade script in the upgrade documentation, like your install script is referenced in the install instructions. I'll play with it and propose something based on the comments here.

[sdetweil]

and just for completeness, if you didn't know, i try to get everyone to backup.
see https://github.com/sdetweil/MagicMirror-backup-restore
as one tool

not MagicMirror's job, but its good practices

[dathbe]

I tried again on a commit for this PR. I now realize that the upgrade script was referenced at the bottom of the page. This commit makes it a little more prominent, gives a little more info, and points directly to the anchor for the upgrade section of your scripts repository. Let me know if it now works.

I back up my custom files offsite and on. You could blow a cannon through my Pi and I'd be back up and running within an hour of getting a new one.

Edit: I just realized there's no mention of node upgrading under manual. Give me time to make a new commit before you review/approve/reject.

[dathbe]

Ok. Please let me know if I'm on the right track.

[KristjanESPERANTO]

I like the direction. I think it's great that the script exists and for some people it's certainly just the right thing, but since we want to encourage people to learn how the system works, I would somehow like to see that the documentation communicates that the manual way is the recommended way.

What do you think about adding something like this in the script section:

---

For users who prefer a straightforward and automated solution, this script offers a practical alternative. While convenient, using the script may mean you gain less insight into the system, potentially making it harder to troubleshoot issues independently.

---

Or would that just be unnecessary bloat? I'm not so sure yet myself.

[dathbe]

I don't mind it, but you all are in charge.
Maybe a similar disclaimer on the install page, though? I tried to model the upgrade page off the install page.

[KristjanESPERANTO]

I am not in a position to make a decision here. I just try to contribute to the process to find a good solution 🙂