// astro.config.mjs
import { defineConfig } from 'astro/config';
import clerk from '@clerk/astro'; // or: import clerk from './source/astro/src/index.ts'

export default defineConfig({
  integrations: [clerk()],
  output: 'server', // required for SSR session handling
});

3. Set environment variables (create .env at project root):

PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Ensure tsconfig.json includes path aliases if consuming source directly:

{
  "compilerOptions": {
    "paths": {
      "@clerk/astro": ["./source/astro/src/index.ts"],
      "@clerk/astro/components": ["./source/astro/src/astro-components/index.ts"]
    }
  }
}

5. Add middleware to src/middleware.ts (Clerk requires it for SSR):

export { onRequest } from '@clerk/astro/server';

Public API

createIntegration (default export of astro/src/index.ts)

import createIntegration from './source/astro/src/integration/create-integration';

const clerkIntegration: AstroIntegration = createIntegration();

This factory is the Astro integration entry point. It registers Vite plugins, injects the Clerk client-side script, and wires server-side session context into every Astro request. Pass it directly to the integrations array in astro.config.mjs.

OrganizationProfile

import { OrganizationProfile } from './source/astro/src/astro-components/index.ts';

// Sub-components:
// OrganizationProfile       - root component
// OrganizationProfile.Page  - custom page slot
// OrganizationProfile.Link  - custom link slot

Renders Clerk's full organization profile management UI as an Astro component. Use .Page and .Link sub-components to inject custom tabs or navigation links into the profile panel.

UserButton

import { UserButton } from './source/astro/src/astro-components/index.ts';

// Sub-components:
// UserButton.MenuItems       - wrapper for custom menu entries
// UserButton.Link            - custom link item in the dropdown
// UserButton.Action          - custom action item in the dropdown
// UserButton.UserProfilePage - custom page inside user profile modal

Renders the signed-in user avatar button with a dropdown. Extend it with .MenuItems, .Link, and .Action sub-components to add custom navigation or actions alongside Clerk's defaults. .UserProfilePage adds a custom tab inside the embedded User Profile modal.

OrganizationSwitcher

import { OrganizationSwitcher } from './source/astro/src/astro-components/index.ts';

// Sub-components:
// OrganizationSwitcher.OrganizationProfilePage
// OrganizationSwitcher.OrganizationProfileLink

Renders a dropdown that lets users switch between organizations or create new ones. Extend with .OrganizationProfilePage and .OrganizationProfileLink to embed custom pages or links inside the organization profile panel that opens from the switcher.

Working examples

Scenario - Basic sign-in / sign-up buttons in a layout

Place unstyled trigger buttons in a shared Astro layout. Clerk manages the redirect flow automatically.

---
// src/layouts/BaseLayout.astro
import { SignInButton, SignUpButton, SignOutButton, Show } from '@clerk/astro/components';
---

<header>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <SignOutButton />
  </Show>
</header>
<slot />

Scenario - Embedding the full UserButton with a custom menu link

---
// src/components/AppHeader.astro
import { UserButton } from '@clerk/astro/components';
---

<nav>
  <UserButton>
    <UserButton.MenuItems>
      <UserButton.Link
        label="Dashboard"
        labelIcon="dashboard-icon"
        href="/dashboard"
      />
      <UserButton.Action label="Help" labelIcon="help-icon" onClick="openHelp" />
    </UserButton.MenuItems>
  </UserButton>
</nav>

Scenario - Organization management with custom profile page

---
// src/pages/org-profile.astro
import { OrganizationProfile } from '@clerk/astro/components';
---

<OrganizationProfile>
  <OrganizationProfile.Page label="Billing" url="billing">
    <!-- custom billing UI rendered inside the profile modal -->
    <h2>Billing Settings</h2>
    <p>Manage your subscription here.</p>
  </OrganizationProfile.Page>
  <OrganizationProfile.Link label="Back to App" url="/" />
</OrganizationProfile>

Scenario - Protecting a server-rendered page with session check

---
// src/pages/protected.astro
import { auth } from '@clerk/astro/server';

const { userId } = auth();
if (!userId) {
  return Astro.redirect('/sign-in');
}
---

