feat(serverAssets): opt-in embed modes for large catalogs

[s00d]

🔗 Linked issue

#1833

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Large serverAssets catalogs (thousands of small JSON files) make Nitro builds slow / OOM because production mode creates one Rollup raw: module per file (#1833). Nuxt 4.x apps that ship translation trees hit this hard.

This PR adds an opt-in embed flag on ServerAssetDir. Default stays true (same historical raw: behavior — no silent auto-inline).

embed	Build behavior
true / omitted	One lazy raw: chunk per file (unchanged)
"inline"	Single virtual module (like public-assets inline)
false	Copy to server/assets/<baseName>; meta+path at build; readFile at runtime (like public-assets node)

Also skips per-file gzip in the server size tree for chunks/raw/** (logging only).

Example

export default defineNitroConfig({
  serverAssets: [{
    baseName: 'i18n',
    dir: './i18n-data',
    embed: 'inline', // or false for Node disk reads
  }],
})

Real-world use

nuxt-i18n-micro can register locale JSON trees as serverAssets and set embed: 'inline' or embed: false so Node SSR builds stay fast without dual-writing payloads to public/.

Benchmark (same fixture: 1296 JSON, compressedSizes: true)

Era	nitropack	strategy	ms (run 1 / 2)	chunks/raw
Nuxt 4.1.2	2.12.5	N× raw:	3228 / 3986	1296
Nuxt 4.2	2.12.9	N× raw:	3286	1296
Nuxt 4.4+	2.13.4	N× raw:	4605 / 3124	1296
this PR	2.13.4+fix	embed: "inline"	1608	0
this PR	2.13.4+fix	embed: false	3288	0

Notes:

• Published 2.12.x → 2.13.x already used N× raw: per file; cost is the same strategy, wall time varies with machine/noise.
• Default with this PR remains N× raw: (same as 2.12.5 / 2.13.4). Speedup requires explicit embed.
• Extra check on 625 JSON, minify off, compressedSizes: false: default ~2270 ms / 625 raw; inline ~610 ms / 0; false ~1130 ms / 0.

Tests

• test/unit/server-assets-perf.test.ts — default unchanged, inline/false runtime, binary, ignore, pattern, mixed dirs
• Also green: test/unit/ + test/presets/node.test.ts (99 passed, no regressions)

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

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

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 600eb2ff-c63c-4d68-87f4-7a0ddba8d847

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

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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