asked in real use

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

__NEXT_SHOW_IGNORE_LISTED disables ignore-list filtering in dev errors

Set __NEXT_SHOW_IGNORE_LISTED=true to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to 'at ignore-listed frames', hiding useful context when debugging framework internals. This is defined in packages/next/src/server/patch-error-inspect.ts.

NEXT_TURBOPACK_TRACING environment variable presets

The NEXT_TURBOPACK_TRACING environment variable supports the following preset values: '1' or 'overview' (basic user level tracing, the only preset in published Next.js releases), 'next' (overview plus lower-level debug and trace logs for Next.js crates), 'turbopack' (next plus lower-level debug and trace logs for Turbopack crates), and 'turbo-tasks' (turbopack plus verbose tracing of every Turbo-Engine function execution). Any directives syntax supported by tracing_subscriber::filter::EnvFilter can also be used.

Turbopack tracing output file format and location

When NEXT_TURBOPACK_TRACING is enabled, Next.js writes tracing information to .next-profiles/trace-turbopack.bin in a binary format.

Detailed tracing requires custom Next.js build

A normal Next.js canary or stable release only includes info level tracing, which is the user-facing tracing level. More detailed tracing requires a custom Next.js build.

Starting turbo-trace-server

The trace-server can be started with either 'cargo run --bin turbo-trace-server --release -- /path/to/your/trace-turbopack.bin' or 'pnpm next internal trace .next-profiles/trace-turbopack.bin'. The server connects via WebSocket on port 57475 on localhost. A --release build is recommended as it can provide approximately 10x performance difference compared to debug builds.

Turbo-trace-viewer access and visualization modes

After starting the trace-server, open https://trace.nextjs.org/ in the browser. The viewer supports visualization modes: aggregated spans (same name in same parent grouped together), individual spans, ordering (by occurrence order or by value with largest first), and bottom-up view (showing self value instead of total). Value modes include duration (CPU time), allocated memory, allocations count, deallocated memory, and persistently allocated memory.

Re-verify session in Server Actions and Route Handlers

Always re-read and re-verify the session in every Server Action and Route Handler close to the data. UI checks hide elements but don't protect data; trusting the client for authorization is a security risk.

TanStack Query provider setup for server and client

Create a single QueryClient instance for browser use and a new QueryClient for each server render. Use a module-level variable with nullish coalescing to check if running on the server (typeof window === 'undefined') and create a new client on server, or return the cached browser instance. Wrap routes using TanStack Query in a QueryClientProvider component placed in a layout.

Query key and options contract for server and client sharing

Keep the query key and query options together in a shared module so both server and client call sites use the same identity. Export a queryOptions object with the same queryKey used by both prefetchQuery on the server and useSuspenseQuery/useQuery on the client. This ensures hydration works correctly.

Cache server-provided data with cacheComponents, use cache, cacheLife, and cacheTag

Enable cacheComponents in next.config.ts. In data fetching functions, add the 'use cache' directive, call cacheLife with a profile (e.g., 'max'), and call cacheTag with a tag identifier so mutations can invalidate the cache. This allows the server cache to coordinate with TanStack Query's browser cache.

Shared cache contract for server tag and query key

Define both query key and server tag identities in one shared contract module. The server function calls cacheTag(productCache.tag(id)) and the client calls useSuspenseQuery(productCache.options(id)). Keep this contract free of server-only and client-only imports so both cache layers can reuse it.

Give your agent this brain