packages/vite/src/shared/server.ts (1)

64-68: Consider standard condition ordering.

The condition 'UNUSED_EXTERNAL_IMPORT' === warning.code uses Yoda-style comparison, which is uncommon in modern JavaScript. While not incorrect, the standard ordering warning.code === 'UNUSED_EXTERNAL_IMPORT' improves readability.

Apply this diff to use standard condition ordering:

-        if (warning.code && 'UNUSED_EXTERNAL_IMPORT' === warning.code) {
+        if (warning.code === 'UNUSED_EXTERNAL_IMPORT') {
           return
         }

packages/vite/src/plugins/client-manifest.ts (1)

68-88: Consider adding error handling for file operations.

The file operations (mkdir, writeFile, rm) are currently unguarded. Whilst this may be acceptable in a build context where failures would propagate naturally, adding explicit error handling could improve debuggability and provide clearer error messages for file system issues.

Consider wrapping the file operations in a try-catch block:

+    try {
       await mkdir(serverDist, { recursive: true })

       if (disableCssCodeSplit) {
         for (const entry of manifestEntries) {
           if (entry.file?.endsWith('.css')) {
             clientManifest[key]!.css ||= []
             ;(clientManifest[key]!.css as string[]).push(entry.file)
             break
           }
         }
       }

       const manifest = normalizeViteManifest(clientManifest)
       await nuxt.callHook('build:manifest', manifest)
       const precomputed = precomputeDependencies(manifest)
       await writeFile(resolve(serverDist, 'client.manifest.mjs'), 'export default ' + serialize(manifest), 'utf8')
       await writeFile(resolve(serverDist, 'client.precomputed.mjs'), 'export default ' + serialize(precomputed), 'utf8')

       if (!nuxt.options.dev) {
         await rm(manifestFile, { force: true })
       }
+    } catch (err) {
+      throw new Error(`Failed to write client manifest: ${err}`)
+    }

packages/vite/src/vite.ts (1)

270-294: Consider adding error handling for dev server creation.

The handleEnvironments function lacks explicit error handling for the createServer and buildApp calls. If these operations fail, the error will propagate but without context about which environment failed.

Add try-catch blocks with contextual error messages:

 async function handleEnvironments (nuxt: Nuxt, config: vite.InlineConfig) {
   config.customLogger = createViteLogger(config)
   config.configFile = false

   for (const environment of ['client', 'ssr']) {
     const environments = { [environment]: config.environments![environment]! }
     const strippedConfig = { ...config, environments } as ViteConfig
     const ctx = { isServer: environment === 'ssr', isClient: environment === 'client' }
     await nuxt.hooks.callHook('vite:extendConfig', strippedConfig, ctx)
     await nuxt.hooks.callHook('vite:configResolved', strippedConfig, ctx)
   }

   if (!nuxt.options.dev) {
+    try {
       const builder = await createBuilder(config)
       await builder.buildApp()
+    } catch (err) {
+      throw new Error(`Failed to build Vite app: ${err}`)
+    }
     return
   }

+  try {
     await withLogs(async () => {
       const server = await createServer(config)
       await server.environments.ssr.pluginContainer.buildStart({})
     }, 'Vite dev server built')

     await writeDevServer(nuxt)
+  } catch (err) {
+    throw new Error(`Failed to create Vite dev server: ${err}`)
+  }
 }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: TheAlexLichter
PR: nuxt/nuxt#31812
File: packages/nuxt/src/components/plugins/islands-transform.ts:202-202
Timestamp: 2025-04-18T18:33:41.753Z
Learning: In Nuxt, using `rolldownVersion` (not `rollupVersion`) is intentional when detecting if rolldown-vite is being used, even though TypeScript may show an error because the property isn't in standard type definitions yet.

docs/2.guide/4.recipes/2.vite-plugin.md (1)

82-98: Documentation addition is clear; verify plugin example is sufficiently complete.

The new section appropriately distinguishes Nuxt 5+ environment-specific usage. However, the placeholder comment on line 94 ("// Plugin configuration") leaves the example incomplete—readers may be uncertain what a full plugin implementation should contain. Consider either providing a minimal working example (e.g., a resolveId hook) or explicitly stating that developers should add their plugin logic here.

Consider expanding the example with minimal plugin implementation:

addVitePlugin(() => ({
  name: 'my-client-plugin',
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
  resolveId (id) {
    if (id === 'virtual-client-module') {
      return id
    }
  },
  load (id) {
    if (id === 'virtual-client-module') {
      return `export default { message: 'client-only' }`
    }
  },
}))

Alternatively, if the intent is to show only the structure, consider making it clear with a comment: "// Add your plugin hooks here".

docs/3.api/5.kit/14.builder.md (3)

17-19: Deprecation warning is appropriate.

The warning correctly indicates the hook is deprecated and recommends the newer approach. However, it could be more specific about when this applies: "Deprecated in Nuxt 5+" would be clearer than just stating it "is now deprecated".

Update the warning text for greater clarity:

- This hook is now deprecated, and we recommend using a Vite plugin instead with a `config` hook, or — for environment-specific configuration — the `applyToEnvironment` hook.
+ This hook is **deprecated in Nuxt 5+** and we recommend using a Vite plugin instead with a `config` hook, or — for environment-specific configuration — the `applyToEnvironment` hook.

---

37-74: Migration examples are comprehensive and well-structured.

The before/after pattern is excellent for migration guidance. The distinction between config (global), configEnvironment (per-environment), and applyToEnvironment (filtering) is clear. The warning at lines 72-74 appropriately flags the ordering caveat.

One minor improvement: the example at line 68 references a non-existent environment.name property without first establishing what properties environment objects have. While readers can infer it from context, adding a brief inline comment would help.

Consider adding context about the environment object:

    // For environment-specific configuration
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
+       // `environment.name` is 'client' or 'ssr' (or custom names)
        return environment.name === 'client'
      },

