Codemod for Async Request API

docs/02-app/01-building-your-application/11-upgrading/01-codemods.mdx

@@ -26,6 +26,108 @@ Replacing `<transform>` and `<path>` with appropriate values.
 
 ### 15.0
 
+#### Migrate to async Dynamic APIs
+
+##### `next-async-request-api`
+
+```bash filename="Terminal"
+npx @next/codemod@latest next-async-request-api .
+```
+
+This codemod will transform APIs `cookies()`, `headers()` and `draftMode()` from `next/headers` to be properly awaited or wrapped with `React.use()` if needed.
+If it's not able to be migrated, will either add a type cast or a TODO comment based on the file is a TypeScript or JavaScript file.
+
+For example:
+
+```tsx
+import { cookies, headers } from 'next/headers'
+const token = cookies().get('token')
+
+function useToken() {
+  const token = cookies().get('token')
+  return token
+}
+
+export default function Page() {
+  const name = cookies().get('name')
+}
+
+function getHeader() {
+  return headers().get('x-foo')
+}
+```
+
+Transforms into:
+
+```tsx
+import { use } from 'react'
+import { cookies, headers, type UnsafeUnwrappedCookies } from 'next/headers'
+
+const token = (await cookies()).get('token')
+
+function useToken() {
+  const token = use(cookies()).get('token')
+  return token
+}
+
+export default function Page() {
+  const name = (await cookies()).get('name')
+}
+
+function getHeader() {
+  return (headers() as UnsafeUnwrappedCookies).get('x-foo')
+}
+```
+
+If there's access to the entry handler `params` and `searchParams` in the route entry default handler (`page.js`, `layout.js`, `route.js` or Metadata API routes) or `generateMetadata` export API,
+it will transform the access to the property from sync to async, and await or wrap these properties with `React.use()` if needed.
+
+For example:
+
+```tsx
+// page.tsx
+export default function Page({
+  params,
+  searchParams,
+}: {
+  params: { slug: string }
+  searchParams: { [key: string]: string | undefined }
+}) {
+  const { value } = searchParams
+  if (value === 'foo') {
+    // ...
+  }
+}
+
+export function generateMetadata({ params }: { params: { slug: string } }) {
+  return {
+    title: `My Page - ${slug}`,
+  }
+}
+```
+
+Transforms into:
+
+```tsx
+// page.tsx
+export default function Page(props: {
+  params: { slug: string }
+  searchParams: { [key: string]: string | undefined }
+}) {
+  const { value } = await props.searchParams
+  if (value === 'foo') {
+    // ...
+  }
+}
+
+export function generateMetadata(props: { params: { slug: string } }) {
+  const { slug } = await props.params
+  return {
+    title: `My Page - ${slug}`,
+  }
+}
+```
+
 #### Replace `geo` and `ip` properties of `NextRequest` with `@vercel/functions`
 
 ##### `next-request-geo-ip`

packages/next-codemod/bin/cli.ts

@@ -164,6 +164,10 @@ const TRANSFORMER_INQUIRER_CHOICES = [
     name: 'built-in-next-font: Uninstall `@next/font` and transform imports to `next/font`',
     value: 'built-in-next-font',
   },
