feat: automatically trace known native pkgs #3923

pi0 · 2026-01-06T11:54:08Z

This PR enables automatically tracing known dependencies with native modules (nf3 db)

Adding back nf3 to main deps as tracing is an important feature.

vercel · 2026-01-06T11:54:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
nitro.build	Ready	Preview, Comment	Jan 6, 2026 11:57am

coderabbitai · 2026-01-06T11:54:18Z

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

The pull request moves the nf3 dependency from devDependencies to dependencies and integrates nf3-based dependency tracing into the build system. Changes include importing NodeNativePackages from nf3, computing traced dependencies that combine library packages with user options, and adding tracing instrumentation with detailed logging to the externals plugin.

Changes

Cohort / File(s)	Summary
Dependency update `package.json`	Moved nf3 from devDependencies (^0.3.1) to dependencies (^0.3.2)
Build system integration `src/build/plugins.ts`, `src/build/plugins/externals.ts`	Imported NodeNativePackages from nf3; computed traceDeps combining nf3 packages with user-provided options; replaced externals.include behavior with RegExp-based conditional matching; added tracing instrumentation with file/package counters and detailed logging output; expanded ExternalsOptions type to include trace, conditions, include, and exclude fields

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

refactor!: overhaul externals support #3799 — Overlapping changes to externals handling and nf3-based dependency tracing in plugins/externals.ts and plugins.ts with traceDeps integration

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'feat: automatically trace known native pkgs' follows the conventional commits format with a clear 'feat' type prefix and describes the main change of automatically tracing known native packages.
Description check	✅ Passed	The pull request description directly relates to the changeset, explaining why nf3 is being moved back to main dependencies and how it enables automatic tracing of known native modules.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/build/plugins.ts (1)
60-74: Consider escaping package names in the RegExp to prevent potential ReDoS.

While NodeNativePackages contains safe static values, nitro.options.traceDeps is user-provided configuration. If a package name contains regex metacharacters (e.g., +, *, (), it could cause unexpected matching behavior or, in edge cases, ReDoS.

The escapeRegExp utility from ../../utils/regex.ts is already used in externals.ts for this purpose.
🔎 Suggested fix
+import { escapeRegExp } from "../utils/regex.ts";
Then update the RegExp construction:
     const traceDeps = [
       ...new Set([...NodeNativePackages, ...(nitro.options.traceDeps || [])]),
     ];
+    const escapedDeps = traceDeps.map(escapeRegExp);
     plugins.push(
       externals({
         rootDir: nitro.options.rootDir,
         conditions: nitro.options.exportConditions || ["default"],
         exclude: [...base.noExternal],
         include: isDevOrPrerender
           ? undefined
           : [
               new RegExp(
-                `^(?:${traceDeps.join("|")})|[/\\\\]node_modules[/\\\\](?:${traceDeps.join("|")})(?:[/\\\\])`
+                `^(?:${escapedDeps.join("|")})|[/\\\\]node_modules[/\\\\](?:${escapedDeps.join("|")})(?:[/\\\\])`
               ),
             ],

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 02aef37 and 92fc7b2.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (3)

package.json
src/build/plugins.ts
src/build/plugins/externals.ts

🧰 Additional context used

📓 Path-based instructions (4)

src/**/*.{ts,js,tsx,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.{ts,js,tsx,jsx}: Use pathe for cross-platform path operations instead of Node.js node:path
Use ESM and modern JavaScript
Do not add comments explaining what the line does unless prompted

Files:

src/build/plugins.ts
src/build/plugins/externals.ts

src/{build,dev,runner,cli}/**/*.{ts,js}

📄 CodeRabbit inference engine (AGENTS.md)

Use consola for logging in build/dev code; use nitro.logger when available

Files:

src/build/plugins.ts
src/build/plugins/externals.ts

src/**/*.{ts,js}

📄 CodeRabbit inference engine (AGENTS.md)

Use unstorage for storage abstraction

Files:

src/build/plugins.ts
src/build/plugins/externals.ts

src/build/**/*.{ts,js}

📄 CodeRabbit inference engine (AGENTS.md)

Virtual modules must be registered in src/build/virtual.ts

Files:

src/build/plugins.ts
src/build/plugins/externals.ts

🧠 Learnings (6)

📓 Common learnings

Learnt from: CR
Repo: nitrojs/nitro PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-24T11:45:17.435Z
Learning: Avoid introducing new dependencies unless strictly necessary; add to `devDependencies` unless required in runtime logic