feat(nuxt): improve error dx for users

[danielroe]

🔗 Linked issue

nuxt/nuxt#13788, resolves nuxt/nuxt#13950

❓ 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 improves the error experience for users:

1. fixes an issue where users who manually throw 404s can't escape from the error page (by clearing error after navigating to new route)
2. renames throwError to showError and allows graceful fallback when nuxt context is not available
3. allows showError to accept createError params for better dx
4. allows directly throwing errors created with createError within the Vue lifecycle. (👈 This is now the recommended approach.) This is similar to using createError in server api routes. On server side these will lead to a full page error, but on client can be handled with error boundaries, onErrorCaptured, and so on.

📝 Checklist

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

[netlify]

✅ Deploy Preview for nuxt3-docs ready!

Name	Link
🔨 Latest commit	444a59c
🔍 Latest deploy log	https://app.netlify.com/sites/nuxt3-docs/deploys/62d9626eb722600008c0c478
😎 Deploy Preview	https://deploy-preview-4539--nuxt3-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[pi0]

Currently, throwError() and throw createError() are behaving the same by showing a full-screen error page. I'm thinking following adjustments before adding:

• throw createError()
  • Server-side: Full error page
  • Client-side: Let the caller scope gracefully handles (*)
  • Document and recommend since has the benefit of bubbling up from function/composable to their parent for controlled handling
• throwError()
  • Server and Client: Show full error page
  • Adds a prop to NuxtError (userError: true or fullpageError: true, or ..) to distingoush
  • Possibly deprecate and rename to a more semantic showError function
  • Document the behavior and recommend to only use for critical errors

(*) Graceful client handling: Showing full-error page for Client-Side, is really unnecessary in many cases. For example, when a refresh button fails, we can avoid bailing the whole application into an error state. Using Error boundary is probably best but it is harder to use.

[Aareksio]

🔥