Index of every page on this site: llms.txt
All skills
vercel avatar

/dce-edge

@495cbfa official
by vercelvercel/next.js144k stars
32,812
Run it yourself

DCE-safe require() patterns and edge runtime constraints. Use when writing conditional require() calls, guarding Node-only imports (node:stream etc.), or editing define-env-plugin.ts / app-render / stream-utils for edge builds. Covers if/else branching for webpack DCE, TypeScript definite assignment, the NEXT_RUNTIME vs real feature flag distinction, and forcing flags false for edge in define-env.ts.

  • 1 file
  • 4 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vercel/next.js/dce-edge

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈103 tokens for metadata: the name and description. ≈906 when used: this file.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈414 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

DCE + Edge

Use this skill when changing conditional require() paths, Node-only imports, or edge/runtime branching.

DCE-Safe require() Pattern

Webpack only DCEs a require() when it sits inside the dead branch of an if/else whose condition DefinePlugin can evaluate at compile time.

// CORRECT - webpack can eliminate the dead branch
if (process.env.__NEXT_USE_NODE_STREAMS) {
  require('node:stream')
} else {
  // web path
}

What does NOT work:

  • Early-return/throw guards: webpack doesn't do control-flow analysis for throws/returns, so the require() is still traced.
  • Bare if without else: works for inline node:* specifiers but NOT for require('./some-module') that pulls a new file into the module graph.

Always test edge changes with pnpm test-start-webpack on test/e2e/app-dir/app/standalone.test.ts (has edge routes), not with NEXT_SKIP_ISOLATE=1 which skips the full webpack compilation.

TypeScript + DCE Interaction

Use if/else (not two independent if blocks) when assigning a variable conditionally on process.env.X. TypeScript cannot prove exhaustiveness across if (flag) { x = a }; if (!flag) { x = b } and will error with "variable used before being assigned". The if/else pattern satisfies both TypeScript (definite assignment) and webpack DCE.

Compile-Time Switcher Pattern

Platform-specific code (node vs web) can use a single .ts switcher module that conditionally require()s either .node.ts or .web.ts into a typed variable, then re-exports the shared runtime API as named exports. Keep the branch as if/else so DefinePlugin can dead-code-eliminate the unused require(). Keep shared types canonical in .node.ts, with .web.ts importing them via import type and the switcher re-exporting types as needed. Examples: stream-ops.ts and debug-channel-server.ts.

NEXT_RUNTIME Is Not a Feature Flag

In user-project webpack server compilers, process.env.NEXT_RUNTIME is inlined to 'nodejs'. Guarding Node-only require('node:*') paths with NEXT_RUNTIME === 'nodejs' does not prune anything. For feature-gated codepaths, guard on the real feature define (e.g. process.env.__NEXT_USE_NODE_STREAMS).

Edge Runtime Constraints

Edge routes do NOT use pre-compiled runtime bundles. They are compiled by the user's webpack/Turbopack, so define-env.ts controls DCE. Feature flags that gate node:* imports must be forced to false for edge builds in define-env.ts (isEdgeServer ? false : flagValue), otherwise webpack will try to resolve node:stream etc. and fail.

app-page.ts Template Gotchas

  • app-page.ts is a build template compiled by the user's bundler. Any require() in this file is traced by webpack/turbopack at next build time. You cannot require internal modules with relative paths because they won't be resolvable from the user's project. Instead, export new helpers from entry-base.ts and access them via entryBase.* in the template.
  • Template helpers should stay out of RenderResult. If app-page.ts needs a Node-stream-only utility, prefer a small dedicated helper module in server/stream-utils/ (with DCE-safe if/else + require()).

Verification

  • Validate edge bundling regressions with pnpm test-start-webpack test/e2e/app-dir/app/standalone.test.ts
  • For module-resolution/build-graph fixes, verify without NEXT_SKIP_ISOLATE=1

Related Skills

  • $flags - flag wiring (config/schema/define-env/runtime env)
  • $react-vendoring - entry-base boundaries and vendored React
  • $runtime-debug - reproduction and verification workflow

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 495cbfa. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
metadata
{
  "internal": true
}

README badge

README badge for vercel/next.js/dce-edge