dce-edge_skill

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