feat(upgrade): implement `to` argument for precise version control

[OrbisK]

This feature allows precise control over the desired version for Nuxt and all its sub-packages. It provides the flexibility to, for instance, update only to the next minor version.

The more I look at it, the bigger the changes. I've just seen that the upgrade effectively only deletes the lockfile and updates everything. Is there no way to just update all nuxt deps?

Cant nuxi upgrade install nuxt version and dedupe lockfile with the same effect?

EDIT: dedupe is now a thing 😄

[dervondenbergen]

I just wanted to open a new issue and saw, that his one already exists.

My usecase is sadly not solved by --dedupe as I only want to upgrade from a v3.16.3 to a v3.17.7, so only minor + patch. When I run the upgrade command now I get v4.0.0 where things are breaking altough I only want to update to the latest minor and see if everything works there before upgrading major version.

Would this be the same issue or should I open a new ticket for my usecase?

[OrbisK]

I think there are two or three options here:

Option 1: use channel option

• use existing channel option and add something like v3 and v4

Option 2: add range(?) option

• have a option to keep the current semver range and upgrade to latest possible
• default to keep
• have other options to allow major/minor/patch upgrades

Option 3: add to option

• be able to pass custom range. like 4, 3, ^3.1.0, latest, ...

[danielroe]

channel feels good to me....

[xak2000]

The instruction in Release Notes now says:

npx nuxt upgrade --dedupe --channel=v3

But this doesn't work. Upgrading from 3.11.2 I still get v4.

Probably that is because my local nuxt in node_modules doesn't have this PR #1019 included, right?

But then, what is the correct way to upgrade then? The instructions in the Release Notes (as an example let's see the instruction here) need to be updated.

My current workaround is:

manually update the Nuxt version in package.json and then run yarn install and yarn dedupe to update the @nuxt/kit version.

But this works only because I use Yarn v4. Not sure if npm has inbound dedupe command.

[OrbisK]

npx caches binaries.

You should use:

npx nuxt@latest upgrade --dedupe --channel=v3

cc @danielroe maybe we should start suggesting this?

[xak2000]

Thanks for the answer. I suspected something like this, but then the @latest part is mandatory and should be used in the recommended upgrade instructions.

[danielroe]

the issue is simply that @nuxt/cli is a dependency of your project and you won't benefit from new features (like --channel) unless you have already updated it.

please do not use nuxt@latest - it will pull in a new and different version of nuxt and run that binary. instead, either upgrade your project, after which the new feature will be available, or use nuxi@latest, which is a standalone binary for occasions like this.

[xak2000]

@danielroe I'm not sure I fully understand your answer. We are discussing Nuxt upgrade command, that by definition must:

1. Not require any preliminary actions from a user (or if any preliminary actions are required they need to be documented).
2. Not mess with the current project dependencies (except for the upgading itself).

the issue is simply that @nuxt/cli is a dependency of your project and you won't benefit from new features (like --channel) unless you have already updated it.

This I understand.

please do not use nuxt@latest - it will pull in a new and different version of nuxt and run that binary

This I do not understand. In package.json of nuxt package I seen that @nuxt/cli is listed as a dependency. So, when I run npx nuxt@latest ... the NPM actually downloads not just @nuxt/cli, but the whole nuxt library? And it downloads it not just into a temporary dir, but right into nuxt_modules of the current project? 😮 That is what you mean?

Sorry for maybe newbie questions but coming from Java ecosystem this all looks very confusing.

either upgrade your project, after which the new feature will be available

But, this is what we are discussing here in the first place, aren't we? :) How to upgrade Nuxt v3 library to a never Nuxt v3 in a project. It is just happened that this new feature is actually required to do this. The instructions in the Release Notes (as an example let's see the instructions here) include an "incorrect" command, then. They say: npx nuxt upgrade --dedupe --channel=v3 which doesn't work by definition if you are on the old version of Nuxt. By "incorrect" I don't mean it is totally wrong. I mean that it will not work for all users. Users who are on an older Nuxt version (which doesn't have channel=v3 feature) will not be able to use this command to upgrade. And we want to have a command in our instructions that will cover as many users as possible, right?

The instructions in the official documentation for v3 are even worse: they just say yarn nuxt upgrade, without even mentioning --channel=v3. I understand why this happened (because last time when the official documentation for v3 was updated these instructions were actually correct), but probably they need to be updated, then?

or use nuxi@latest, which is a standalone binary for occasions like this.

It took me a very long time to understand that nuxi is actually an abbreviation for nuxt cli. :)) Very surprising and confusing name to be honest. I would prefer nuxt-cli or @nuxt/cli or something more intuitive, but ok. :) I think this fact should be added to the official documentation because my brain just wasn't able to connect why "Nuxt CLI" is called "nuxi". Maybe "why" feels like not important as long as you know that nuxi is the official command for Nuxt CLI, but for some reason the absense of this understanding was really confusing and didn't allow me to clearly think about it.

Anyway, then, shouldn't it be the official way of upgading Nuxt if this is the only way that will work by running a single command and will not mess with the node_modules of the project?

Again, sorry for maybe dumb questions. But currently it's a mess. In several different places there are several different upgrade commands listed, and none of them are actually working. :)

I know, I know... The command mentioned in the release notes works for some specific cases (when you areadly have Nuxt v3 that supports --channel=v3 feature). But do we really want to use a command that works for fewer number of cases as an official instructions?

I would gladly create a PR to fix the official docs for v3, if you approve that the "correct" command that should be used instead of nuxt upgrade is:

npx nuxi@latest upgrade --dedupe --channel=v3

I can't update the release notes, though. Maybe you can update them, please, so other users will use the correct command (that works in more cases) to upgrade their Nuxt projects?

[danielroe]

in general, the docs should show: npx nuxt upgrade --dedupe --channel=v3. (we can indicate that channel might not be supported for older versions of nuxt).

in release notes we can use npx nuxi@latest if --channel isn't supported by your current version of nuxt/cli. (as I did in the most recent patch).

other than downloading more than needed, there's nothing wrong with running npx nuxt@latest

[xak2000]

Now I'm confused even more then before. :D

You said:

please do not use nuxt@latest - it will pull in a new and different version of nuxt and run that binary

And then:

other than downloading more than needed, there's nothing wrong with running npx nuxt@latest

[danielroe]

I'm saying that it downloads too much.

it will be slow. that is why you should not use nuxt@latest. it will download a fresh version of nuxt (though it will not affect the node_modules in your project) along with fresh versions of vite, oxc, etc.