add useRouter from next/navigation (#201)

Author: tatethurston

CHANGELOG.md

@@ -17,13 +17,21 @@
   </Link>;
   ```
 
-- Add `RouteLiteral` type. This type represents a string that confirmed to be a validated application route and can be passed to `Link` or `useRouter`. This is a TypeScript branded type.
+- Add `RouteLiteral` type. This type represents a string that has been confirmed to be a validated application route and can be passed to `Link` or `useRouter`. This is a TypeScript branded type.
 
   ```ts
   import { RouteLiteral } from "nextjs-routes";
   ```
 
-- Refine types for `usePathname` and `useParams` from `"next/navigation"` to use `nextjs-routes` generated types.
+  `route` returns a `RouteLiteral`. If you construct a route string you can cast it to a `RouteLiteral` so that `Link` and `useRouter` will accept it:
+
+  ```
+  const myRoute = `/foos/${foo}` as RouteLiteral
+  ```
+
+  In general, prefer using the `route` helper to generate routes.
+
+- Refine types for `usePathname`, `useRouter` and `useParams` from `"next/navigation"` to use `nextjs-routes` generated types.
 
 - Fix generated routes when using [parallel-routes](https://nextjs.org/docs/app/building-your-application/routing/parallel-routes) and [intercepting-routes](https://nextjs.org/docs/app/building-your-application/routing/intercepting-routes).
 

examples/app/@types/nextjs-routes.d.ts

@@ -30,7 +30,7 @@ declare module "nextjs-routes" {
     [key: string]: string | string[] | undefined;
   };
 
-  export type RoutedQuery<P extends Route["pathname"]> = Extract<
+  export type RoutedQuery<P extends Route["pathname"] = Route["pathname"]> = Extract<
     Route,
     { pathname: P }
   >["query"];
@@ -170,7 +170,10 @@ declare module "next/router" {
 // prettier-ignore
 declare module "next/navigation" {
   export * from "next/dist/client/components/navigation";
-  import type { RoutedQuery, RouteLiteral } from "nextjs-routes";
+  import type { Route, RouteLiteral, RoutedQuery } from "nextjs-routes";
+  import type { AppRouterInstance as NextAppRouterInstance, NavigateOptions, PrefetchOptions } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+  type StaticRoute = Exclude<Route, { query: any }>["pathname"];
 
   /**
    * A [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) hook
@@ -189,7 +192,33 @@ declare module "next/navigation" {
    *
    * Read more: [Next.js Docs: `usePathname`](https://nextjs.org/docs/app/api-reference/functions/use-pathname)
    */
-  export function usePathname(): RouteLiteral;
+  export const usePathname = () => RouteLiteral;
+
+  type AppRouterInstance = Omit<NextAppRouterInstance, 'push' | 'replace' | 'href'> & {
+    push(href: StaticRoute | RouteLiteral, options?: NavigateOptions): void;
+    replace(href: StaticRoute | RouteLiteral, options?: NavigateOptions): void;
+    prefetch(href: StaticRoute | RouteLiteral, options?: PrefetchOptions): void;
+  }
+
+  /**
+   *
+   * This hook allows you to programmatically change routes inside [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components).
+   *
+   * @example
+   * ```ts
+   * "use client"
+   * import { useRouter } from 'next/navigation'
+   *
+   * export default function Page() {
+   *  const router = useRouter()
+   *  // ...
+   *  router.push('/dashboard') // Navigate to /dashboard
+   * }
+   * ```
+   *
+   * Read more: [Next.js Docs: `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router)
+   */
+  export function useRouter(): AppRouterInstance;
 
   /**
    * A [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) hook
@@ -208,5 +237,5 @@ declare module "next/navigation" {
    *
    * Read more: [Next.js Docs: `useParams`](https://nextjs.org/docs/app/api-reference/functions/use-params)
    */
-  export function useParams<Pathname extends Route["pathname"] = Route["pathname"]>(): RoutedQuery<Pathname>;
+  export const useParams = <Pathname extends Route["pathname"] = Route["pathname"]>() => RoutedQuery<Pathname>;
 }

examples/app/src/app/client.tsx

