merge canary

.github/workflows/build_reusable.yml

@@ -51,6 +51,7 @@ env:
 
 jobs:
   build:
+    timeout-minutes: 25
     runs-on: [self-hosted, linux, x64]
 
     steps:

docs/02-app/01-building-your-application/01-routing/10-router-handlers.mdx

@@ -365,19 +365,21 @@ export async function GET(request) {
 
 Route Handlers can use [Dynamic Segments](/docs/app/building-your-application/routing/dynamic-routes) to create request handlers from dynamic data.
 
-```ts filename="app/items/[slug]/route.js"
+```ts filename="app/items/[slug]/route.ts" switcher
 export async function GET(
   request: Request,
-  {
-    params,
-  }: {
-    params: { slug: string }
-  }
+  { params }: { params: { slug: string } }
 ) {
   const slug = params.slug // 'a', 'b', or 'c'
 }
 ```
 
+```js filename="app/items/[slug]/route.js" switcher
+export async function GET(request, { params }) {
+  const slug = params.slug // 'a', 'b', or 'c'
+}
+```
+
 | Route                       | Example URL | `params`        |
 | --------------------------- | ----------- | --------------- |
 | `app/items/[slug]/route.js` | `/items/a`  | `{ slug: 'a' }` |

docs/02-app/01-building-your-application/01-routing/12-colocation.mdx

@@ -137,7 +137,7 @@ import { Button } from '@/components/button'
 
 ## Project organization strategies
 
-There is no "right" or "wrong" way when it comes to organizing your own files and folders in Next.js a project.
+There is no "right" or "wrong" way when it comes to organizing your own files and folders in a Next.js project.
 
 The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.
 

docs/02-app/01-building-your-application/03-data-fetching/04-server-actions.mdx

@@ -329,6 +329,8 @@ export function Thread({ messages }) {
 The **experimental** `useFormStatus` hook can be used within Form Actions, and provides the `pending` property.
 
 ```jsx filename="app/form.js"
+'use client'
+
 import { experimental_useFormStatus as useFormStatus } from 'react-dom'
 
 function Submit() {

docs/02-app/01-building-your-application/05-optimizing/04-metadata.mdx

@@ -8,7 +8,7 @@ related:
     - app/api-reference/file-conventions/metadata
 ---
 
-Next.js has a Metadata API that can used to define your application metadata (e.g. `meta` and `link` tags inside your HTML `head` element) for improved SEO and web shareability.
+Next.js has a Metadata API that can be used to define your application metadata (e.g. `meta` and `link` tags inside your HTML `head` element) for improved SEO and web shareability.
 
 There are two ways you can add metadata to your application:
 

docs/02-app/01-building-your-application/06-configuring/02-eslint.mdx

@@ -27,9 +27,9 @@ yarn lint
 >
 > ? How would you like to configure ESLint?
 >
-> ❯ Base configuration + Core Web Vitals rule-set (recommended)
-> Base configuration
-> None
+> ❯ Strict (recommended)
+> Base
+> Cancel
 
 One of the following three options can be selected:
 

docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx

@@ -110,7 +110,7 @@ const interSemiBold = fetch(
 ).then((res) => res.arrayBuffer())
 
 // Image generation
-export default function Image() {
+export default async function Image() {
   return new ImageResponse(
     (
       // ImageResponse JSX element
@@ -146,7 +146,7 @@ export default function Image() {
 }
 ```
 
-```jsx filename="app/about/opengraph-image.js" switcher
+```jsx filename="app/about/opengraph-image.jsx" switcher
 import { ImageResponse } from 'next/server'
 
 // Route segment config
@@ -225,7 +225,7 @@ export default function Image({ params }: { params: { slug: string } }) {
 }
 ```
 
-```jsx filename="app/shop/[slug]/opengraph-image.js" switcher
+```jsx filename="app/shop/[slug]/opengraph-image.jsx" switcher
 export default function Image({ params }) {
   // ...
 }
@@ -262,7 +262,7 @@ export const alt = 'My images alt text'
 export default function Image() {}
 ```
 
-```jsx filename="opengraph-image.js / twitter-image.js" switcher
+```jsx filename="opengraph-image.jsx / twitter-image.jsx" switcher
 export const alt = 'My images alt text'
 
 export default function Image() {}
@@ -280,7 +280,7 @@ export const size = { width: 1200, height: 630 }
 export default function Image() {}
 ```
 
-```jsx filename="opengraph-image.js / twitter-image.js" switcher
+```jsx filename="opengraph-image.jsx / twitter-image.jsx" switcher
 export const size = { width: 1200, height: 630 }
 
 export default function Image() {}
@@ -299,7 +299,7 @@ export const contentType = 'image/png'
 export default function Image() {}
 ```
 
-```jsx filename="opengraph-image.js / twitter-image.js" switcher
+```jsx filename="opengraph-image.jsx / twitter-image.jsx" switcher
 export const contentType = 'image/png'
 
 export default function Image() {}
@@ -326,7 +326,7 @@ export const runtime = 'edge'
 export default function Image() {}
 ```
 
-```jsx filename="app/opengraph-image.js" switcher
+```jsx filename="app/opengraph-image.jsx" switcher
 export const runtime = 'edge'
 
 export default function Image() {}
@@ -380,3 +380,43 @@ export default async function Image({ params }: { params: { slug: string } }) {
   )
 }
 ```
+
+```jsx filename="app/posts/[slug]/opengraph-image.jsx" switcher
+import { ImageResponse } from 'next/server'
+
+export const runtime = 'edge'
+
+export const alt = 'About Acme'
+export const size = {
+  width: 1200,
+  height: 630,
+}
+export const contentType = 'image/png'
+
+export default async function Image({ params }) {
+  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
+    res.json()
+  )
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 48,
+          background: 'white',
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        {post.title}
+      </div>
+    ),
+    {
+      ...size,
+    }
+  )
+}
+```

docs/02-app/02-api-reference/04-functions/revalidateTag.mdx

@@ -6,7 +6,8 @@ description: API Reference for the revalidateTag function.
 `revalidateTag` allows you to revalidate data associated with a specific cache tag. This is useful for scenarios where you want to update your cached data without waiting for a revalidation period to expire.
 
 ```tsx filename="app/api/revalidate/route.ts" switcher
-import { NextRequest, NextResponse, revalidateTag } from 'next/server'
+import { NextRequest, NextResponse } from 'next/server'
+import { revalidateTag } from 'next/cache'
 
 export async function GET(request: NextRequest) {
   const tag = request.nextUrl.searchParams.get('tag')
@@ -16,7 +17,8 @@ export async function GET(request: NextRequest) {
 ```
 
 ```jsx filename="app/api/revalidate/route.js" switcher
-import { NextResponse, revalidateTag } from 'next/server'
+import { NextResponse } from 'next/server'
+import { revalidateTag } from 'next/cache'
 
 export async function GET(request) {
   const tag = request.nextUrl.searchParams.get('tag')

docs/02-app/02-api-reference/06-create-next-app.mdx

@@ -21,11 +21,12 @@ You will then be asked the following prompts:
 
 ```bash filename="Terminal"
 What is your project named?  my-app
-Would you like to add TypeScript with this project?  Y/N
-Would you like to use ESLint with this project?  Y/N
-Would you like to use Tailwind CSS with this project? Y/N
-Would you like to use the `src/ directory` with this project? Y/N
-What import alias would you like configured? `@/*`
+Would you like to use TypeScript with this project?  No / Yes
+Would you like to use ESLint with this project?  No / Yes
+Would you like to use Tailwind CSS with this project?  No / Yes
+Would you like to use `src/` directory with this project?  No / Yes
+Use App Router (recommended)?  No / Yes
+Would you like to customize the default import alias?  No / Yes
 ```
 
 Once you've answered the prompts, a new project will be created with the correct configuration depending on your answers.
@@ -59,6 +60,10 @@ Options:
 
     Initialize with ESLint config.
 
+  --app
+
+    Initialize as an App Router project.
+
   --src-dir
 
     Initialize inside a `src/` directory.
@@ -75,6 +80,10 @@ Options:
 
     Explicitly tell the CLI to bootstrap the app using pnpm
 
+  --use-yarn
+
+    Explicitly tell the CLI to bootstrap the app using Yarn
+
   -e, --example [name]|[github-url]
 
     An example to bootstrap the app with. You can use an example name

docs/05-community/01-contribution-guide.mdx

@@ -360,7 +360,7 @@ Here are some guidelines to maintain a consistent style and voice across the doc
   - For example, _Next.js uses React_ instead of _React is used by Next.js_. If you find yourself using words like _was_ and _by_ you may be using a passive voice.
 - Avoid using words like _easy_, _quick_, _simple_, _just_, etc. This is subjective and can be discouraging to users.
 - Avoid negative words like _don't_, _can't_, _won't_, etc. This can be discouraging to readers.
-  - For example, _"You can use the `Link` component to create links between pages""_ instead of _"Don't use the `<a>` tags create links between pages_".
+  - For example, _"You can use the `Link` component to create links between pages"_ instead of _"Don't use the `<a>` tag to create links between pages"_.
 - Write in second person (you/your). This is more personal and engaging.
 - Use gender-neutral language. Use _developers_, _users_, or _readers_, when referring to the audience.
 - If adding code examples, ensure they are properly formatted and working.

errors/next-router-not-mounted.md

@@ -4,10 +4,16 @@
 
 A component used `useRouter` outside a Next.js application, or was rendered outside a Next.js application. This can happen when doing unit testing on components that use the `useRouter` hook as they are not configured with Next.js' contexts.
 
+This can also happen when you try to use the `useRouter` hook from `next/router` inside the `app` directory, as the App Router's `useRouter` from `next/navigation` has different behavior to the `useRouter` hook in `pages`.
+
 #### Possible Ways to Fix It
 
 If used in a test, mock out the router by mocking the `next/router`'s `useRouter()` hook.
 
+If used in the `app` directory, migrate to the new hooks imported from `next/navigation`.
+
 ### Useful Links
 
 - [next-router-mock](https://www.npmjs.com/package/next-router-mock)
+- [App Router Migration](https://nextjs.org/docs/pages/building-your-application/upgrading/app-router-migration#step-5-migrating-routing-hooks)
+- [useRouter](https://nextjs.org/docs/app/api-reference/functions/use-router)

examples/with-azure-cosmos/.env.local.example

@@ -0,0 +1,3 @@
+COSMOSDB_CONNECTION_STRING=
+COSMOSDB_DATABASE_NAME=
+COSMOSDB_CONTAINER_NAME=

examples/with-azure-cosmos/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/with-azure-cosmos/README.md

@@ -0,0 +1,67 @@
+## Example app using Azure Cosmos DB
+
+[Azure Cosmos DB](https://azure.microsoft.com/en-in/products/cosmos-db) is a fully managed NoSQL and relational database for modern app development. Azure Cosmos DB offers single-digit millisecond response times, automatic and instant scalability, along with guarantee speed at any scale. Business continuity is assured with SLA-backed availability and enterprise-grade security.
+
+## Deploy your own
+
+Once you have access to the environment variables you'll need, deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?project-name=with-azure-cosmos&repository-name=with-azure-cosmos&repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fwith-azure-cosmos&integration-ids=oac_mPA9PZCLjkhQGhlA5zntNs0L)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example with-azure-cosmos with-azure-cosmos-app
+```
+
+```bash
+yarn create next-app --example with-azure-cosmos with-azure-cosmos-app
+```
+
+```bash
+pnpm create next-app --example with-azure-cosmos with-azure-cosmos-app
+```
+
+## Configuration
+
+### Set up a Azure Cosmos DB database
+
+Set up a CosmosDB database with [Try Azure Cosmos DB free](https://cosmos.azure.com/try/).
+
+### Set up environment variables
+
+Copy the `env.local.example` file in this directory to `.env.local` (which will be ignored by Git):
+
+```bash
+cp .env.local.example .env.local
+```
+
+Set each variable on `.env.local`:
+
+- `COSMOSDB_CONNECTION_STRING` - You will need your Cosmos DB connection string. You can find these in the Azure Portal in keys section.
+- `COSMOSDB_DATABASE_NAME` - Name of the database you plan on using. This should already exist in the Cosmos DB account.
+- `COSMOSDB_CONTAINER_NAME` - Name of the container you plan on using. This should already exist in the previous database.
+
+### Run Next.js in development mode
+
+```bash
+npm install
+npm run dev
+
+# or
+
+yarn install
+yarn dev
+```
+
+Your app should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/vercel/next.js/discussions).
+
+You will either see a message stating "You are connected to CosmosDB" or "You are NOT connected to CosmosDB". Please make sure you have provided valid environment variables.
+
+When you are successfully connected, you can refer to the [Azure Cosmos DB client library for JavaScript/TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/cosmosdb/cosmos) for further instructions on how to query your database.
+
+## Deploy on Vercel
+
+You can deploy this app to the cloud with [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).