fix(astro): accept single array child in unstyled buttons

[manovotny]

Description

Ports the @clerk/react fix from #8556 to @clerk/astro. Astro carries its own duplicate copy of assertSingleChild (marked // TODO-SHARED) that was not updated when the React-side fix landed.

Same root cause as #8556: when a custom button child crosses a Next-style server/client boundary, React can deliver it as a one-item array. React.Children.only() rejects that shape, which the SDK catches and surfaces as a misleading "multiple children" error to the user. The fix falls back to React.Children.toArray() and accepts a length-1 array of a valid element, preserving the genuine multi-child error path.

This benefits all seven astro unstyled buttons via the shared util: SignInButton, SignUpButton, SignOutButton, SignInWithMetamaskButton, CheckoutButton, SubscriptionDetailsButton, PlanDetailsButton.

Also adds the first React component tests to the astro package, mirroring the regression test from #8556 plus baseline coverage (default child, custom child, array-wrapped single child).

Checklist

• pnpm test runs as expected. (21/21 in @clerk/astro, including 3 new tests.)
• pnpm build runs as expected. (Full repo build not verified end-to-end — pre-existing failures in unrelated workspace packages, unrelated to this change.)
• (If applicable) JSDoc comments have been added or updated for any package exports — N/A, no public API surface change.
• (If applicable) Documentation has been updated — N/A, clerk-docs PR Add example for multiple children on <SignUpButton>/<SignInButton> components clerk-docs#3358 already covers the multi-child guidance.

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

References

• fix(react): accept single array child in unstyled buttons #8556 — original @clerk/react fix this ports
• https://www.reddit.com/r/nextjs/comments/1tcilsv/can_you_please_help_me_to_fix_an_error_from_clerk/ — user report and Jeff's explanation of the RSC boundary mechanism
• Add example for multiple children on <SignUpButton>/<SignInButton> components clerk-docs#3358 — related docs update on passing multiple children

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 15, 2026 5:59pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ff14fc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/astro	Patch

Not sure what this means? Click here to learn what changesets are.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: cb2bf55d-b78a-42cb-a19f-89d7a4058c4d

📥 Commits

Reviewing files that changed from the base of the PR and between b45777c and 0ff14fc.

📒 Files selected for processing (3)

• .changeset/astro-buttons-accept-one.md
• packages/astro/src/react/__tests__/SignInButton.test.tsx
• packages/astro/src/react/utils.tsx

---

📝 Walkthrough

Walkthrough

This PR fixes the Astro package's unstyled button components to accept a single React element passed as a one-item array. The assertSingleChild utility in utils.tsx now catches the error from React.Children.only() and checks if the converted array contains exactly one valid React element, returning it instead of treating it as a multiple-children error. A new test suite for SignInButton verifies the default button behavior, custom button children with their own click handlers, and the new one-item array scenario. A changeset entry documents this patch release.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• clerk/javascript#8556: Both PRs update the same assertSingleChild logic for unstyled button children to accept a one-item array as a valid single React element (and add corresponding SignInButton regression tests).

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The linked issue #39 concerns fixing Content-Type and User-Agent in @clerk/edge, which is completely unrelated to this PR about fixing array-wrapped children in @clerk/astro buttons.	The PR appears to address #8556 and other references, but the linked issue #39 is unrelated to these changes. Verify the correct linked issue is attached or remove the incorrect link.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(astro): accept single array child in unstyled buttons' clearly and specifically describes the main change: fixing unstyled Astro buttons to accept a single element passed as an array.
Description check	✅ Passed	The description provides detailed context about porting the React fix to Astro, explains the root cause and solution, lists affected components, and documents test coverage additions.
Out of Scope Changes check	✅ Passed	All changes align with the stated objective of porting the @clerk/react fix to @clerk/astro: updating assertSingleChild utility, adding regression tests, and adding baseline test coverage for unstyled buttons.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8561

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8561

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8561

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8561

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8561

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8561

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8561

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8561

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8561

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8561

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8561

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8561

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8561

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8561

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8561

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8561

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8561

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8561

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8561

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8561

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8561

commit: 0ff14fc