refactor!: opt-in experimental.tsconfigPaths

[pi0]

In alpha.1, Nitro introduced tsconfig.json support for aliases and JSX options. (#3757)

Investigating integration with Nuxt with @danielroe, enabling aliases can cause issues as Nuxt generates paths meant for IDE support and not actual runtime resolution.

This PR disables the experimental flag and makes it opt-in. We might more advocate native node subpath import # aliases.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
nitro.build	Ready	Preview	Comment	Dec 11, 2025 3:19pm

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request tightens the conditional logic for TypeScript config path alias resolution by changing the guard condition from a falsy check to an explicit truthy requirement, accompanied by an example demonstrating proper feature enablement.

Changes

Cohort / File(s)	Summary
Configuration and Examples examples/import-alias/nitro.config.ts	Enables tsconfigPaths under the experimental section to activate alias resolution.
Core Resolver Logic src/config/resolvers/tsconfig.ts	Modified guard condition from options.experimental.tsconfigPaths !== false to truthy check. This restricts alias logic execution to only when tsconfigPaths is explicitly truthy, rather than when it's undefined or false.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• The configuration change is straightforward enabling of a feature flag.
• The guard condition modification is a targeted logic adjustment with minimal scope.
• Key review consideration: Verify that narrowing from falsy-check to truthy-check doesn't inadvertently break existing behavior in cases where tsconfigPaths was previously undefined and relied on default behavior.

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	Title follows conventional commits format with breaking change indicator (!) and clearly describes the opt-in change to experimental.tsconfigPaths feature.
Description check	✅ Passed	The pull request description directly relates to the changeset by explaining the rationale for disabling the experimental tsconfigPaths flag and making it opt-in.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/optin-tsconfigpaths

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/config/resolvers/tsconfig.ts (1)

11-19: Guard change correctly makes tsconfigPaths opt‑in

Requiring options.experimental.tsconfigPaths to be truthy here cleanly enforces the new opt‑in behavior and avoids applying tsconfig path aliases by default. Logic and alias merge order remain sound.

If you want to soften the breaking change, you could optionally emit a warning when compilerOptions.paths exist but experimental.tsconfigPaths is not enabled, to guide users to the new flag.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6f7889e and adc3efb.

📒 Files selected for processing (2)

• examples/import-alias/nitro.config.ts (1 hunks)
• src/config/resolvers/tsconfig.ts (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: tests-rolldown (windows-latest)
• GitHub Check: tests-rollup (ubuntu-latest)
• GitHub Check: tests-rollup (windows-latest)

🔇 Additional comments (1)

examples/import-alias/nitro.config.ts (1)

5-7: Explicit opt‑in to experimental.tsconfigPaths is correct

This example now correctly demonstrates enabling tsconfig-based alias resolution only when the experimental flag is explicitly set to true, matching the resolver behavior.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitrojs/nitro@3859

commit: adc3efb