fix(astro): avoid invalid ui constructor in injected scripts

[jescalan]

Summary

Fix two Astro integration initialization paths that could pass an invalid ui.ClerkUI value into clerk.load():

import clerk from "@clerk/astro";
import { ui } from "@clerk/ui";

clerk({ ui });

The bundled UI path was serializing injected script params with JSON.stringify(...), which strips ui.ClerkUI because it is a constructor. The client-side initialization then saw options.ui, skipped CDN UI loading, and passed an object without a usable ClerkUI constructor into clerk.load().

The prefetchUI: false path had a related issue: Astro returned Promise<undefined> from the UI resolver, then passed that promise as ui.ClerkUI. clerk-js treats the promise object as truthy and later attempts to instantiate the resolved undefined value.

This PR now:

• imports the live bundled ui object from @clerk/ui in injected snippets when the Astro integration is configured with ui
• returns plain undefined, not Promise<undefined>, for no-UI paths like prefetchUI: false and UI marker objects without constructors
• keeps default/non-bundled snippets on the previous serialized behavior

Testing

• pnpm --filter @clerk/astro test -- src/internal/__tests__/create-clerk-instance.test.ts src/integration/__tests__/snippets.test.ts
• pnpm --filter @clerk/astro lint (passes with existing warnings)
• pnpm exec prettier --check packages/astro/src/internal/create-clerk-instance.ts packages/astro/src/internal/__tests__/create-clerk-instance.test.ts packages/astro/src/integration/snippets.ts packages/astro/src/integration/__tests__/snippets.test.ts .changeset/astro-bundled-ui-serialization.md
• git diff --check

Note: pnpm --filter @clerk/astro format:check still fails on pre-existing copied components/**/*.astro formatting issues, but it does not flag the files touched in this PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: 50d8e7d

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

[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 22, 2026 6:59pm

[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: 2072108d-9197-403c-a504-324969b205cd

📥 Commits

Reviewing files that changed from the base of the PR and between 03636db and 50d8e7d.

📒 Files selected for processing (5)

• .changeset/astro-bundled-ui-serialization.md
• packages/astro/src/integration/__tests__/snippets.test.ts
• packages/astro/src/integration/snippets.ts
• packages/astro/src/internal/__tests__/create-clerk-instance.test.ts
• packages/astro/src/internal/create-clerk-instance.ts

✅ Files skipped from review due to trivial changes (1)

• .changeset/astro-bundled-ui-serialization.md

---

📝 Walkthrough

Walkthrough

This PR adds a helper that serializes internal initialization params and, when ui is present, emits an @clerk/ui import and rewrites ui to reference the imported symbol. Both buildBeforeHydrationSnippet and buildPageLoadSnippet use the helper to inject computed imports and params into runInjectionScript (page-load adds router callbacks in the View Transitions path). The internal getClerkUIEntryChunk loader was refactored to return constructor|promise|undefined and delegate remote loading to loadClerkUIEntryChunk. Tests and a changeset were added.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main fix: avoiding invalid ui constructor in injected scripts, which directly addresses the core problem described in the PR.
Description check	✅ Passed	The description thoroughly explains the problem, solution, and testing approach, all directly related to the bundled UI serialization fix in the Astro integration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

_{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@8628

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 50d8e7d