Skip to main content
Docs
Dashboard

Integration

The Clerk integration is required to integrate Clerk into your Astro application, providing session and user context to Clerk's hooks, nanostores, and components.

Usage

To configure Clerk with Astro, you must pass the clerk() integration to the integrations array in your astro.config.mjs file. The clerk() integration accepts optional options, such as { signInForceRedirectUrl: '/dashboard' }. See the properties section for more information.

Warning

For SSR, there is further configuration required. See the quickstart for more information.

astro.config.mjs
import { defineConfig } from 'astro/config'
import clerk from '@clerk/astro'

export default defineConfig({
  // Can accept options, such as { signInForceRedirectUrl: '/dashboard' }
  integrations: [clerk()],
})

Properties

  • Name
    afterMultiSessionSingleSignOutUrl?
    Type
    null | string
    Description

    The full URL or path to navigate to after signing out the current user is complete. This option applies to multi-session applications.

  • Name
    afterSignInUrl?
    Type
    null | string
    Description

    Deprecated. Use fallbackRedirectUrl or forceRedirectUrl instead.

  • Name
    afterSignOutUrl?
    Type
    null | string
    Description

    Full URL or path to navigate to after successful sign out.

  • Name
    afterSignUpUrl?
    Type
    null | string
    Description

    Deprecated. Use fallbackRedirectUrl or forceRedirectUrl instead.

  • Name
    allowedRedirectOrigins?
    Type
    (string | RegExp)[]
    Description

    An optional array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    allowedRedirectProtocols?
    Type
    string[]
    Description

    An optional array of protocols to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    appearance?
    Type
    Appearance
    Description

    Optional object to style your components. Will only affect Clerk Components and not Account Portal pages.

  • Name
    clerkJSUrl?
    Type
    string
    Description

    The URL that @clerk/clerk-js should be hot-loaded from.

  • Name
    clerkJSVariant?
    Type
    "" | "headless"
    Description

    If your web application only uses Control Components, you can set this value to 'headless' and load a minimal ClerkJS bundle for optimal page performance.

  • Name
    clerkJSVersion?
    Type
    string
    Description

    The npm version for @clerk/clerk-js.

  • Name
    domain?
    Type
    string | (url) => string
    Description

    Required if your application is a satellite application. Sets the domain of the satellite application.

  • Name
    experimental?
    Type
    Autocomplete<{ commerce: boolean; persistClient: boolean; rethrowOfflineNetworkErrors: boolean; }, Record<string, any>>
    Description

    Enable experimental flags to gain access to new features. These flags are not guaranteed to be stable and may change drastically in between patch or minor versions.

  • Name
    initialState?
    Type
    Serializable<{ actor: undefined | { [x: string]: unknown; sub: string; }; factorVerificationAge: [number, number]; organization: undefined | OrganizationResource; orgId: undefined | string; orgPermissions: undefined | string[]; orgRole: undefined | string; orgSlug: undefined | string; session: undefined | SessionResource; sessionClaims: JwtPayload; sessionId: undefined | string; sessionStatus: SessionStatusClaim; user: undefined | UserResource; userId: undefined | string; }>
    Description

    Provide an initial state of the Clerk client during server-side rendering. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    isSatellite?
    Type
    boolean | (url) => boolean
    Description

    A boolean that indicates whether the application is a satellite application.

  • Name
    localization?
    Type
    DeepPartial<Localization>
    Description

    Optional object to localize your components. Will only affect Clerk Components and not Account Portal pages.

  • Name
    newSubscriptionRedirectUrl?
    Type
    null | string
    Description

    The URL to navigate to after the user completes the checkout and clicks the "Continue" button.

  • Name
    nonce?
    Type
    string
    Description

    This nonce value will be passed through to the @clerk/clerk-js script tag. Use it to implement a strict-dynamic CSP. Requires the dynamic prop to also be set.

  • Name
    proxyUrl?
    Type
    string | (url) => string | (url) => string
    Description

    Required for applications that run behind a reverse proxy. The URL that Clerk will proxy requests to. Can be either a relative path (/__clerk) or a full URL (https://<your-domain>/__clerk).

  • Name
    publishableKey
    Type
    string
    Description

    The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.

  • Name
    redirectUrl?
    Type
    null | string
    Description

    Deprecated. Use fallbackRedirectUrl or forceRedirectUrl instead.

  • Name
    routerPush?
    Type
    (to, metadata?) => unknown
    Description

    A function which takes the destination path as an argument and performs a "push" navigation.

  • Name
    routerReplace?
    Type
    (to, metadata?) => unknown
    Description

    A function which takes the destination path as an argument and performs a "replace" navigation.

  • Name
    sdkMetadata?
    Type
    { environment?: string; name: string; version: string; }
    Description

    Contains information about the SDK that the host application is using. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    sdkMetadata.environment?
    Type
    string
    Description

    Typically this will be the NODE_ENV that the SDK is currently running in.

  • Name
    sdkMetadata.name
    Type
    string
    Description

    The npm package name of the SDK.

  • Name
    sdkMetadata.version
    Type
    string
    Description

    The npm package version of the SDK.

  • Name
    selectInitialSession?
    Type
    (client) => null | SignedInSessionResource
    Description

    By default, the last signed-in session is used during client initialization. This option allows you to override that behavior, e.g. by selecting a specific session.

  • Name
    signInFallbackRedirectUrl?
    Type
    null | string
    Description

    The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.

  • Name
    signInForceRedirectUrl?
    Type
    null | string
    Description

    This URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.

  • Name
    signInUrl?
    Type
    string
    Description

    This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It is required to be set for a satellite application in a development instance. It's recommended to use the environment variable instead.

  • Name
    signUpFallbackRedirectUrl?
    Type
    null | string
    Description

    The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. It's recommended to use the environment variable instead. Defaults to '/'.

  • Name
    signUpForceRedirectUrl?
    Type
    null | string
    Description

    This URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.

  • Name
    signUpUrl?
    Type
    string
    Description

    This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances but must be set for a satellite application in a development instance. It's recommended to use the environment variable instead.

  • Name
    standardBrowser?
    Type
    boolean
    Description

    By default, ClerkJS is loaded with the assumption that cookies can be set (browser setup). On native platforms this value must be set to false.

  • Name
    supportEmail?
    Type
    string
    Description

    Optional support email for display in authentication screens. Will only affect Clerk Components and not Account Portal pages.

  • Name
    telemetry?
    Type
    false | { debug?: boolean; disabled?: boolean; }
    Description

    Controls whether or not Clerk will collect telemetry data. If set to debug, telemetry events are only logged to the console and not sent to Clerk.

  • Name
    touchSession?
    Type
    boolean
    Description

    By default, the Clerk Frontend API touch endpoint is called during page focus to keep the last active session alive. This option allows you to disable this behavior.

  • Name
    treatPendingAsSignedOut?
    Type
    boolean
    Description

    A boolean that indicates whether pending sessions are considered as signed out or not. Defaults to true.

  • Name
    waitlistUrl?
    Type
    string
    Description

    The full URL or path to the waitlist page. If undefined, will redirect to the Account Portal waitlist page.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on