---

157-159: Deprecation warning for addVitePlugin is helpful.

The warning correctly explains the behaviour change in Nuxt 5+: plugins with server: false or client: false will no longer have their config or configResolved hooks called. This is important for users to understand the migration.

However, the warning could be even clearer about the reason: these hooks operate on shared configuration in Nuxt 5+, so per-environment filtering changes how they behave. Consider linking to the applyToEnvironment() hook documentation.

Enhance the warning with a link to environment-specific plugin documentation:

- In Nuxt 5+, plugins registered with `server: false` or `client: false` options will not have their `config` or `configResolved` hooks called. Instead, use the `applyToEnvironment()` method instead for environment-specific plugins.
+ In Nuxt 5+, plugins registered with `server: false` or `client: false` options will not have their `config` or `configResolved` hooks called (as Vite uses a shared configuration). Instead, use the `applyToEnvironment()` method for environment-specific plugins. See [migration guide](#migration-to-vite-environment-api) for details.

docs/1.getting-started/18.upgrade.md (2)

66-95: "Migration to Vite Environment API" section is comprehensive and well-structured.

The introduction clearly explains what changed and why. The key changes are accurate and important. The tip at lines 76-78 provides helpful guidance on testing early.

However, the phrasing "Previously, Nuxt used separate client and server Vite configurations" could be slightly clearer: "Previously, Nuxt maintained separate Vite configurations for client and server bundles" would be more precise.

One potential issue: Line 84 states "will not have their config or configResolved hooks called" but this might be confusing to readers unfamiliar with Vite plugin architecture. Consider adding a clarifying note about why this happens (shared configuration model in Vite 6).

Add clarification about the hook behaviour change:

2. **Changed plugin registration**: Vite plugins registered with `addVitePlugin()` and only targeting one environment (by passing `server: false` or `client: false`) will not have their `config` or `configResolved` hooks called.
+ 
+   This is because Nuxt 5+ uses a shared Vite configuration model, and per-environment plugin filtering happens at registration time rather than during hook execution.

---

96-135: Migration steps provide excellent before/after examples.

The "Migrate to use Vite plugins" step (lines 98-135) is particularly helpful. It shows three common patterns:

1. Using extendViteConfig with server: false
2. Using Nuxt hooks like vite:extendConfig
3. The recommended approach using addVitePlugin with environment-specific hooks

The examples are clear and runnable. The "Migrate Vite plugins to use environments" section (lines 137-171) demonstrates the applyToEnvironment pattern effectively.

One suggestion: The examples at lines 102-112 and 141-149 are somewhat duplicative (both show before patterns). Consider consolidating or cross-referencing.

docs/3.api/6.advanced/1.hooks.md (1)

78-79: Deprecation notes appropriately flag the behaviour change.

The table entries clearly indicate these hooks are deprecated in Nuxt 5+ and explain the key difference: operating on shared configuration rather than separate configs. This is consistent with messaging in other files.

However, the table format limits detail. Consider whether users should be directed to the migration guide. Since this is an API reference, the current brief approach is appropriate, but adding a note like "(see migration guide)" could improve discoverability.

Add migration guide reference for discoverability:

- `vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
- `vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
+ `vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config. **Deprecated in Nuxt 5+** (see [migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api)). In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
+ `vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config. **Deprecated in Nuxt 5+** (see [migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api)). In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.

docs/2.guide/3.going-further/1.experimental-features.md (1)

899-921: New viteEnvironmentApi experimental feature section is well-integrated.

The section appropriately documents the experimental feature, explains the default behaviour with future.compatibilityVersion: 5, and provides clear enabling instructions. The warning at lines 915-917 helpfully directs users to the migration guide.

The description at line 913 could be slightly more concrete. Saying "better consistency between development and production builds" and "more granular control" is good, but readers might benefit from a brief example or more specific benefit.

Enhance the benefits description with more specificity:

- The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.
+ The Vite Environment API provides:
+ - Better consistency between development and production builds through unified configuration
+ - More granular control over environment-specific configuration via `applyToEnvironment()`
+ - Improved performance and plugin architecture alignment with Vite 6

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro