Docs: Create Examples section (#73858)

Closes: https://linear.app/vercel/issue/DOC-4047/create-examples-section

Redirects: vercel/front#39878

docs/01-app/02-building-your-application/12-examples/index.mdx → docs/01-app/02-examples/index.mdx

@@ -1,11 +1,8 @@
 ---
-title: Next.js Examples
-nav_title: Examples
-description: Examples of popular Next.js UI patterns and use cases.
+title: Examples
+descriptions: Learn how to implement common UI patterns and use cases  using Next.js
 ---
 
-{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
-
 ### Data Fetching
 
 - [Using the `fetch` API](/docs/app/building-your-application/data-fetching/fetching#fetching-data-on-the-server-with-the-fetch-api)

docs/01-app/04-api-reference/04-functions/unstable_expirePath.mdx

@@ -0,0 +1,130 @@
+---
+title: unstable_expirePath
+description: API Reference for the unstable_expirePath function.
+version: unstable
+---
+
+`unstable_expirePath` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific path.
+
+> **Good to know**:
+>
+> - `unstable_expirePath` is available in both [Node.js and Edge runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
+> - `unstable_expirePath` only invalidates the cache when the included path is next visited. This means calling `unstable_expirePath` with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
+> - Currently, `unstable_expirePath` invalidates all the routes in the [client-side Router Cache](/docs/app/building-your-application/caching#client-side-router-cache) when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.
+> - Using `unstable_expirePath` invalidates **only the specific path** in the [server-side Route Cache](/docs/app/building-your-application/caching#full-route-cache).
+
+## Reference
+
+### Parameters
+
+```tsx
+unstable_expirePath(path: string, type?: 'page' | 'layout'): void;
+```
+
+- `path`: Either a string representing the filesystem path associated with the data you want to expire (for example, `/product/[slug]/page`), or the literal route segment (for example, `/product/123`). Must be less than 1024 characters. This value is case-sensitive.
+- `type`: (optional) `'page'` or `'layout'` string to change the type of path to expire. If `path` contains a dynamic segment (for example, `/product/[slug]/page`), this parameter is required. If path refers to the literal route segment, e.g., `/product/1` for a dynamic page (e.g., `/product/[slug]/page`), you should not provide `type`.
+
+### Returns
+
+`unstable_expirePath` does not return a value.
+
+## Examples
+
+### Expiring a specific URL
+
+```ts
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/post-1')
+```
+
+This will purge the cache for one specific URL on the next page visit.
+
+### Expiring a page path
+
+```ts
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/[slug]', 'page')
+// or with route groups
+unstable_expirePath('/(main)/blog/[slug]', 'page')
+```
+
+This will purge the cache any URL that matches the provided `page` file on the next page visit. This will _not_ invalidate pages beneath the specific page. For example, `/blog/[slug]` won't invalidate `/blog/[slug]/[author]`.
+
+### Expiring a layout path
+
+```ts
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/[slug]', 'layout')
+// or with route groups
+unstable_expirePath('/(main)/post/[slug]', 'layout')
+```
+
+This will purge the cache on any URL that matches the provided `layout` file on the next page visit. This will cause pages beneath with the same layout to revalidate on the next visit. For example, in the above case, `/blog/[slug]/[another]` would also revalidate on the next visit.
+
+### Expiring all data
+
+```ts
+import { unstable_expirePath } from 'next/cache'
+
+unstable_expirePath('/', 'layout')
+```
+
+This will purge the Data Cache on the next page visit.
+
+### Server Action
+
+You can call `unstable_expirePath` in a Server Action:
+
+```ts filename="app/actions.ts" switcher
+'use server'
+
+import { unstable_expirePath } from 'next/cache'
+
+export default async function submit() {
+  await submitForm()
+  unstable_expirePath('/')
+}
+```
+
+### Route Handler
+
+You can call `unstable_expirePath` in a Route Handler:
+
+```ts filename="app/api/expire/route.ts" switcher
+import { unstable_expirePath } from 'next/cache'
+import type { NextRequest } from 'next/server'
+
+export async function GET(request: NextRequest) {
+  const path = request.nextUrl.searchParams.get('path')
+
+  if (path) {
+    unstable_expirePath(path)
+    return Response.json({ revalidated: true, now: Date.now() })
+  }
+
+  return Response.json({
+    expired: false,
+    now: Date.now(),
+    message: 'Missing path to expire',
+  })
+}
+```
+
+```js filename="app/api/expire/route.js" switcher
+import { unstable_expirePath } from 'next/cache'
+
+export async function GET(request) {
+  const path = request.nextUrl.searchParams.get('path')
+
+  if (path) {
+    unstable_expirePath(path)
+    return Response.json({ expired: true, now: Date.now() })
+  }
+
+  return Response.json({
+    expired: false,
+    now: Date.now(),
+    message: 'Missing path to expire',
+  })
+}
+```

docs/01-app/04-api-reference/04-functions/unstable_expireTag.mdx

@@ -0,0 +1,85 @@
+---
+title: unstable_expireTag
+description: API Reference for the unstable_expireTag function.
+version: unstable
+---
+
+`unstable_expireTag` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific cache tag.
+
+> **Good to know**:
+>
+> - `unstable_expireTag` is available in both [Node.js and Edge runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
+> - `unstable_expireTag` only invalidates the cache when the path is next visited. This means calling `unstable_expireTag` with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
+
+## Reference
+
+### Parameters
+
+```tsx
+unstable_expireTag(...tags: string[]): void;
+```
+
+- `tags`: String arguments representing the cache tags associated with the data you want to revalidate. Must be less than or equal to 256 characters each. This value is case-sensitive.
+
+You can add tags to `fetch` as follows:
+
+```tsx
+fetch(url, { next: { tags: [...] } });
+```
+
+### Returns
+
+`unstable_expireTag` does not return a value.
+
+## Examples
+
+### Server Action
+
+You can invoke `unstable_expireTag` in a Server Action:
+
+```ts filename="app/actions.ts" switcher
+'use server'
+
+import { unstable_expireTag } from 'next/cache'
+
+export default async function submit() {
+  await addPost()
+  unstable_expireTag('posts', 'blog')
+}
+```
+
+```js filename="app/actions.js" switcher
+'use server'
+
+import { unstable_expireTag } from 'next/cache'
+
+export default async function submit() {
+  await addPost()
+  unstable_expireTag('posts', 'blog')
+}
+```
+
+### Route Handler
+
+You can invoke `unstable_expireTag` in a Route Handler:
+
+```ts filename="app/api/revalidate/route.ts" switcher
+import type { NextRequest } from 'next/server'
+import { unstable_expireTag } from 'next/cache'
+
+export async function GET(request: NextRequest) {
+  const tag = request.nextUrl.searchParams.get('tag')
+  unstable_expireTag(tag)
+  return Response.json({ revalidated: true, now: Date.now() })
+}
+```
+
+```js filename="app/api/revalidate/route.js" switcher
+import { unstable_expireTag } from 'next/cache'
+
+export async function GET(request) {
+  const tag = request.nextUrl.searchParams.get('tag')
+  unstable_expireTag(tag)
+  return Response.json({ revalidated: true, now: Date.now() })
+}
+```

scripts/validate-externals-doc.js

@@ -55,7 +55,7 @@ function validate(docPath) {
 }
 
 const appRouterValid = validate(
-  `docs/01-app/03-api-reference/05-config/01-next-config-js/serverExternalPackages.mdx`
+  `docs/01-app/04-api-reference/05-config/01-next-config-js/serverExternalPackages.mdx`
 )
 const pagesRouterValid = validate(
   `docs/02-pages/03-api-reference/04-config/01-next-config-js/serverExternalPackages.mdx`