feat: import optional deps on demand from the user project

[pi0x]

Removes all optional peer dependencies except vite, resolving each from the user project on demand via src/utils/dep.ts (importDep / ensureDep, which resolves from nitro.options.rootDir and offers to install what is missing).

Direct imports → importDep

dep	before	now
rollup	await import("rollup") ×2	new src/build/rollup/_import.ts helper
xml2js	await import("xml2js")	resolved from rootDir in the IIS web.config merge
@vercel/queue	optional peer	already went through importDep — the peer entry was redundant
zephyr-agent	optional peer	already went through importDep

dotenv / giget / jiti

These are optional peers of c12, which Nitro bundles — so a bare import("jiti") inside dist/ cannot reach the user's node_modules under pnpm's isolated layout. They now get a bundle-time resolve.alias to a shim under src/shims/ that goes through importDep too:

// dist/_libs/c12+rc9.mjs
const { createJiti } = await import("./jiti.ts.mjs").catch(...)

dotenv is only reachable on runtimes without node:util.parseEnv (below Nitro's supported Node range), and giget only for remote extends: — both keep working, they just install on demand now.

vite stays an optional peer

src/build/vite/dev.ts extends vite's DevEnvironment class and src/types/build.ts / src/build/vite/* re-export vite types from Nitro's public .d.ts, so dropping the peer entry would break type resolution for consumers. Left as-is to keep the risk down.

Other

• build.config.ts: externals no longer derive the full list from pkg.peerDependencies (which would have silently started bundling rollup); explicit optionalDeps list instead, minus the shimmed ones. Same for the tracedPackages hook.
• dotenv + jiti moved to devDependencies (they were peer-only) so this repo's own tests and typecheck still resolve them.
• AGENTS.md: documents the convention.

Testing

pnpm lint, pnpm typecheck, pnpm build clean. pnpm test:rolldown 913 passed. pnpm test:rollup has 3 failures in test/unit/import-attributes.test.ts — pre-existing on main (verified by stashing), caused by resolveBuilder prompting for an install against a temp rootDir instead of using utils/dep.ts, which has an isTest guard. Not touched here.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
nitro.build	Ready	Preview	Aug 20, 2026 7:55pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 80b84181-cc23-49d5-b860-8b9dd9c57d19

📥 Commits

Reviewing files that changed from the base of the PR and between d8eb77a and 6663f02.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (11)

• AGENTS.md
• build.config.ts
• package.json
• src/build/rollup/_import.ts
• src/build/rollup/dev.ts
• src/build/rollup/prod.ts
• src/presets/iis/utils.ts
• src/shims/README.md
• src/shims/dotenv.ts
• src/shims/giget.ts
• src/shims/jiti.ts

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

---

📝 Walkthrough

Walkthrough

The change adds optional dependency configuration and build-time shims. Rollup and IIS utilities now resolve dependencies from the user project through importDep. Package metadata and contributor guidance reflect the new loading model.

Changes

Optional dependency loading

Layer / File(s)	Summary
Optional dependency build configuration AGENTS.md, build.config.ts, package.json, src/shims/README.md	The build aliases shimmed packages, externalizes other optional dependencies, removes optional dependencies from traced results, and retains only optional vite peer metadata.
Runtime shims for optional packages src/shims/*.ts	New shims dynamically load dotenv, giget, and jiti, then export their required APIs.
Build and IIS dependency loaders src/build/rollup/..., src/presets/iis/utils.ts	Rollup and xml2js now load from the user project through importDep. IIS helpers receive rootDir, and empty XML input avoids parser loading.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 6663f

The change updates optional dependency loading while preserving existing behavior, and no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 8 files. (3 skipped: 3 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description clearly explains the optional dependency refactor and its testing status.
Title check	✅ Passed	The title uses the conventional commit format and accurately summarizes the optional dependency refactor.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/shim-deps

---

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.}

[pkg-pr-new]

Open in StackBlitz

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

commit: 6663f02