Skip to content

feat: add error code documentation routing #2219

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

Open
danielroe wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: add error code documentation routing #2219

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b469918
feat: add redirects for nuxt error documentation
danielroe Mar 27, 2026
4f467fc
fix: use flat branch name to avoid isomorphic-git ref parsing issue
danielroe Mar 27, 2026
397f8ba
fix: lowercase error codes in redirects to match content collection p…
danielroe Mar 27, 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
2 changes: 1 addition & 1 deletion app/pages/docs/[...slug].vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ watch(page, (page) => {
}, { immediate: true })

// Get the -2 item of the breadcrumb
const currentSectionTitle = computed(() => headerLinks.value[0].children.find(link => path.value.includes(link.to))?.label || findPageBreadcrumb(navigation.value, path.value).slice(-1)[0].title)
const currentSectionTitle = computed(() => headerLinks.value[0].children.find(link => path.value.includes(link.to))?.label || findPageBreadcrumb(navigation.value, path.value).slice(-1)[0]?.title || page.value?.title)

const breadcrumb = computed(() => {
const links = mapContentNavigation(findPageBreadcrumb(navigation.value, path.value)).map(link => ({
Expand Down
3 changes: 2 additions & 1 deletion content.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ const docsV3Source = {

const docsV4Source = {
cwd: process.env.NUXT_V4_PATH ?? undefined,
repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/4.x' : undefined,
// TODO: revert to 4.x branch before merging
repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/feat/error-context' : undefined,
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 27, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Avoid shipping a feature-branch fallback for v4 docs source.

Line 14 points to feat/error-context, and with default envs this becomes the effective source. That’s risky for merge/release because it can drift or break when the feature branch changes. Please revert the fallback to 4.x before merge (or gate preview branch selection behind an explicit env var).

Suggested fix 
 const docsV4Source = {
   cwd: process.env.NUXT_V4_PATH ?? undefined,
-  // TODO: revert to 4.x branch before merging
-  repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/feat/error-context' : undefined,
+  repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/4.x' : undefined,
   include: 'docs/**/*',
   exclude: ['docs/**/*.json'],
   prefix: '/docs/4.x'
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// TODO: revert to 4.x branch before merging
repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/feat/error-context' : undefined,
const docsV4Source = {
cwd: process.env.NUXT_V4_PATH ?? undefined,
repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/4.x' : undefined,
include: 'docs/**/*',
exclude: ['docs/**/*.json'],
prefix: '/docs/4.x'
}
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@content.config.ts` around lines 13 - 14, The repo fallback currently points
to the feature branch 'https://github.com/nuxt/nuxt/tree/feat/error-context'
when process.env.NUXT_V4_PATH is not set; change this so the default does not
reference a feature branch by replacing that URL with the stable
'https://github.com/nuxt/nuxt/tree/4.x' (or set repository to undefined and
require an explicit env var to opt into the feature branch), updating the
`repository` assignment that references process.env.NUXT_V4_PATH to ensure
previews are only selected via an explicit environment variable rather than
defaulting to the feat/error-context branch.

include: 'docs/**/*',
exclude: ['docs/**/*.json'],
prefix: '/docs/4.x'
Expand Down
1 change: 1 addition & 0 deletions nuxt.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ export default defineNuxtConfig({
'/docs/3.x/getting-started/introduction': { prerender: true },
'/docs/4.x/getting-started/introduction': { prerender: true },
'/docs/5.x/getting-started/introduction': { prerender: true },
'/docs/4.x/errors': { prerender: true },
'/modules': { prerender: true },
'/modules/**': { isr: 60 * 60 },
'/changelog': { isr: 60 * 60 },
Expand Down
17 changes: 17 additions & 0 deletions server/middleware/error-docs-redirect.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
/**
* Redirect unversioned error doc paths to the current default version.
*
* The Nuxt runtime links to https://nuxt.com/docs/errors/E1001 (unversioned).
* This middleware redirects those paths to the current default docs version
* (e.g., /docs/4.x/errors/E1001) so the content can be resolved.
*/
export default defineEventHandler((event) => {
const path = getRequestURL(event).pathname

// Match /docs/errors/... but NOT /docs/3.x/errors/... or /docs/4.x/errors/...
const match = path.match(/^\/docs\/errors\/(.+)$/)
if (match) {
// TODO: update to /docs/5.x when Nuxt 5 is the default
return sendRedirect(event, `/docs/4.x/errors/${match[1]}`, 302)
}
})
24 changes: 24 additions & 0 deletions server/routes/e/[code].get.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
/**
* Short URL handler for Nuxt error codes.
*
* Redirects /e/NUXT_E1001 → /docs/4.x/errors/E1001
* Redirects /e/NUXT_B1001 → /docs/4.x/errors/B1001
*
* The error code format is NUXT_ followed by E or B and 1-4 digits.
* The NUXT_ prefix is stripped and the user is redirected to the
* current default docs version.
*/
export default defineEventHandler((event) => {
const code = getRouterParam(event, 'code')

// Validate: must be NUXT_ followed by E or B and 1-4 digits
if (!code || !/^NUXT_[EB]\d{1,4}$/.test(code)) {
throw createError({ statusCode: 404, statusMessage: 'Not found' })
}

// Strip the NUXT_ prefix → E1001 or B1001
const errorCode = code.replace('NUXT_', '')

// TODO: update to /docs/5.x when Nuxt 5 is the default
return sendRedirect(event, `/docs/4.x/errors/${errorCode}`, 302)
})
Loading