fix: render without random numbers, so Next.js 16 can prerender emails - #65

Summary

A new Next.js 16 app (create-next-app turns on Cache Components) can't build a page, GET route handler or Client Component that renders an email with 0.2.0. Next.js prerenders those at build time and fails the build when a render reads a random number. 0.2.0 asked crypto.getRandomValues() for each render's nonce (the marker that stops markup in a template's data from passing for one of the collecting render's markers). 0.1.22 builds the same pages.

The nonce now comes from a count of renders (shared by every copy of Elements in a process, as the collecting stack is) and performance's high-resolution clock, which Next.js leaves for timing. The nonce never reaches the output, so HTML, designs and plain text are unchanged.

Changes

• packages/react/src/utils/normalize.tsx: nonce() uses the render count and performance.timeOrigin / performance.now(). It reads no random numbers or date.
• packages/react/src/regression/render-isolation.test.tsx: a render calls no crypto.getRandomValues(), crypto.randomUUID(), Math.random() or Date.now() (fails on 0.2.0). An email renders the same where the clock stands still (fake timers) or there's no performance, and so does an email rendered inside one of its components.
• tests/next16-integration (new, in CI): Next.js 16.4 with Cache Components, where a route handler, a Server Component and a Client Component that render an email are prerendered and checked by verify.mjs. Its build fails with the published 0.2.0.
• .github/workflows/test.yml, CLAUDE.md, tests/nextjs-integration/verify.mjs: the new consumer step and its docs.
• packages/react/README.md: Waku's Server Components can't render emails, and no release of Elements can there.

Test Plan

• pnpm build passes; ESM bundle 117,988 bytes (budget 118,000)
• pnpm test passes (react 989, shared 107, convert-core 193, from-react-email 283, migrate 178), and with coverage
• Tested in Storybook: smoke test 138/138, visual drift 138 stories × 2 widths match the baseline
• Added/updated tests for new behavior (unit tests above; the new test fails without the fix)
• Typechecks, CSP gate (Node 20 and 24), browser runtime gate, browser E2E gate (27 sections), migration fidelity and differential checks
• Consumers with the packed tarball: Next.js 15, 14 and the new 16 (next build with Turbopack and with --webpack, and next dev), Jest 30
• Output against the published 0.2.0: byte-identical HTML, design, plain text and messages for 13 templates (the realistic examples plus edge cases: a component that throws, an async one, a nested render, markup in Columns, Page/Document roots) on React 18 and 19; designs and plain text still match 0.1.22; 5,000 generated templates (GENERATED_SEEDS=5000)
• Fresh apps with the fixed build next to the published 0.2.0, each rendering the same email: Next.js 16, Astro 7, TanStack Start, React Router 8, Vite 8, Waku (Client Components), Cloudflare Workers (with and without nodejs_compat), Express 5, Node + TypeScript (ESM and CommonJS), Bun, Deno, and Vitest 5 in node/jsdom/happy-dom with real timers, fake timers and a frozen performance. All renders were right and matched 0.2.0.

Notes

• The nonce's strength. It was 64 random bits; now it's the render count and the clock to a fraction of a millisecond. Data written before a render still can't know it: in Node it would mean guessing process start time and render time to the nanosecond. It's weaker where the clock is coarse or stands still (browsers round it; Workers read wall time with timeOrigin 0). A guessed nonce lets markup in a template's data rearrange or break that one render; it can't add markup beyond the raw HTML that data already puts there. Using crypto where Next.js hasn't wrapped it would mean detecting its wrapper, which could break with a Next.js update, and would go over the bundle budget.
• Bundle budget. 12 bytes are left under the 118 KB budget.
• Not in this PR. In Next.js Server Components and route handlers rendered on request, a component of the user's own that uses a hook is left out of the email (0.1.22 lost the whole Column). That's a separate issue.
• Users get the fix in the next release (0.2.1). After it, move @unlayer/react-elements-previous to it, per CLAUDE.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F9N7pEyxbxtqQmAw8BgEps

Generated by Claude Code

📖 Storybook Preview: https://unlayer.github.io/elements/pr/65/