@@ -9,7 +9,7 @@ export default function Client() {
   const router = useRouter();
 
   return (
-    <button type="button" onClick={() => router.push("/tate")}>
+    <button type="button" onClick={() => router.push("/")}>
       Dashboard
     </button>
   );

examples/cjs/types/nextjs-routes.d.ts

@@ -30,7 +30,7 @@ declare module "nextjs-routes" {
     [key: string]: string | string[] | undefined;
   };
 
-  export type RoutedQuery<P extends Route["pathname"]> = Extract<
+  export type RoutedQuery<P extends Route["pathname"] = Route["pathname"]> = Extract<
     Route,
     { pathname: P }
   >["query"];

examples/intl/@types/nextjs-routes.d.ts

@@ -30,7 +30,7 @@ declare module "nextjs-routes" {
     [key: string]: string | string[] | undefined;
   };
 
-  export type RoutedQuery<P extends Route["pathname"]> = Extract<
+  export type RoutedQuery<P extends Route["pathname"] = Route["pathname"]> = Extract<
     Route,
     { pathname: P }
   >["query"];

examples/typescript/types/nextjs-routes.d.ts

@@ -32,7 +32,7 @@ declare module "nextjs-routes" {
     [key: string]: string | string[] | undefined;
   };
 
-  export type RoutedQuery<P extends Route["pathname"]> = Extract<
+  export type RoutedQuery<P extends Route["pathname"] = Route["pathname"]> = Extract<
     Route,
     { pathname: P }
   >["query"];

packages/e2e/@types/nextjs-routes.d.ts

@@ -13,6 +13,7 @@ declare module "nextjs-routes" {
   export type Route =
     | StaticRoute<"/">
     | DynamicRoute<"/[...slug]", { "slug": string[] }>
+    | DynamicRoute<"/bars/[bar]", { "bar": string }>
     | DynamicRoute<"/foos/[foo]", { "foo": string }>;
 
   interface StaticRoute<Pathname> {
@@ -31,7 +32,7 @@ declare module "nextjs-routes" {
     [key: string]: string | string[] | undefined;
   };
 
-  export type RoutedQuery<P extends Route["pathname"]> = Extract<
+  export type RoutedQuery<P extends Route["pathname"] = Route["pathname"]> = Extract<
     Route,
     { pathname: P }
   >["query"];
@@ -82,14 +83,14 @@ declare module "nextjs-routes" {
 
 // prettier-ignore
 declare module "next/link" {
-  import type { Route } from "nextjs-routes";;
+  import type { Route, RouteLiteral } from "nextjs-routes";;
   import type { LinkProps as NextLinkProps } from "next/dist/client/link";
   import type React from "react";
 
   type StaticRoute = Exclude<Route, { query: any }>["pathname"];
 
   export type LinkProps = Omit<NextLinkProps, "href" | "locale"> & {
-    href: Route | StaticRoute | Omit<Route, "pathname">;
+    href: Route | StaticRoute | Omit<Route, "pathname"> | RouteLiteral;
     locale?: false;
   }
 
@@ -167,3 +168,76 @@ declare module "next/router" {
 
   export function useRouter<P extends Route["pathname"]>(): NextRouter<P>;
 }
+
+// prettier-ignore
+declare module "next/navigation" {
+  export * from "next/dist/client/components/navigation";
+  import type { Route, RouteLiteral, RoutedQuery } from "nextjs-routes";
+  import type { AppRouterInstance as NextAppRouterInstance, NavigateOptions, PrefetchOptions } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+  type StaticRoute = Exclude<Route, { query: any }>["pathname"];
+
+  /**
+   * A [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) hook
+   * that lets you read the current URL's pathname.
+   *
+   * @example
+   * ```ts
+   * "use client"
+   * import { usePathname } from 'next/navigation'
+   *
+   * export default function Page() {
+   *  const pathname = usePathname() // returns "/dashboard" on /dashboard?foo=bar
+   *  // ...
+   * }
+   * ```
+   *
+   * Read more: [Next.js Docs: `usePathname`](https://nextjs.org/docs/app/api-reference/functions/use-pathname)
+   */
+  export const usePathname = () => RouteLiteral;
+
+  type AppRouterInstance = Omit<NextAppRouterInstance, 'push' | 'replace' | 'href'> & {
+    push(href: StaticRoute | RouteLiteral, options?: NavigateOptions): void;
+    replace(href: StaticRoute | RouteLiteral, options?: NavigateOptions): void;
+    prefetch(href: StaticRoute | RouteLiteral, options?: PrefetchOptions): void;
+  }
+
+  /**
+   *
+   * This hook allows you to programmatically change routes inside [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components).
+   *
+   * @example
+   * ```ts
+   * "use client"
+   * import { useRouter } from 'next/navigation'
+   *
+   * export default function Page() {
+   *  const router = useRouter()
+   *  // ...
+   *  router.push('/dashboard') // Navigate to /dashboard
+   * }
+   * ```
+   *
+   * Read more: [Next.js Docs: `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router)
+   */
+  export function useRouter(): AppRouterInstance;
+
+  /**
+   * A [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) hook
+   * that lets you read a route's dynamic params filled in by the current URL.
+   *
+   * @example
+   * ```ts
+   * "use client"
+   * import { useParams } from 'next/navigation'
+   *
+   * export default function Page() {
+   *   // on /dashboard/[team] where pathname is /dashboard/nextjs
+   *   const { team } = useParams() // team === "nextjs"
+   * }
+   * ```
+   *
+   * Read more: [Next.js Docs: `useParams`](https://nextjs.org/docs/app/api-reference/functions/use-params)
+   */
+  export const useParams = <Pathname extends Route["pathname"] = Route["pathname"]>() => RoutedQuery<Pathname>;
+}

packages/e2e/app/bars/[bar]/page.tsx

@@ -0,0 +1 @@
+export default () => <div>Bar</div>;

packages/e2e/app/layout.tsx

@@ -0,0 +1,12 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html>
+      <head />
+      <body>{children}</body>
+    </html>
+  );
+}

packages/e2e/next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.