chore(docs): note tsup + emitDecoratorMetadata gotcha for render

[mvanhorn]

Summary

Document the tsup + emitDecoratorMetadata build gotcha on the Render utility page so backend users hitting ReferenceError: React is not defined in production bundles have somewhere to land.

Why this matters

Issue #3177 reports the failure mode and explicitly frames it as "worth a docs mention since it affects an unrelated tsconfig flag." The chain is:

• emitDecoratorMetadata: true makes tsup route .tsx through SWC instead of esbuild (egoist/tsup#792)
• SWC defaults to the classic JSX runtime, so the output emits React.createElement calls
• Combined with the recommended external: ["react"], the bundle references React without importing it

This affects any TS project that needs runtime decorator metadata (NestJS, type-graphql, TypeORM).

Changes

A new section at the end of apps/docs/utilities/render.mdx: failure symptom, the SWC routing chain, three mitigations (automatic JSX runtime, drop the external for the affected entry, or force tsup back to esbuild for .tsx), and a link to the upstream tsup issue.

Testing

pnpm lint passes (one pre-existing warning unrelated to this change). Mintlify validation against the local Node version was blocked by the LTS requirement; the section uses standard markdown that Mintlify renders verbatim.

Fixes #3177

---

Summary by cubic

Added a Troubleshooting guide for the tsup + emitDecoratorMetadata gotcha that makes render() fail with ReferenceError: React is not defined in production. It’s linked from render() and appears under the docs sidebar’s “Troubleshooting”; the guide explains the SWC + classic JSX with external: ["react"] cause and three fixes: switch to the automatic JSX runtime, remove the external for that entry, or force .tsx back to esbuild (fixes #3177).

^{Written for commit 2afb57e. Summary will update on new commits. Review in cubic}

[vercel]

@mvanhorn is attempting to deploy a commit to the resend Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2afb57e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Auto-approved: Documentation-only change adding a note about tsup and decorator metadata gotcha. No code, config, or logic changes. Low risk.}

[mvanhorn]

Pushed 525dcf0 in response to your common-problems suggestion:

• Created apps/docs/guides/common-problems/tsup-decorator-metadata.mdx with the gotcha content reorganized as Symptom / Cause / Fix.
• Wired a new Common Problems group into docs.json under Guides (next to Internationalization, with the circle-exclamation icon).
• The render page now ends with a short ## Common problems pointer to the new guide instead of carrying the section inline, so the subsection can grow with future entries.

Let me know if you'd rather the guide live under a different parent (e.g. top-level Troubleshooting tab) or want a different page title.

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Auto-approved: All changes are documentation-only: new guide, sidebar entry, and a link. No code or config changes affect runtime behavior. Low risk.}

[dielduarte]

Hey @mvanhorn, let's get this one to the finish line too, Sorry for the delay!

I think a "troubleshooting" group/section would be easier to find when searching. Can you rename it instead of "common problems" I can also do that, just let me know!

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Auto-approved: This is purely a documentation update adding a troubleshooting guide for a build-time issue, with no changes to application logic, infrastructure, or dependencies.
Re-trigger cubic}

[mvanhorn]

Done in 2afb57e — renamed the group to Troubleshooting, moved the guide to guides/troubleshooting/, and updated the cross-reference in utilities/render.mdx. grep -rn "common-problems\|Common Problems" apps/docs/ is clean.

Ready for another pass whenever.