docs: clarify noExternals path patterns

[vittorioexp]

Summary

Closes #3269.

Documents how noExternals array patterns work: they match resolved absolute module paths, not bare import specifiers. Adds monorepo and node_modules examples and a Nitro 2 externals.inline migration note.

Also updates the noExternals JSDoc in src/types/config.ts to match.

Test plan

• Verified against src/build/config.ts and src/build/plugins/externals.ts
• Docs-only change (plus JSDoc)

[vercel]

@vittorioexp is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: d1e6849e-e46e-4626-a784-72ff22a8d919

📥 Commits

Reviewing files that changed from the base of the PR and between d9fdd8e and cbeba72.

📒 Files selected for processing (2)

• docs/3.config/0.index.md
• src/types/config.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Updated noExternals documentation and JSDoc to describe externalization and path matching. Updated typescript documentation to describe its empty default and tsConfig bundler configuration with JSX options.

Changes

Configuration documentation

Layer / File(s)	Summary
Document noExternals behavior docs/3.config/0.index.md, src/types/config.ts	Documents externalization defaults, boolean and array options, import-specifier and resolved-path matching, monorepo and cross-platform patterns, and Nitro version equivalents.
Document TypeScript bundler configuration docs/3.config/0.index.md	Documents an empty typescript default and configuration through tsConfig, including JSX compiler options.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to cbeba

This clarifies configuration matching, Nitro migration guidance, and TypeScript bundler configuration without changing runtime behavior. No current merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses the conventional commit format and accurately describes the documentation change to noExternals path patterns.
Description check	✅ Passed	The description explains the noExternals documentation updates, the Nitro 2 migration note, and the related JSDoc change.
Linked Issues check	✅ Passed	The changes address issue #3269 by documenting external dependency inlining, noExternals matching behavior, relevant examples, and the Nitro 2 externals.inline migration.
Out of Scope Changes check	✅ Passed	All changes are limited to documentation and related JSDoc updates for external dependency inlining. No unrelated changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/3.config/0.index.md`:
- Line 1068: Update the documentation sentence about Nitro’s default dependency
externalization to qualify it as applying only to Node-compatible builds, or
explicitly state that it depends on nitro.options.node being true; keep the
existing explanation of inlined modules and alias configuration unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 089aebfe-2390-467d-8060-3bb70d8452c3

📥 Commits

Reviewing files that changed from the base of the PR and between c1ff6ba and 24e9f6a.

📒 Files selected for processing (2)

• docs/3.config/0.index.md
• src/types/config.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Qualify the default externalization claim for non-Node builds.

src/build/plugins.ts:59-76 only enables the externals plugin when nitro.options.node is true; for edge/non-Node builds, this default externalization path is not enabled. Please say “Node-compatible builds” or document the node condition.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/3.config/0.index.md` at line 1068, Update the documentation sentence
about Nitro’s default dependency externalization to qualify it as applying only
to Node-compatible builds, or explicitly state that it depends on
nitro.options.node being true; keep the existing explanation of inlined modules
and alias configuration unchanged.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4460

commit: cbeba72

[pi0x]

• Rebased onto main, no conflicts.
• I tested this against v3 and two claims were wrong, so I fixed them in an extra commit:
  • Patterns are matched against bare specifiers. noExternals: [/^my-lib$/] (which can never match a file path) still inlines the package. They are matched against the import specifier and against the resolved path.
  • v3 production builds do not externalize node_modules by default; they bundle almost everything. Only native/non-bundleable packages and traceDeps stay external. The old behaviour still applies in dev, which is where this option matters.
• Rest of the PR was correct and I kept it: RegExp used as-is, strings escaped as substrings, [\\/] for Windows, and the Nitro 2 externals.inline note.

This comment was written by an AI assistant on behalf of the Nitro maintainers. Please double-check anything that looks wrong.