feat(nuxt): add experimental app:chunkError hook and reload strategy

[danielroe]

🔗 Linked issue

resolves #14594

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR adds a feature that can be enabled with the experimental.emitRouteChunkError option. This will catch chunk loading errors and calls the app:chunkError page. This can be handled with something like this:

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('app:chunkError', ({ error }) => {
    console.log('caught chunk load error'))
  })
})

You can also set experimental.emitRouteChunkError to reload to enable an automatic hard reload when navigating if the new route triggers a chunk loading error.

Notes:

• In webpack, a chunk error is not thrown when fetching payloads, although it does with vite. I think this is fine - errors fetching payload aren't really the kind of error we're trying to catch as payloads aren't hashed.
• this approach does not suppress chunk errors. perhaps we can find a way for user to indicate that an error is 'handled' so we can then avoid throwing it.
• the reload strategy does not handle all chunk errors, just ones on route navigation. For example, issues with prefetching chunks won't reload the page, though the error will still be thrown and it's possible to handle this intentionally

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codesandbox]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[danielroe]

We could also catch this directly here:

Suggested change

	nuxtApp.hook('app:chunkError', ({ error }) => { chunkError = error })
	nuxtApp.hook('app:chunkError', ({ error }) => {
	if (nuxtApp._processingMiddleware) {
	// handle error here
	}
	})

I've not done that here in case the user has handled the error, but it's worth keeping in mind if someone has a better idea.

[clarkdo]

Nice!

[pi0]

Nice work! For me it even looks good to be out of experimental flag testing on edge only.

One note about implementation it would be nice if the "reload" functionality extracted as a composable utility reloadNuxtApp({ error? }). It can be useful for outside integrations too such as handling app updates.

[danielroe]

Great! 😊 I think we can include in next minor, along with extracting reload helper. 👍 For now I'll keep it under flag so we can merge in a patch release.

[scofield-ua]

@danielroe so this is how I can set it in nuxt.config.ts:

export default defineNuxtConfig({
   experimental: {
      emitRouteChunkError: 'reload'    
   }
})

Is that correct?

[danielroe]

@scofield-ua The API changed a little bit in #19086.

The jsdocs should give the possible configuration options for this. It is enabled by default in v3.3+.