Skip to content

feat(upgrade): add v5-nightly and soft-deprecate v3 channels #1631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danielroe merged 3 commits into from
Oct 26, 2026
Merged

feat(upgrade): add v5-nightly and soft-deprecate v3 channels #1631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b706605
feat: add `nightly-v5` upgrade channel
OrbisK Oct 23, 2026
10a11e0
chore: soft deprecated v3 channel
OrbisK Oct 23, 2026
664e75c
test(upgrade): cover nightly dist-tags and drop `v3` from docs
danielroe Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ links:

<!--upgrade-cmd-->
```bash [Terminal]
npx nuxt upgrade [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dedupe] [-f, --force] [-ch, --channel=<stable|nightly|v3|v4|v4-nightly|v3-nightly>]
npx nuxt upgrade [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dedupe] [-f, --force] [-ch, --channel=<stable|nightly|v4|v4-nightly|v5-nightly>]
```
<!--/upgrade-cmd-->

The `upgrade` command upgrades Nuxt to the latest version. It updates the version in your [`package.json`](/docs/directory-structure/package), reinstalls dependencies with your package manager and removes the build cache.

`--channel` picks what to upgrade to: `stable` for the latest release, `v3` or `v4` to stay on a major, and `nightly`, `v3-nightly` or `v4-nightly` for the nightly release channel.
`--channel` picks what to upgrade to: `stable` for the latest release, `v4` to stay on a major, and `nightly`, `v4-nightly` or `v5-nightly` for the nightly release channel.

`--force` recreates the lockfile and `node_modules` from scratch, and `--dedupe` deduplicates dependencies afterwards where the package manager supports it.

