vercel/next.js
Overview
This skill documents DCE-safe require() patterns and edge runtime constraints for Next.js builds. It explains how to write conditional imports, guard Node-only modules, and configure define-env for edge builds so webpack/Turbopack dead-code-eliminates server-only code and avoids unresolved node:* imports. Use it when editing define-env, app render templates, or stream utilities for edge targets.
How this skill works
It inspects conditional branching patterns and environment defines that the bundler can evaluate at compile time. The skill prescribes an if/else pattern around require() calls so DefinePlugin can inline flags and let webpack remove the dead branch. It also describes forcing feature flags false for edge builds in define-env.ts so user compilers don’t attempt to resolve Node-only modules.
When to use it
- Changing conditional require() calls that choose node vs web implementations
- Adding or moving Node-only imports (node:stream, node:fs, etc.)
- Editing define-env.ts to control feature flags for edge builds
- Working on build templates like app-page.ts that the user’s bundler compiles
- Creating platform switcher modules that re-export a unified API
Best practices
- Always use an if/else branch (not bare if or early return) around require() so webpack can DCE the unused branch
- Guard Node-only paths with real feature defines (e.g. process.env.__NEXT_USE_NODE_STREAMS), not NEXT_RUNTIME
- Force feature flags to false for edge in define-env.ts (isEdgeServer ? false : flagValue) to prevent resolving node:* during user builds
- Keep shared types canonical in the .node.ts implementation and import them via import type in the .web.ts file
- Avoid require()ing internal relative modules from build templates; expose helpers from entry-base.ts instead
Example use cases
- Implement a stream-ops switcher that requires node:stream only when the node-stream feature flag is true
- Modify define-env.ts to set __NEXT_USE_NODE_STREAMS to false for edge builds to prevent build-time resolution errors
- Refactor app-page.ts template to call helpers on entry-base.ts rather than requiring internal server utils directly
- Add a small server/stream-utils helper module that is conditionally required with if/else for edge-safe stream handling
FAQ
NEXT_RUNTIME is inlined to 'nodejs' in server compilers and is not a feature flag. Use the real feature define (e.g. __NEXT_USE_NODE_STREAMS) for dead-code elimination.
Why must I avoid bare if or early return guards?
Webpack’s DCE only recognizes require() in the dead branch of an if/else whose condition is compile-time constant. Early returns or single if blocks leave the require() reachable and included in the module graph.
5 skills
This skill guides safe, edge-compatible require patterns and DCE-friendly compilation in Next.js apps, improving edge builds and feature gating.
This skill guides adding or modifying Next.js experimental feature flags end-to-end, covering type declarations, zod schemas, build-time injection, and runtime
This skill helps you create, structure, and maintain agent skills under .agents/skills by guiding frontmatter, content, and naming conventions.
This skill assists in vendoring React and enforcing entry-base.ts boundaries for react-server workflows across Next.js apps.
This skill helps you implement Next.js Cache Components with proactive patterns to optimize static shells, cached content, and dynamic streams.
