deployment & infrastructure

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

rspack release process via GitHub Actions

Rspack releases are managed via GitHub Actions workflow at .github/workflows/release-next-rspack.yml. The workflow supports dry-run mode and supports multiple npm tags including latest, alpha, beta, and canary.

OpenTelemetry works out of the box on Vercel

OpenTelemetry has been configured to work out of the box on Vercel. Follow Vercel documentation to connect your project to an observability provider.

Self-hosting with OpenTelemetry Collector

When self-hosting, set up your own OpenTelemetry Collector to receive and process telemetry data from your Next.js app. Follow the OpenTelemetry Collector Getting Started guide to configure it to receive data from your Next.js app, then deploy your Next.js app to your chosen platform.

Speed Insights auto instrumentation removed in Next.js 15

Auto instrumentation for Speed Insights was removed in Next.js 15. To continue using Speed Insights, follow the Vercel Speed Insights Quickstart guide.

geolocation and ipAddress from @vercel/functions

import { geolocation } from '@vercel/functions'; export function middleware(request: NextRequest) { const { city } = geolocation(request); } and import { ipAddress } from '@vercel/functions'; export function middleware(request: NextRequest) { const ip = ipAddress(request); }

Enable useOffline for automatic offline retry

Set experimental.useOffline to true in next.config.ts or next.config.js to enable automatic retry of failed navigations, RSC data fetches, prefetches, and Server Actions when the network goes down. With this flag enabled, failed requests remain pending and automatically retry once the connection returns, instead of throwing errors immediately.

useOffline hook returns connectivity state

The useOffline hook returns true when the browser fires an offline event or when a navigation, prefetch, or Server Action fetch fails. It returns false when a background connectivity check succeeds. This is more reliable than navigator.onLine because it reflects actual internet connectivity, not just OS network interface status.

useOffline hook behavior during SSR and hydration

useOffline returns false during server-side rendering and initial hydration. The first accurate value is whatever the browser reports after the app mounts.

Offline detection applies only to soft navigations and Server Actions

The offline feature only applies to soft navigations into prefetched routes and Server Action calls from the current page. A full page reload while offline still fails because the browser needs the network to deliver the HTML. Full offline loads would need a service worker.

Recommended configuration for offline support with Cache Components

Enable cacheComponents: true, partialPrefetching: true, and experimental.useOffline: true in next.config.ts or next.config.js. Cache Components lets you place the Suspense boundary close to uncached data with the App Shell rendered around it. Partial Prefetching makes the App Shell the unit a Link prefetches, so it is ready to render when navigation happens offline.

useOffline hook import path

Import the useOffline hook from 'next/offline' in Client Components that need to check connectivity state.

Suspense fallback shows while requests are pending offline

When offline, if a navigation, prefetch, or Server Action fetch fails, the UI remains in its loading state with the Suspense fallback visible or a pending transition for a Server Action. The UI looks the same as if the server is slow. Use the useOffline hook to differentiate between slow server and offline conditions in the fallback UI.

Parameterized routes support offline rendering

With useOffline enabled, parameterized routes like /chats/[id] render their shared App Shell when navigating offline, and the dynamic content behind its Suspense boundary loads when the connection returns. If per-link URL data is prefetched ahead of the click, the dynamic content renders immediately offline instead of waiting for connection.

Navigation queues behind pending Server Action while offline

While offline, clicking a link during a pending Server Action may appear to do nothing. The link's navigation also needs the network and queues behind the same connectivity signal as the action. Both resolve when the connection returns.

Loading.tsx as alternative to Cache Components for offline support

A route-level loading.tsx file provides the same offline job as Cache Components. It gives Next.js a boundary to prefetch as the route's shell, so the shell renders offline and the page resumes once the network returns. The useOffline hook, banner, and Server Action retry all behave the same way with loading.tsx.

Example useOffline implementation in connectivity fallback component

'use client' import { useOffline } from 'next/offline' export function ConnectivityFallback() { const isOffline = useOffline() return ( <p> {isOffline ? 'Waiting for connection to load this section...' : 'Loading...'} </p> ) } This Client Component returns different messages based on offline state and can be passed as a Suspense fallback.

Example offline banner in root layout

'use client' import { useOffline } from 'next/offline' export function OfflineBanner() { const isOffline = useOffline() if (!isOffline) { return null } return ( <div role="status"> Offline. Pending requests will retry once you are back online. </div> ) } Add to root layout to display connectivity state across the entire app.

Example next.config.ts for offline support

import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, partialPrefetching: true, experimental: { useOffline: true, }, } export default nextConfig

Nginx configuration for static export deployment

For Nginx deployment of static exports, configure the root to point to the `out` folder and use `try_files $uri $uri.html $uri/ =404;` to route requests. When `trailingSlash: false`, add a rewrite rule for dynamic routes like `/blog/(.*)` to map to `/blog/$1.html`. Configure `error_page 404 /404.html;` for 404 handling.

Static export deployment hosting requirements

Since static exports produce only HTML/CSS/JS static assets, Next.js applications with static export can be deployed and hosted on any web server that can serve static files, including GitHub Pages and services like Nginx.

Encryption key environment variable for self-hosted deployments

When self-hosting Next.js across multiple servers, use the process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY environment variable to overwrite the encryption key. This ensures encryption keys are persistent across builds and all server instances use the same key. The key must be a base64-encoded value with decoded length matching a valid AES key size (16, 24, or 32 bytes). Next.js generates 32-byte keys by default. Generate a compatible key using: openssl rand -base64 32

serverActions.allowedOrigins configuration

For large applications using reverse proxies or multi-layered backend architectures where the server API differs from the production domain, use the serverActions.allowedOrigins configuration option in next.config.js to specify a list of safe origins. The option accepts an array of strings. Example: experimental: { serverActions: { allowedOrigins: ['my-proxy.com', '*.my-proxy.com'] } }

Give your agent this brain