Expand All @@ -33,11 +33,11 @@ A dependency pinned to a pnpm catalog (`"nuxt": "catalog:"`) is upgraded in `pnp
## Options

<!--upgrade-opts-->
| Option | Default | Description |
|--------------------------------------------------------------------|----------|-----------------------------------------------------|
| `--cwd=<directory>` | | Specify the root directory of your Nuxt project |
| `--logLevel=<silent\|info\|verbose>` | | Specify build-time log level |
| `--dedupe` | | Dedupe dependencies after upgrading |
| `-f, --force` | | Force upgrade to recreate lockfile and node_modules |
| `-ch, --channel=<stable\|nightly\|v3\|v4\|v4-nightly\|v3-nightly>` | `stable` | Specify a channel to install from |
| Option | Default | Description |
|----------------------------------------------------------------|----------|-----------------------------------------------------|
| `--cwd=<directory>` | | Specify the root directory of your Nuxt project |
| `--logLevel=<silent\|info\|verbose>` | | Specify build-time log level |
| `--dedupe` | | Dedupe dependencies after upgrading |
| `-f, --force` | | Force upgrade to recreate lockfile and node_modules |
| `-ch, --channel=<stable\|nightly\|v4\|v4-nightly\|v5-nightly>` | `stable` | Specify a channel to install from |
<!--/upgrade-opts-->
14 changes: 9 additions & 5 deletions packages/nuxt-cli/src/commands/upgrade.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,8 @@ export async function resolveCatalogSpecifier(spec: InstallSpec, current?: strin

const nuxtVersionTags = {
'3.x': '3x',
'4.x': 'latest',
'4.x': '4x',
'5.x': '5x',
Comment on lines -98 to +99

@OrbisK OrbisK Oct 23, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we have to confirm that those are actually the up to date tags we are using before merging this PR

}

type NuxtVersionTag = keyof typeof nuxtVersionTags
Expand All @@ -108,8 +109,8 @@ async function getNightlyVersion(packageNames: string[]): Promise<{ npmPackages:
const nuxtVersion = await select({
message: 'Which nightly Nuxt release channel do you want to install?',
options: [
{ value: '3.x' as const, label: '3.x' },
{ value: '4.x' as const, label: '4.x' },
{ value: '5.x' as const, label: '5.x' },
],
initialValue: '4.x' as const,
})
Expand All @@ -130,12 +131,14 @@ async function getRequiredNewVersion(packageNames: string[], channel: string): P
return getNightlyVersion(packageNames)
case 'v3':
return { npmPackages: packageNames.map(p => `${p}@3`), nuxtVersion: '3.x' }
case 'v3-nightly':
return { npmPackages: packageNames.map(p => getNightlyDependency(p, '3.x')), nuxtVersion: '3.x' }
case 'v4':
return { npmPackages: packageNames.map(p => `${p}@4`), nuxtVersion: '4.x' }
case 'v3-nightly':
return { npmPackages: packageNames.map(p => getNightlyDependency(p, '3.x')), nuxtVersion: '3.x' }
case 'v4-nightly':
return { npmPackages: packageNames.map(p => getNightlyDependency(p, '4.x')), nuxtVersion: '4.x' }
case 'v5-nightly':
return { npmPackages: packageNames.map(p => getNightlyDependency(p, '5.x')), nuxtVersion: '5.x' }
case 'stable':
default:
return { npmPackages: packageNames.map(p => `${p}@latest`), nuxtVersion: '4.x' }
Comment on lines 132 to 144

@OrbisK OrbisK Oct 23, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should already introduce v5, but dont document it like with nuxt 3 in this pr

Expand Down Expand Up @@ -164,7 +167,8 @@ export default defineCommand({
alias: 'ch',
default: 'stable',
description: 'Specify a channel to install from',
options: ['stable', 'nightly', 'v3', 'v4', 'v4-nightly', 'v3-nightly'],
options: ['stable', 'nightly', 'v3', 'v4', 'v3-nightly', 'v4-nightly', 'v5-nightly'],
valueHint: 'stable|nightly|v4|v4-nightly|v5-nightly',
},
},
async run(ctx) {
Expand Down
21 changes: 21 additions & 0 deletions packages/nuxt-cli/test/unit/commands/upgrade-run.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,27 @@ describe('upgrade install', () => {
expect(runInstall).toHaveBeenCalledWith(expect.objectContaining({ dependencies: ['nuxt@3'] }))
})

it.each([
['v3-nightly', '3x'],
['v4-nightly', '4x'],
['v5-nightly', '5x'],
])('should install the %s channel from the %s nightly dist-tag', async (channel, tag) => {
await runUpgrade([`--channel=${channel}`])

expect(runInstall).toHaveBeenCalledWith(expect.objectContaining({ dependencies: [`nuxt@npm:nuxt-nightly@${tag}`] }))
})

it.each([
['4.x', '4x'],
['5.x', '5x'],
])('should install the %s nightly picked from the prompt', async (answer, tag) => {
answers.select.push(answer)

await runUpgrade(['--channel=nightly'])

expect(runInstall).toHaveBeenCalledWith(expect.objectContaining({ dependencies: [`nuxt@npm:nuxt-nightly@${tag}`] }))
})

it('should upgrade the core packages the project depends on', async () => {
await writeProject({ 'package.json': JSON.stringify({ name: 'app', devDependencies: { 'nuxt': '^4.0.0', '@nuxt/kit': '^4.0.0' } }) })

Expand Down
8 changes: 4 additions & 4 deletions packages/nuxt-cli/test/unit/help.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -468,10 +468,10 @@ describe('help', () => {

OPTIONS

--logLevel=<silent|info|verbose> Specify build-time log level
--dedupe Dedupe dependencies after upgrading
-f, --force Force upgrade to recreate lockfile and node_modules
-ch, --channel=<stable|nightly|v3|v4|v4-nightly|v3-nightly> Specify a channel to install from (Default: stable)
--logLevel=<silent|info|verbose> Specify build-time log level
--dedupe Dedupe dependencies after upgrading
-f, --force Force upgrade to recreate lockfile and node_modules
-ch, --channel=<stable|nightly|v3|v4|v3-nightly|v4-nightly|v5-nightly> Specify a channel to install from (Default: stable)
"
`)
})
Expand Down
Loading