Router API types

[ravinggenius]

Goals

1. Provide canonical types for app router objects (layout, template, page et cetera)

Non-Goals

1. Provide types for pages router objects

Background

I want to have accurate types for the "conventional files" used by the App Router. When creating a new page for instance, the editor doesn't know what type the page component props are. It types params as any. Next does export some relevant types, such as Metadata and NextRequest. Recently I discovered that Params and SearchParams are technically available, but only from next/dist/server/request/params and next/dist/server/request/search-params respectively. These are accurate according to the description in the docs, but using them feels wrong.

As a work-around I've been defining the types (as described by the docs) and maintaining them as part of my project. However when Next 15 was released, I had to update the types to account for the new async API.

Proposal

Below are the types I define for my project. It would be much more convenient to import them directly from Next, where they would be available for everyone. I'm happy to provide a patch if there is any interest for it.

1. Are these types accurate? I think they are, but I could have missed something.
2. If a patch is desired, where in the project source should it live? I was thinking exporting from next/app-router might be good, but perhaps another source is preferred?

(Params and SearchParams should be properly exported too.)

import { Metadata } from "next";
import { Params } from "next/dist/server/request/params";
import { SearchParams } from "next/dist/server/request/search-params";
import { NextRequest } from "next/server";
import { ReactNode } from "react";

export interface DefaultProps {
	params?: Promise<Params>;
}

export interface ErrorProps {
	error: Error & { digest?: string };
	reset: () => void;
}

export interface LayoutProps {
	children: ReactNode;
	params?: Promise<Params>;
}

export type LayoutGenerateMetadata = (
	props: Pick<LayoutProps, "params">
) => Metadata | Promise<Metadata>;

export interface TemplateProps {
	children: ReactNode;
}

export interface PageProps {
	params?: Promise<Params>;
	searchParams?: Promise<SearchParams>;
}

export type PageGenerateMetadata = (
	props: PageProps
) => Metadata | Promise<Metadata>;

export interface RouteContext {
	params: Promise<Params>;
}

export type RouteMethod = (
	request: NextRequest,
	context: RouteContext
) => Response | Promise<Response>;

[ravinggenius]

I guess there's less of an appetite for this than I thought. Would a merge request be welcome? I'm happy to do the work if there is interest. (I mean it's basically done already.)

[icyJoseph]

We now have this feature built in: https://nextjs.org/blog/next-15-5#route-props-helpers :) give it a go!

[ravinggenius]

Thanks @icyJoseph; I saw that earlier today! I wasn't expecting LayoutProps, PageProps and RouteContext to be generic, but I appreciate it. My app uses some helper functions to verify params and searchParams with zod, so the generic type arguments are a bit verbose. It would be nice if the build process at least verified the expected type argument is used.

My app doesn't use DefaultProps, ErrorProps or TemplateProps yet, so I don't know if those would be generated with this change or not.

It's a little unfortunate that we didn't get LayoutGenerateMetadata, PageGenerateMetadata or RouteMethod. Having those assigned to their respective exported symbols would have been nice. Of course they should have appropriate type parameters to pass on to LayoutProps, PageProps and RouteContext respectively.