+  {
+    name: 'next-async-request-api: Transforms usage of Next.js async Request APIs',
+    value: 'next-async-request-api',
+  },
   {
     name: 'next-request-geo-ip: Install `@vercel/functions` to replace `geo` and `ip` properties on `NextRequest`',
     value: 'next-request-geo-ip',

packages/next-codemod/package.json

@@ -19,6 +19,7 @@
   },
   "files": [
     "transforms/*.js",
+    "transforms/lib/**/*.js",
     "bin/*.js",
     "lib/**/*.js",
     "lib/cra-to-next/gitignore"

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-01.input.tsx

@@ -0,0 +1,10 @@
+import { cookies } from 'next/headers'
+
+export async function MyComponent() {
+  const name = cookies().get('name')
+  callback(name)
+}
+
+function callback(name: any) {
+  console.log(name)
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-01.output.tsx

@@ -0,0 +1,10 @@
+import { cookies } from 'next/headers'
+
+export async function MyComponent() {
+  const name = (await cookies()).get('name')
+  callback(name)
+}
+
+function callback(name: any) {
+  console.log(name)
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-02.input.tsx

@@ -0,0 +1,5 @@
+import { draftMode } from 'next/headers'
+
+export async function MyComponent() {
+  draftMode().enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-02.output.tsx

@@ -0,0 +1,5 @@
+import { draftMode } from 'next/headers'
+
+export async function MyComponent() {
+  (await draftMode()).enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-03.input.tsx

@@ -0,0 +1,6 @@
+// If it's sync default export, convert to async and await the function call
+import { draftMode } from 'next/headers'
+
+export default function MyComponent() {
+  draftMode().enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-03.output.tsx

@@ -0,0 +1,6 @@
+// If it's sync default export, convert to async and await the function call
+import { draftMode } from 'next/headers'
+
+export default async function MyComponent() {
+  (await draftMode()).enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-04.input.tsx

@@ -0,0 +1,9 @@
+import { draftMode } from 'next/headers'
+
+export default async function MyComponent() {
+  draftMode().enable()
+}
+
+export async function MyComponent2() {
+  draftMode().enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-04.output.tsx

@@ -0,0 +1,9 @@
+import { draftMode } from 'next/headers'
+
+export default async function MyComponent() {
+  (await draftMode()).enable()
+}
+
+export async function MyComponent2() {
+  (await draftMode()).enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-05.input.tsx

@@ -0,0 +1,9 @@
+import { draftMode } from 'next/headers'
+
+export function MyComponent2() {
+  draftMode().enable()
+}
+
+export function useDraftModeEnabled() {
+  draftMode().enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-05.output.tsx

@@ -0,0 +1,10 @@
+import { use } from "react";
+import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers';
+
+export function MyComponent2() {
+  (draftMode() as unknown as UnsafeUnwrappedDraftMode).enable()
+}
+
+export function useDraftModeEnabled() {
+  use(draftMode()).enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-06.input.tsx

@@ -0,0 +1,6 @@
+import React from 'react'
+import { draftMode } from 'next/headers'
+
+export default function Page() {
+  return <button disabled={draftMode().isEnabled}>Enable Draft Mode</button>
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-06.output.tsx

@@ -0,0 +1,7 @@
+import React from 'react'
+import { draftMode } from 'next/headers'
+
+export default async function Page() {
+  return <button disabled={(await draftMode()).isEnabled}>Enable Draft Mode</button>;
+}
+

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-07.input.tsx

@@ -0,0 +1,6 @@
+// Already imported the type
+import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'
+
+export function MyComponent2() {
+  draftMode().enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-07.output.tsx

@@ -0,0 +1,6 @@
+// Already imported the type
+import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'
+
+export function MyComponent2() {
+  (draftMode() as unknown as UnsafeUnwrappedDraftMode).enable()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-08.input.tsx

@@ -0,0 +1,5 @@
+import { headers } from 'next/headers'
+
+export function GET(): Response {
+  headers()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-08.output.tsx

@@ -0,0 +1,5 @@
+import { headers } from 'next/headers'
+
+export async function GET(): Promise<Response> {
+  await headers()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-09.input.tsx

@@ -0,0 +1,13 @@
+export default function Page({
+  params: { slug },
+  searchParams: { search },
+}: {
+  params: { slug: string }
+  searchParams: any
+}): JSX.Element {
+  // Access to the destructed properties
+  slug
+  search
+
+  return <div>Page</div>
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-09.output.tsx

@@ -0,0 +1,24 @@
+export default async function Page(
+  props: {
+    params: Promise<{ slug: string }>
+    searchParams: Promise<any>
+  }
+): Promise<JSX.Element> {
+  const searchParams = await props.searchParams;
+
+  const {
+    search
+  } = searchParams;
+
+  const params = await props.params;
+
+  const {
+    slug
+  } = params;
+
+  // Access to the destructed properties
+  slug
+  search
+
+  return <div>Page</div>
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-10.input.tsx

@@ -0,0 +1,13 @@
+import { headers } from 'next/headers'
+
+export function MyComp() {
+  return headers()
+}
+
+export function MyComp2() {
+  return headers()
+}
+
+export function MyComp3() {
+  return headers()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-10.output.tsx

@@ -0,0 +1,13 @@
+import { headers, type UnsafeUnwrappedHeaders } from 'next/headers';
+
+export function MyComp() {
+  return (headers() as unknown as UnsafeUnwrappedHeaders);
+}
+
+export function MyComp2() {
+  return (headers() as unknown as UnsafeUnwrappedHeaders);
+}
+
+export function MyComp3() {
+  return (headers() as unknown as UnsafeUnwrappedHeaders);
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-11.input.tsx

@@ -0,0 +1,9 @@
+import { headers } from 'next/headers'
+
+export function MyComp() {
+  headers()
+}
+
+export function generateContentfulMetadata() {
+  headers()
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-11.output.tsx

@@ -0,0 +1,10 @@
+import { headers, type UnsafeUnwrappedHeaders } from 'next/headers';
+
+export function MyComp() {
+  (headers() as unknown as UnsafeUnwrappedHeaders)
+}
+
+export function generateContentfulMetadata() {
+  (headers() as unknown as UnsafeUnwrappedHeaders)
+}
+

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-12.input.js

@@ -0,0 +1,5 @@
+import { cookies } from "next/headers";
+
+async function MyComponent() {
+  callSomething(cookies());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-12.output.js

@@ -0,0 +1,5 @@
+import { cookies } from "next/headers";
+
+async function MyComponent() {
+  callSomething(await cookies());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-13.input.js

@@ -0,0 +1,5 @@
+import { headers } from "next/headers";
+
+async function MyComponent() {
+  callSomething(headers());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-13.output.js

@@ -0,0 +1,5 @@
+import { headers } from "next/headers";
+
+async function MyComponent() {
+  callSomething(await headers());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-14.input.js

@@ -0,0 +1,5 @@
+import { cookies } from "next/headers";
+
+export default async function Page() {
+  callSomething(cookies());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-14.output.js

@@ -0,0 +1,5 @@
+import { cookies } from "next/headers";
+
+export default async function Page() {
+  callSomething(await cookies());
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-15.input.js

@@ -0,0 +1,7 @@
+import { cookies } from "next/headers";
+
+async function MyComponent() {
+  function asyncFunction() {
+    callSomething(cookies());
+  }
+}

packages/next-codemod/transforms/__testfixtures__/next-async-request-api-dynamic-apis/async-api-15.output.js

@@ -0,0 +1,8 @@
+import { cookies } from "next/headers";
+
+async function MyComponent() {
+  function asyncFunction() {
+    callSomething(/* TODO: please manually await this call, codemod cannot transform due to undetermined async scope */
+    cookies());
+  }
+}