<h1>Welcome, {userId}</h1>

File walkthrough

• astro/src/index.ts - Package entry; exports the result of createIntegration() as the default Astro integration.
• astro/src/integration/create-integration.ts - Builds the AstroIntegration object, registers Vite plugins and hooks.
• astro/src/integration/snippets.ts - Code snippets injected into the user's Astro project by the integration.
• astro/src/integration/vite-plugin-astro-config.ts - Vite plugin that reads and patches the Astro config for Clerk.
• astro/src/astro-components/index.ts - Barrel re-exporting all Astro UI and control components.
• astro/src/astro-components/control/ - Gate components (Show, AuthenticateWithRedirectCallback) for conditional rendering.
• astro/src/astro-components/interactive/ - Full Clerk UI components (SignIn, SignUp, UserButton, UserProfile, OrganizationProfile, OrganizationSwitcher, etc.).
• astro/src/astro-components/unstyled/ - Headless trigger buttons (SignInButton, SignUpButton, SignOutButton, etc.).
• astro/src/internal/create-clerk-instance.ts - Manages a singleton Clerk instance for SSR contexts.
• astro/src/internal/create-injection-script-runner.ts - Handles client-side script injection for hydration.
• astro/src/client/index.ts - Client-side exports (store subscriptions, reactive auth state).
• astro/src/server/ - Server-side auth helpers (auth(), currentUser(), middleware utilities).
• astro/src/stores/ - Nano-store bindings for reactive Clerk state in Astro islands.
• astro/src/types/ - Shared TypeScript types and interfaces for the Astro SDK.
• astro/src/utils/ - Internal utility functions.
• astro/src/async-local-storage.server.ts - Node.js AsyncLocalStorage adapter for per-request auth context.
• astro/src/async-local-storage.client.ts - No-op client stub matching the server adapter's interface.
• astro/src/webhooks.ts - Clerk webhook verification helpers for Astro API routes.

Common pitfalls and fixes

• Missing output: 'server': Clerk's SSR session detection requires server rendering; add output: 'server' (or 'hybrid') in astro.config.mjs.
• PUBLIC_CLERK_PUBLISHABLE_KEY not picked up: Astro only exposes env vars prefixed with PUBLIC_ to the client; use the exact prefix and restart the dev server after adding it.
• Middleware not registered: Clerk auth context is injected via middleware; if src/middleware.ts does not re-export onRequest from @clerk/astro/server, all auth() calls return null.
• React islands not hydrating: Components using UserButton or OrganizationProfile as React islands need @astrojs/react installed and configured, and must use a client:* directive.
• ESM/CJS interop errors with @clerk/backend: Ensure "moduleResolution": "bundler" or "node16" in tsconfig.json; older "node" resolution misses package export maps.
• Webhook signature verification fails: Ensure the raw request body (not parsed JSON) is passed to the webhook helper; Astro's request.json() consumes the stream and breaks signature checks - use request.text() instead.

Vibe-coding prompt template

I have dropped the Clerk JavaScript SDK source into `source/` in my project root,
and I have a `USAGE.md` file at the same level that documents the real exports and setup steps.

Upstream npm package: @clerk/javascript (Astro SDK under source/astro/).

Please help me integrate Clerk authentication into my existing Astro project step by step:

1. Read `USAGE.md` and `source/astro/src/astro-components/index.ts` to understand what
   components are available.
2. Update `astro.config.mjs` to register the Clerk integration from
   `source/astro/src/index.ts`.
3. Create `src/middleware.ts` that exports `onRequest` from the Clerk server module.
4. Add `PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` to `.env`.
5. Add a `<UserButton />` to my existing header component and protect `/dashboard`
   by checking `auth().userId` server-side, redirecting to `/sign-in` if absent.
6. Show me only real imports from the exports listed in `USAGE.md`. Do not invent
   component names or props not shown there.

License and credit

The Clerk JavaScript SDK is released under the MIT license. See source/astro/LICENSE for the full license text. Upstream repository and documentation: https://github.com/clerk/javascript / https://clerk.com/docs.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。