feat(nuxt): enable chunk error handling by default

[danielroe]

🔗 Linked issue

#19038 (comment)
#14594
resolves #19182

❓ 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 is the next step to enabling chunk error handling by default in Nuxt apps.

Progress

• add reloadNuxtApp composable.
• add documentation for composable and chunk error handling
• remove experimental flag for emitting errors (and enable reload strategy by default)
• resolve emitRouteChunkError: 'reload' redirects incorrectly with hashMode: true #19182
• allow preserving nuxtApp state during reload (requires opt-in)
• Add more documentation for the reload strategy in Error Handling docs section

Future enhancements

• possibly handle chunk errors outside route navigation?
• allow users to suppress chunk errors

📝 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

[mcrapts]

I tried it out, and I like it!

Specifically I'm trying to handle the situation where the network connection is interrupted. This especially can happen often in corporate environments with VPNs. Without any handling, interrupted connections with Nuxt 3 result in a fatal error that is non-recoverable, i.e. any subsequent clicks when the connection is restored won't do anything. This is because of chunk loading errors. The user will not see this, but simply notice that interacting with the website is impossible. This is difficult because throwing an error will result in an error, due to Nuxt not being able to dynamically load the error component. I simulate this behavior by setting the throttling to "No connection" in the network tab in Chrome developer tools.

1. The behavior is different in dev vs production. In the above scenario the chunkError hook doesn't seem to be called in dev.
2. The hook will trigger in the production build, but now I encounter the problem that the hook is already called during prefetching. Ideally it would be possible to discard prefetch situations, or at least add the trigger to the error context, so that errors can be handled differently for prefetching vs regular navigation.

[danielroe]

@mcrapts Would you explain more about this:

The hook will trigger in the production build, but now I encounter the problem that the hook is already called during prefetching. Ideally it would be possible to discard prefetch situations, or at least add the trigger to the error context, so that errors can be handled differently for prefetching vs regular navigation.

The reload strategy currently does not handle prefetch errors, so I take it you mean that it would be helpful to have more information in the app:chunkError hook about the situation that caused the chunk error?

[mcrapts]

@mcrapts Would you explain more about this:

The hook will trigger in the production build, but now I encounter the problem that the hook is already called during prefetching. Ideally it would be possible to discard prefetch situations, or at least add the trigger to the error context, so that errors can be handled differently for prefetching vs regular navigation.

The reload strategy currently does not handle prefetch errors, so I take it you mean that it would be helpful to have more information in the app:chunkError hook about the situation that caused the chunk error?

Yes, exactly. Then I can differentiate between prefetch and navigation errors. Navigation errors are more critical and I want to handle them differently.

[danielroe]

Interesting idea. Currently we get that information this way in the reload strategy:

export default defineNuxtPlugin((nuxtApp) => {
  const router = useRouter()

  const chunkErrors = new Set()

  router.beforeEach(() => { chunkErrors.clear() })
  nuxtApp.hook('app:chunkError', ({ error }) => { chunkErrors.add(error) })

  router.onError((error, to) => {
    if (chunkErrors.has(error)) {
      // it was a navigation error
    }
  })
})

We can't really annotate the error (which is emitted from vite's preload function) without adding runtime code to do so, so that might be a future issue/PR.

[Plinpod]

+1 to adding the ability to suppress chunk errors.

Currently, depending on the caching strategy you have setup, new deployments will break the app until the page cache is cleared. The reason being that the cached pages will try to call JS chunk files that no longer exist. It would be good to simply suppress these errors while the cache is cleared and rebuilt.

Does anyone know of a hacky way to do this before this feature is added?

[sondh0127]

Would it be possible to extract it as a vite plugin for use in vite base SPA applications @danielroe

[danielroe]

Indeed. I've already opened a PR as the first step: vitejs/vite#12084

[edwh]

@danielroe Is there a rationale for only handling errors on the route?

If you're using async components then you'll hit missing chunks when deploying on something like Netlify, where the old chunks are gone.

Would the solution to that be to always reload when you hit a chunk error, along the lines of:

import { joinURL } from 'ufo'
import { defineNuxtPlugin, useRuntimeConfig } from '#app/nuxt'
import { reloadNuxtApp } from '#app/composables/chunk'

export default defineNuxtPlugin({
  name: 'nuxt:chunk-reload',
  setup (nuxtApp) {
    const config = useRuntimeConfig()

    nuxtApp.hook('app:chunkError', ({ error }) => { 
        const isHash = 'href' in to && (to.href as string).startsWith('#')
        const path = isHash ? config.app.baseURL + (to as any).href : joinURL(config.app.baseURL, to.fullPath)
        reloadNuxtApp({ path, persistState: true })
    })
  }
})

I've not tested this - I'm wondering if I'm missing something Very Bad that might happen.

[danielroe]

No, I think that should be a reasonable approach 👍

[edwh]

@danielroe Thanks. I need to get the current path, which I can't get from to in the chunkError hook. I tried using useRoute so that I could access route.path, but that is returning undefined. Would you expect that to work?

import * as Sentry from '@sentry/browser'
import { useRoute } from 'vue-router'
import { defineNuxtPlugin } from '#app/nuxt'
import { reloadNuxtApp } from '#app/composables/chunk'

export default defineNuxtPlugin({
  setup(nuxtApp) {
    nuxtApp.hook('app:chunkError', ({ error }) => {
      const route = useRoute()

      Sentry.captureMessage(
        'Caught chunk error in ' +
          route?.path +
          ', will reload: ' +
          JSON.stringify(error)
      )

      reloadNuxtApp({
        path: route?.path ? '/' : route.path,
        persistState: true,
      })
    })
  },
})

[danielroe]

Try getting the route outside the hook - i.e. in the body of the plugin? You can also directly use window.location.

[edwh]

@danielroe Thanks, I think that now works. But I think we might be able to do better, at least on Netlify. I've opened a separate issue #20950.