what does npm run update do that npm ci did not?

@brianteeman
Hi, thanks for the quick reply and the great question!

Just to add some context, I'm new to contributing to Joomla, so I was following the setup guide with a fresh perspective.

From what I could tell, npm ci did a great job of downloading all the external tools and libraries that the project depends on.

However, after it finished, it seemed like there was a missing step to actually build Joomla's own CSS and JavaScript files from the source code. I looked in the package.json and found the npm run update command, which seemed to do that final compilation.

So, I guess the difference is that npm ci gathers all the parts, while npm run update puts them together for the site to use. Without it, the site seemed to be missing its assets.

Hope that clarifies things! Happy to help further if I can.

i ask because from my own experience npm ci does everything

In my case, after npm ci finished, the site's CSS and JS assets were definitely missing. Running npm run update manually was the necessary step that created them.

It seems like this automatic step might not be working reliably on all systems. Adding npm run update to the README would be a clear instruction for anyone who runs into the same situation.

Seems very odd

@tarunsaini04 I cannot reproduce the need of running npm run update.

When you do a composer install and then an npm ci, all assets are created.

The only thing which is not done because done only when building the packages are the gzipped assets.

I cannot count how many hundreds or even thousands times I have done that for Joomla versions 4, 5 and 6 on different environments. There never was something missing for me.

And I have also verified how other release managers have built their packages on Windows. There never was the need to run npm run update.

Could you report back details on your environment and what is missing for you?

If you are using Windows: Are you using WSL2? Or a pure Windows CMD without WSL?

@richard67 , thanks for digging into this! Hopefully, the details of my setup can help explain why our results were different.

I'm on a pretty standard Windows 11 machine (not using WSL2), with the latest XAMPP (PHP 8.2.12) and Node.js (v20.16.0).

The odd part was, after npm ci completed, I realized there wasn't an instruction to compile the frontend assets. When I checked the /media directory, I could see that the final CSS and JS files had not been created.

It was only after I manually ran npm run update that all those asset files were generated, preparing the site to be run correctly.

So, my guess is that the automatic build step might not be triggering reliably on a 'vanilla' Windows setup like mine. If you think this is a scenario others might face, then adding a quick note to the README about running npm run update would be a huge help for future contributors.

@tarunsaini04 As I've said, that has never been observed before by anyone. So I am against adding that step to the description of the regular procedure. However, it could make sense to add it to a trouble-shooting section.

Lots of us have that same windows setup without issue

Thanks for confirming it's not a common issue.
I think the suggestion to add a note to a troubleshooting guide is the perfect solution for anyone who might encounter this in the future.
Thanks for all the help, everyone!

It would be interesting to know if you can repeat the problem. I am wondering if you did the npm part before composer and that caused the problem

Hey everyone, quick update.

I reran the entire setup on a clean system to be sure, and to answer the question about command order: I can confirm I definitely ran composer install first, before npm ci.

The re-test today solved the mystery. You are all correct that a successful npm ci builds everything automatically. The problem in my first attempt was that npm ci crashed during the Cypress download, most likely because it was blocked by my security software (Windows Defender), so it never got to the automatic build step at the end.

This leaves the project in a broken state with missing assets and no instructions on how to fix it. The manual npm run update command was the necessary workaround for that failure.

So, your suggestion to add this scenario to a troubleshooting section is the perfect solution.

Thanks for all the help in tracking this down!

@tarunsaini04 It does not need npm run update to fix a broken state.

You simply use git commands to reset your local branch to a clean state, and then start from the beginning with composer install and npm ci. You can clean up a branch e.g. with git clean -d -x -f to clean up any added files or folders, and then git checkout . to revert any changes on files.

Or even easier: Just remove your complete local git clone, i.e. remove the complete folder where your clone is in, and then clone your repository again.

This makes sure you have a clean, unmodified state.

Fixing a broken state with npm run update will not do that. There still might be broken remainders.

So I am even against adding it to a troubleshooting section.

... or check each command to make sure that they complete successfully. Presumably your failed npm i had a meaningful error message at the end

That's a fair point. Your explanation of the correct developer workflow using git clean makes a lot of sense.

My feedback was based purely on my experience as a newcomer, where the path to recovery wasn't immediately obvious when the documented steps failed.

I'll leave it to you all to decide what's best for the documentation. I just wanted to share my experience in case it was helpful.

Thanks again for your time and the detailed discussion!