Unverified Commit b58d9840 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

Allow `unstable_retry` from TS plugin check in Next.js Error APIs (#94460)

### What?

Stop the Next.js TypeScript plugin from flagging the framework-injected
`unstable_retry` prop in `error.tsx` and `global-error.tsx` with error
`71007` (`INVALID_CLIENT_ENTRY_PROP`). The plugin already exempts
`reset`; this extends that exemption to `unstable_retry`.

### Why?

`unstable_retry` is injected by the framework into error boundaries: it
is part of the `ErrorInfo` type (`error`, `reset`, `unstable_retry`) in
`packages/next/src/client/components/error-boundary.tsx` and is passed
to the user's error component, not supplied by the user. Like `reset`,
it therefore does not need to be serializable.

The file-convention docs
(`docs/01-app/03-api-reference/03-file-conventions/error.mdx`) document
`unstable_retry` as an error-component prop (added in `v16.2.0`) and
recommend it over `reset`. The exact documented pattern, `export default
function Error({ error, unstable_retry })`, was being false-flagged by
the plugin, so a user copying the docs would hit a spurious diagnostic.

<img width="2930" height="1110" alt="image"
src="https://github.com/user-attachments/assets/7c7efefe-f9df-448a-9fd6-218c51bc8bd1"
/>

### How?

Extend the existing error-file `reset` exemption in
`packages/next/src/server/typescript/rules/client-boundary.ts` to also
allow `unstable_retry`. The exemption stays scoped to those two prop
names in `error` / `global-error` files; every other non-serializable
function prop is still flagged.

Add regression tests for both `error.tsx` and `global-error.tsx`, each
with a `_notExempt` negative control that confirms the exemption stays
scoped (an ordinary function prop is still flagged). Update the manual
VSCode fixtures and the test README to match.

### Verification

- `pnpm test-dev-turbo
test/development/typescript-plugin/client-boundary/client-boundary.test.ts`
(5/5 passed; the harness loads the compiled plugin from `dist`, so green
also confirms the build reflects the change)
- `pnpm --filter=next types` (passed)
- `pnpm --filter=next build` (passed)
- `pnpm typescript` root `tsc` for the changed test files (passed)
- Not run: full CI suite (will run on the PR)

<!-- NEXT_JS_LLM_PR -->
parent 42987701
...@@ -75,13 +75,17 @@ const clientBoundary = { ...@@ -75,13 +75,17 @@ const clientBoundary = {
const maybeServerAction = const maybeServerAction =
propName === 'action' || /.+Action$/.test(propName) propName === 'action' || /.+Action$/.test(propName)
// There's a special case for the error file that the `reset` prop // There's a special case for error files where the
// is allowed to be a function: // framework-injected `reset` and `unstable_retry` props are
// allowed to be functions. Next.js provides these props, the
// user doesn't pass them, so they don't need to be
// serializable.
// https://github.com/vercel/next.js/issues/46573 // https://github.com/vercel/next.js/issues/46573
const isErrorReset = const isErrorBoundaryFunctionProp =
(isErrorFile || isGlobalErrorFile) && propName === 'reset' (isErrorFile || isGlobalErrorFile) &&
(propName === 'reset' || propName === 'unstable_retry')
if (!maybeServerAction && !isErrorReset) { if (!maybeServerAction && !isErrorBoundaryFunctionProp) {
diagnostics.push({ diagnostics.push({
file: source, file: source,
category: ts.DiagnosticCategory.Warning, category: ts.DiagnosticCategory.Warning,
......
...@@ -16,8 +16,8 @@ The plugin only applies to VSCode so manual testing in VSCode is required. ...@@ -16,8 +16,8 @@ The plugin only applies to VSCode so manual testing in VSCode is required.
`app/client.tsx#ClientComponent` has props that can and can't be serialized. `app/client.tsx#ClientComponent` has props that can and can't be serialized.
Ensure the current comments still describe the observed behavior. Ensure the current comments still describe the observed behavior.
`app/error.tsx#Error` and `app/global-error.tsx#GlobalError` have a `reset` prop `app/error.tsx#Error` and `app/global-error.tsx#GlobalError` have `reset` and
that should be excluded from the serialization check. `unstable_retry` props that should be excluded from the serialization check.
### Client Boundary ### Client Boundary
......
...@@ -5,10 +5,13 @@ import { useEffect } from 'react' ...@@ -5,10 +5,13 @@ import { useEffect } from 'react'
export default function Error({ export default function Error({
error, error,
reset, reset,
//^^^ fine because it's the special reset prop in an error file unstable_retry,
//^^^ `reset` and `unstable_retry` are fine because they are the special
// framework-injected function props in an error file
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void reset: () => void
unstable_retry: () => void
}) { }) {
useEffect(() => { useEffect(() => {
console.error(error) console.error(error)
...@@ -18,6 +21,7 @@ export default function Error({ ...@@ -18,6 +21,7 @@ export default function Error({
<div> <div>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Retry</button>
</div> </div>
) )
} }
...@@ -3,16 +3,20 @@ ...@@ -3,16 +3,20 @@
export default function GlobalError({ export default function GlobalError({
error, error,
reset, reset,
//^^^ fine because it's the special reset prop in a global-error file unstable_retry,
//^^^ `reset` and `unstable_retry` are fine because they are the special
// framework-injected function props in a global-error file
}: { }: {
error: Error & { digest?: string } error: Error & { digest?: string }
reset: () => void reset: () => void
unstable_retry: () => void
}) { }) {
return ( return (
<html> <html>
<body> <body>
<h2>Something went wrong!</h2> <h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button> <button onClick={() => reset()}>Try again</button>
<button onClick={() => unstable_retry()}>Retry</button>
</body> </body>
</html> </html>
) )
......
'use client'
// Error boundaries receive `error`, `reset`, and `unstable_retry` from the
// framework. `reset` and `unstable_retry` are functions, but they are injected
// by Next.js rather than passed by the user, so the client-entry serialization
// rule must not flag them. `_notExempt` is an ordinary function prop and
// must still be flagged, proving the exemption stays scoped to error-boundary
// props.
export default function Error({
error,
reset,
unstable_retry,
_notExempt,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
_notExempt: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Reset</button>
<button onClick={() => unstable_retry()}>Try again</button>
<button onClick={() => _notExempt()}>Nope</button>
</div>
)
}
'use client'
// `global-error.tsx` receives the same framework-injected props as `error.tsx`.
// Its function props (`reset`, `unstable_retry`) are provided by Next.js and
// must not be flagged as non-serializable. `_notExempt` is an ordinary function
// prop and must still be flagged, proving the exemption stays scoped to known
// error-boundary props.
export default function GlobalError({
error,
reset,
unstable_retry,
_notExempt,
}: {
error: Error & { digest?: string }
reset: () => void
unstable_retry: () => void
_notExempt: () => void
}) {
return (
<html>
<body>
<h2>Something went wrong!</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Reset</button>
<button onClick={() => unstable_retry()}>Try again</button>
<button onClick={() => _notExempt()}>Nope</button>
</body>
</html>
)
}
...@@ -2,7 +2,7 @@ import type { PluginLanguageService } from '../test-utils' ...@@ -2,7 +2,7 @@ import type { PluginLanguageService } from '../test-utils'
import ts from 'typescript' import ts from 'typescript'
import { relative, resolve } from 'node:path' import { relative, resolve } from 'node:path'
import { getPluginLanguageService } from '../test-utils' import { getPluginLanguageService, NEXT_TS_ERRORS } from '../test-utils'
type PartialDiagnostic = Pick< type PartialDiagnostic = Pick<
ts.Diagnostic, ts.Diagnostic,
...@@ -118,4 +118,46 @@ describe('typescript-plugin - client-boundary', () => { ...@@ -118,4 +118,46 @@ describe('typescript-plugin - client-boundary', () => {
} }
`) `)
}) })
it('should not flag framework-injected function props in error files', () => {
const tsFile = resolve(__dirname, 'app/error.tsx')
const flaggedProps = languageService
.getSemanticDiagnostics(tsFile)
.filter(
(diagnostic) =>
diagnostic.code === NEXT_TS_ERRORS.INVALID_CLIENT_ENTRY_PROP
)
.map((diagnostic) => String(diagnostic.messageText))
// `reset` and `unstable_retry` are injected by Next.js into error
// boundaries, so they must not be flagged as non-serializable props.
expect(flaggedProps.some((m) => m.includes('"reset"'))).toBe(false)
expect(flaggedProps.some((m) => m.includes('"unstable_retry"'))).toBe(false)
// The exemption stays scoped to known error-boundary props: an ordinary
// function prop in an error file is still flagged.
expect(flaggedProps.some((m) => m.includes('"_notExempt"'))).toBe(true)
expect(flaggedProps).toHaveLength(1)
})
it('should not flag framework-injected function props in global-error files', () => {
const tsFile = resolve(__dirname, 'app/global-error.tsx')
const flaggedProps = languageService
.getSemanticDiagnostics(tsFile)
.filter(
(diagnostic) =>
diagnostic.code === NEXT_TS_ERRORS.INVALID_CLIENT_ENTRY_PROP
)
.map((diagnostic) => String(diagnostic.messageText))
// `reset` and `unstable_retry` are injected by Next.js into global-error
// boundaries, so they must not be flagged as non-serializable props.
expect(flaggedProps.some((m) => m.includes('"reset"'))).toBe(false)
expect(flaggedProps.some((m) => m.includes('"unstable_retry"'))).toBe(false)
// The exemption stays scoped to known error-boundary props: an ordinary
// function prop in a global-error file is still flagged.
expect(flaggedProps.some((m) => m.includes('"_notExempt"'))).toBe(true)
expect(flaggedProps).toHaveLength(1)
})
}) })
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment