fix(nitro): use hash-based cache for dev payloads

[danielroe]

🔗 Linked issue

resolves #34547

📚 Description

this makes sure to use hash-based cache for payloads, as they can be nested.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[pkg-pr-new]

Open in StackBlitz

@nuxt/kit

npm i https://pkg.pr.new/@nuxt/kit@34569

@nuxt/nitro-server

npm i https://pkg.pr.new/@nuxt/nitro-server@34569

nuxt

npm i https://pkg.pr.new/nuxt@34569

@nuxt/rspack-builder

npm i https://pkg.pr.new/@nuxt/rspack-builder@34569

@nuxt/schema

npm i https://pkg.pr.new/@nuxt/schema@34569

@nuxt/vite-builder

npm i https://pkg.pr.new/@nuxt/vite-builder@34569

@nuxt/webpack-builder

npm i https://pkg.pr.new/@nuxt/webpack-builder@34569

commit: 4abb793

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9bb51e25-aa3b-44bf-87bb-c0589312fed2

📥 Commits

Reviewing files that changed from the base of the PR and between 8994083 and 8c5d820.

📒 Files selected for processing (1)

• packages/nitro-server/src/index.ts

---

Walkthrough

The change adds a cacheDriverOption derived from a platform-aware cacheDriverPath (using a file URL href on Windows, the direct path elsewhere). In dev mode it configures a hash-based payload cache driver under nitro.config.devStorage with driver set to cacheDriverOption and base pointed to the payload cache directory. Internal prerender storage configuration is updated to use cacheDriverOption. The new logic runs as part of the bundle setup prior to nitro.init; Nitro exposure and initialisation flow are otherwise unchanged.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarises the main change: implementing hash-based cache for dev payloads to resolve the nested path conflict issue.
Description check	✅ Passed	The description references the linked issue #34547 and explains the purpose of using hash-based cache to handle nested payloads.
Linked Issues check	✅ Passed	The code changes implement hash-based caching via cacheDriverOption to prevent file/directory conflicts when routes have optional subroutes, directly addressing issue #34547.
Out of Scope Changes check	✅ Passed	All changes are scoped to nitro server configuration for payload caching and directly address the linked issue's requirement to use a conflict-free cache strategy.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/payload-cache-path

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 20 untouched benchmarks
⏩ 3 skipped benchmarks¹

---

_{Comparing fix/payload-cache-path (8c5d820) with main (6a51f14)}

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[maxmalysh]

@danielroe Though why limiting this fix only for devStorage? I guess using fs-lite with production storage is still broken?

    storage: {
      cache: { driver: 'fs-lite', base: '.cache/nitro' },
    },

[danielroe]

I think that should probably be raised upstream in unstorage or nitro