From 4be52d341f5f6dacd8056e4a2407986bcc596234 Mon Sep 17 00:00:00 2001
From: Alex Liu <dsa1314@gmail.com>
Date: Fri, 7 Feb 2025 00:46:15 +0800
Subject: [PATCH] feat(nuxt): add type hints for `NuxtPage` (#30704)

---
 packages/nuxt/src/app/index.ts           |  2 +-
 packages/nuxt/src/app/types.ts           |  2 +-
 packages/nuxt/src/pages/runtime/index.ts |  1 +
 packages/nuxt/src/pages/runtime/page.ts  | 40 ++++++++++++++++++++++--
 4 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/packages/nuxt/src/app/index.ts b/packages/nuxt/src/app/index.ts
index 9935ab9f75..2dd13243b8 100644
--- a/packages/nuxt/src/app/index.ts
+++ b/packages/nuxt/src/app/index.ts
@@ -8,7 +8,7 @@ export { defineNuxtLink } from './components/index'
 export type { NuxtLinkOptions, NuxtLinkProps } from './components/index'
 export { _getAppConfig, updateAppConfig, useAppConfig } from './config'
 export { cancelIdleCallback, requestIdleCallback } from './compat/idle-callback'
-export type { NuxtAppLiterals, NuxtIslandContext, NuxtIslandResponse, NuxtRenderHTMLContext, PageMeta } from './types'
+export type { NuxtAppLiterals, NuxtIslandContext, NuxtIslandResponse, NuxtRenderHTMLContext, PageMeta, NuxtPageProps } from './types'
 
 export const isVue2 = false
 export const isVue3 = true
diff --git a/packages/nuxt/src/app/types.ts b/packages/nuxt/src/app/types.ts
index 795e92384e..54bfe868de 100644
--- a/packages/nuxt/src/app/types.ts
+++ b/packages/nuxt/src/app/types.ts
@@ -1,4 +1,4 @@
-export type { PageMeta } from '../pages/runtime/index'
+export type { PageMeta, NuxtPageProps } from '../pages/runtime/index'
 
 export interface NuxtAppLiterals {
   [key: string]: string
diff --git a/packages/nuxt/src/pages/runtime/index.ts b/packages/nuxt/src/pages/runtime/index.ts
index 2a46da204f..2160084dae 100644
--- a/packages/nuxt/src/pages/runtime/index.ts
+++ b/packages/nuxt/src/pages/runtime/index.ts
@@ -1,2 +1,3 @@
 export { definePageMeta, defineRouteRules } from './composables'
 export type { PageMeta } from './composables'
+export type { NuxtPageProps } from './page'
diff --git a/packages/nuxt/src/pages/runtime/page.ts b/packages/nuxt/src/pages/runtime/page.ts
index 9deebfdf22..3d52ab622b 100644
--- a/packages/nuxt/src/pages/runtime/page.ts
+++ b/packages/nuxt/src/pages/runtime/page.ts
@@ -1,8 +1,8 @@
 import { Fragment, Suspense, defineComponent, h, inject, nextTick, ref, watch } from 'vue'
-import type { KeepAliveProps, TransitionProps, VNode } from 'vue'
+import type { AllowedComponentProps, ComponentCustomProps, ComponentPublicInstance, KeepAliveProps, TransitionProps, VNode, VNodeProps } from 'vue'
 import { RouterView } from 'vue-router'
 import { defu } from 'defu'
-import type { RouteLocationNormalized, RouteLocationNormalizedLoaded } from 'vue-router'
+import type { RouteLocationNormalized, RouteLocationNormalizedLoaded, RouterViewProps } from 'vue-router'
 
 import { generateRouteKey, toArray, wrapInKeepAlive } from './utils'
 import type { RouterViewSlotProps } from './utils'
@@ -14,6 +14,23 @@ import { LayoutMetaSymbol, PageRouteSymbol } from '#app/components/injections'
 // @ts-expect-error virtual file
 import { appKeepalive as defaultKeepaliveConfig, appPageTransition as defaultPageTransition } from '#build/nuxt.config.mjs'
 
+export interface NuxtPageProps extends RouterViewProps {
+  /**
+   * Define global transitions for all pages rendered with the `NuxtPage` component.
+   */
+  transition?: boolean | TransitionProps
+
+  /**
+   * Control state preservation of pages rendered with the `NuxtPage` component.
+   */
+  keepalive?: boolean | KeepAliveProps
+
+  /**
+   * Control when the `NuxtPage` component is re-rendered.
+   */
+  pageKey?: string | ((route: RouteLocationNormalizedLoaded) => string)
+}
+
 export default defineComponent({
   name: 'NuxtPage',
   inheritAttrs: false,
@@ -169,7 +186,24 @@ export default defineComponent({
       })
     }
   },
-})
+}) as unknown as {
+  new(): {
+    $props: AllowedComponentProps &
+      ComponentCustomProps &
+      VNodeProps &
+      NuxtPageProps
+
+    $slots: {
+      default?: (routeProps: RouterViewSlotProps) => VNode[]
+    }
+
+    // expose
+    /**
+     * Reference to the page component instance
+     */
+    pageRef: Element | ComponentPublicInstance | null
+  }
+}
 
 function _mergeTransitionProps (routeProps: TransitionProps[]): TransitionProps {
   const _props: TransitionProps[] = routeProps.map(prop => ({