docs: document the working Oxygen deploy OOM fix (supersedes #444)

[paul-phan]

Why

A client storefront hit FATAL ERROR: JavaScript heap out of memory (exit 134) during the Oxygen deploy. The build died before uploading completely, so the environment served HTML referencing client JS that was never published and the storefront rendered blank (all oxygen-v2/.../assets/*.js returned 404).

Supersedes #444, which tried to fix this with build.sourcemap: false in vite.config.ts. That does not work.

Why the config change doesn't work

Two independent reasons, either one fatal:

1. It was already false. Asking Vite to resolve the config on unmodified main returns false for both the client and SSR passes. That's the default. #444 set a value to what it already was.

2. The Shopify CLI overrides the config file. The server build receives sourcemap inline, and deploy hardcodes it to true:

// @shopify/cli/dist/chunk-AATUQ2AY.js
await Je({ directory: p, ..., sourcemap: !0, forceClientSourcemap: d, ... })

Inline config beats the config file in Vite, so the theme repo cannot turn this off from vite.config.ts.

Verified by building both ways:

main (no change):        dist/server/index.js.map  4,833,304 bytes
#444 applied:            dist/server/index.js.map  4,833,304 bytes
cmp → byte-identical

What actually works

The CLI owns the flag, so use the CLI's switch. Measured on this repo:

Build	server output	.map files	peak RSS
default	6.9 MB	1	1362 MB
SHOPIFY_HYDROGEN_FLAG_SOURCEMAP=false	2.3 MB	0	1136 MB

Server bundle drops by 4.6 MB, peak memory by ~226 MB (17%). npx shopify hydrogen build --no-sourcemap produces the same result; the env var is documented because it drops straight into the generated workflow next to NODE_OPTIONS.

Changes

README only. Documents SHOPIFY_HYDROGEN_FLAG_SOURCEMAP=false on the deploy step alongside the existing NODE_OPTIONS heap bump, and records why vite.config.ts can't solve it so the next person debugging an OOM doesn't retry the dead end.

No vite.config.ts change. No runtime behavior change.

Verification

• npm run biome — 324 files, 0 warnings
• Documented env var built end-to-end: exit 0, 0 .map files, server 2.3 MB

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2a1d6e4835

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use a deploy path that honors the sourcemap flag

In the generated Oxygen workflow where this step runs npx shopify hydrogen deploy, setting this env var does not affect the bundled @shopify/cli 4.5.2 deploy build: the command manifest registers SHOPIFY_HYDROGEN_FLAG_SOURCEMAP for hydrogen:build, but hydrogen:deploy has no sourcemap flag (node_modules/@shopify/cli/oclif.manifest.json:5854-5857, :6206), and deploy's internal build function still calls Je(..., sourcemap: !0, ...) (node_modules/@shopify/cli/dist/chunk-AATUQ2AY.js:132). Users following this README will still generate the server map and can still hit the Oxygen OOM, so the documented workaround needs to use a custom build/deploy path or a deploy option that is actually honored.

Useful? React with 👍 / 👎.