Unverified Commit b2f208ae authored by Joseph's avatar Joseph Committed by GitHub

Backport: new view-transitions guide, update and fixes (#92264)

Publishing: 

1. `6a204593` - docs: add middleware bypass note to CDN caching guide
(#92132)
2. `495d50f1` - docs: document revalidateTag's required second
argument in upgrade guide (#92134)
3. `faa4b992` - docs: local images referenced by remote source
(#92178)
4. `0167a026` - Docs/adapters review (#92223)
5. `2622a539` - docs: vt demo guide (#92249)

---------
Co-authored-by: 's avatarJJ Kasper <jj@jjsweb.site>
Co-authored-by: 's avatarAurora Scharff <66901228+aurorascharff@users.noreply.github.com>
parent 52faae3d
...@@ -117,6 +117,50 @@ export default function Page() { ...@@ -117,6 +117,50 @@ export default function Page() {
} }
``` ```
### Images without static imports
If you can't use a static `import` for your images, you can use a dynamic `import()` in a Server Component to still get automatic `width`, `height`, and `blurDataURL`:
```tsx filename="app/blog/[slug]/page.tsx" switcher
import Image from 'next/image'
async function PostImage({
imageFilename,
alt,
}: {
imageFilename: string
alt: string
}) {
const { default: image } = await import(
`../content/blog/images/${imageFilename}`
)
// image contains width, height, and blurDataURL
return <Image src={image} alt={alt} />
}
```
```jsx filename="app/blog/[slug]/page.js" switcher
import Image from 'next/image'
async function PostImage({ imageFilename, alt }) {
const { default: image } = await import(
`../content/blog/images/${imageFilename}`
)
// image contains width, height, and blurDataURL
return <Image src={image} alt={alt} />
}
```
If you have a [path alias](https://www.typescriptlang.org/tsconfig/#paths) configured (e.g. `@/`), you can use it instead of a relative path:
```tsx
const { default: image } = await import(
`@/content/blog/images/${imageFilename}`
)
```
The path must include a static prefix (like `../content/blog/images/`). Be as specific as possible, since **all** files matching that prefix are bundled. Only files in your specified directory are included, so external input cannot reach outside of it.
## Remote images ## Remote images
To use a remote image, you can provide a URL string for the `src` property. To use a remote image, you can provide a URL string for the `src` property.
......
...@@ -52,6 +52,8 @@ App Router responses can vary based on several custom request headers. Next.js s ...@@ -52,6 +52,8 @@ App Router responses can vary based on several custom request headers. Next.js s
- `next-router-segment-prefetch` — the specific segment being prefetched - `next-router-segment-prefetch` — the specific segment being prefetched
- `next-url` — added only for routes that use [interception routes](/docs/app/api-reference/file-conventions/intercepting-routes), carries the URL being intercepted - `next-url` — added only for routes that use [interception routes](/docs/app/api-reference/file-conventions/intercepting-routes), carries the URL being intercepted
> **Good to know:** [`proxy.js`](/docs/app/api-reference/file-conventions/proxy) (previously Middleware) should run before the CDN cache so it remains the source of truth for auth, redirects, and rewrites. If your deployment places `proxy.js` behind the CDN, configure the cache layer to bypass caching for routes that depend on `proxy.js` decisions.
Many CDNs don't support `Vary` without additional configuration. Next.js addresses this with the `_rsc` search parameter: a hash of the relevant request header values that acts as a cache-key, ensuring different response variants get different cache keys. This ensures correct responses even on CDNs that ignore `Vary`. Many CDNs don't support `Vary` without additional configuration. Next.js addresses this with the `_rsc` search parameter: a hash of the relevant request header values that acts as a cache-key, ensuring different response variants get different cache keys. This ensures correct responses even on CDNs that ignore `Vary`.
## Handling Headers at the CDN ## Handling Headers at the CDN
......
...@@ -454,7 +454,17 @@ bun add -D babel-plugin-react-compiler ...@@ -454,7 +454,17 @@ bun add -D babel-plugin-react-compiler
### revalidateTag ### revalidateTag
[`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) has a new function signature. You can pass a [`cacheLife`](/docs/app/api-reference/functions/cacheLife#reference) profile as the second argument. [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) now requires a second argument specifying a [`cacheLife`](/docs/app/api-reference/functions/cacheLife#reference) profile. The single-argument form is deprecated and will produce a TypeScript error.
```ts
// Before
revalidateTag('posts')
// After
revalidateTag('posts', 'max')
```
If you need immediate expiration rather than stale-while-revalidate, use [`updateTag`](/docs/app/api-reference/functions/updateTag) in Server Actions instead.
```ts filename="app/actions.ts" switcher ```ts filename="app/actions.ts" switcher
'use server' 'use server'
......
This diff is collapsed.
...@@ -4,7 +4,7 @@ description: Enable ViewTransition API from React in App Router ...@@ -4,7 +4,7 @@ description: Enable ViewTransition API from React in App Router
version: experimental version: experimental
--- ---
`viewTransition` is an experimental flag that enables the new [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) in React. This API allows you to leverage the native View Transitions browser API to create seamless transitions between UI states. `viewTransition` enables React's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) integration in Next.js. This lets you animate navigations, loading states, and content changes using the native browser View Transitions API.
To enable this feature, you need to set the `viewTransition` property to `true` in your `next.config.js` file. To enable this feature, you need to set the `viewTransition` property to `true` in your `next.config.js` file.
...@@ -19,9 +19,10 @@ const nextConfig = { ...@@ -19,9 +19,10 @@ const nextConfig = {
module.exports = nextConfig module.exports = nextConfig
``` ```
> Important Notice: The `<ViewTransition>` Component is already available in React's Canary release channel. > [!NOTE]
> `experimental.viewTransition` is only required to enable deeper integration with Next.js features e.g. automatically > The [`<ViewTransition>`](https://react.dev/reference/react/ViewTransition) component is provided by React.
> [adding Transition types](https://react.dev/reference/react/addTransitionType) for navigations. Next.js specific transition types are not implemented yet. > The `experimental.viewTransition` flag enables Next.js integration, such as triggering
> transitions during route navigations.
## Usage ## Usage
...@@ -33,6 +34,6 @@ import { ViewTransition } from 'react' ...@@ -33,6 +34,6 @@ import { ViewTransition } from 'react'
### Live Demo ### Live Demo
Check out our [Next.js View Transition Demo](https://view-transition-example.vercel.app) to see this feature in action. Check out the [View Transitions Demo](https://react-view-transitions-demo.labs.vercel.dev) to see this feature in action, or read the [designing view transitions guide](/docs/app/guides/view-transitions) for a step-by-step walkthrough.
As this API evolves, we will update our documentation and share more examples. However, for now, we strongly advise against using this feature in production. The View Transitions API is a baseline web standard, and browser support continues to expand. As React's [`<ViewTransition>`](https://react.dev/reference/react/ViewTransition) component evolves, more transition patterns and use cases will become available.
...@@ -168,6 +168,9 @@ require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2)); ...@@ -168,6 +168,9 @@ require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2));
# Set the adapter path so that the app uses it. # Set the adapter path so that the app uses it.
export NEXT_ADAPTER_PATH="${ADAPTER_DIR}/dist/index.js" export NEXT_ADAPTER_PATH="${ADAPTER_DIR}/dist/index.js"
# Build the app
pnpm build
# Write any metadata needed later to files in the working directory. # Write any metadata needed later to files in the working directory.
BUILD_ID="$(cat .next/BUILD_ID)" BUILD_ID="$(cat .next/BUILD_ID)"
DEPLOYMENT_ID="my-adapter-local" DEPLOYMENT_ID="my-adapter-local"
...@@ -181,9 +184,6 @@ IMMUTABLE_ASSET_TOKEN="undefined" ...@@ -181,9 +184,6 @@ IMMUTABLE_ASSET_TOKEN="undefined"
echo "IMMUTABLE_ASSET_TOKEN: $IMMUTABLE_ASSET_TOKEN" echo "IMMUTABLE_ASSET_TOKEN: $IMMUTABLE_ASSET_TOKEN"
} >> .adapter-build.log } >> .adapter-build.log
# Build the app
pnpm build
# Start or deploy the app. Capture the URL at this point or make the script output the URL to stdout. # Start or deploy the app. Capture the URL at this point or make the script output the URL to stdout.
provider-cli-to-deploy provider-cli-to-deploy
......
...@@ -20,12 +20,12 @@ const pathnames = [ ...@@ -20,12 +20,12 @@ const pathnames = [
].map((output) => output.pathname) ].map((output) => output.pathname)
const result = await resolveRoutes({ const result = await resolveRoutes({
url: requestUrl, url: new URL(requestUrl),
buildId, buildId,
basePath: config.basePath || '', basePath: config.basePath || '',
i18n: config.i18n, i18n: config.i18n,
headers: requestHeaders, headers: new Headers(requestHeaders),
requestBody, requestBody, // ReadableStream
pathnames, pathnames,
routes: routing, routes: routing,
invokeMiddleware: async (ctx) => { invokeMiddleware: async (ctx) => {
...@@ -43,8 +43,14 @@ if (result.resolvedPathname) { ...@@ -43,8 +43,14 @@ if (result.resolvedPathname) {
`resolveRoutes()` returns: `resolveRoutes()` returns:
- `middlewareResponded`: `true` when middleware already sent a response (the adapter should not invoke an entrypoint).
- `externalRewrite`: A `URL` when routing resolved to an external rewrite destination.
- `redirect`: An object with `url` (`URL`) and `status` when the request should be redirected.
- `resolvedPathname`: The route pathname selected by Next.js routing. For dynamic routes, this is the matched route template such as `/blog/[slug]`. - `resolvedPathname`: The route pathname selected by Next.js routing. For dynamic routes, this is the matched route template such as `/blog/[slug]`.
- `resolvedQuery`: The final query after rewrites or middleware have added or replaced search params. - `resolvedQuery`: The final query after rewrites or middleware have added or replaced search params.
- `invocationTarget`: The concrete pathname and query to invoke for the matched route. - `invocationTarget`: The concrete pathname and query to invoke for the matched route.
- `resolvedHeaders`: A `Headers` object containing any headers added or modified during routing.
- `status`: An HTTP status code set by routing (for example from a redirect or rewrite rule).
- `routeMatches`: A record of named matches extracted from dynamic route segments.
For example, if `/blog/post-1?draft=1` matches `/blog/[slug]?slug=post-1`, `resolvedPathname` is `/blog/[slug]` while `invocationTarget.pathname` is `/blog/post-1`. For example, if `/blog/post-1?draft=1` matches `/blog/[slug]?slug=post-1`, `resolvedPathname` is `/blog/[slug]` while `invocationTarget.pathname` is `/blog/post-1`.
...@@ -80,7 +80,7 @@ React pages from the `app/` directory: ...@@ -80,7 +80,7 @@ React pages from the `app/` directory:
type: 'APP_PAGE' type: 'APP_PAGE'
id: string // Route identifier id: string // Route identifier
filePath: string // Path to the built file filePath: string // Path to the built file
pathname: string // URL pathname.Includes .rsc suffix for RSC routes pathname: string // URL pathname. Includes .rsc suffix for RSC routes
sourcePage: string // Original relative source file path sourcePage: string // Original relative source file path
runtime: 'nodejs' | 'edge' // Runtime the route is built for runtime: 'nodejs' | 'edge' // Runtime the route is built for
assets: Record<string, string> // Traced dependencies (key: relative path from repo root, value: absolute path) assets: Record<string, string> // Traced dependencies (key: relative path from repo root, value: absolute path)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment