feat(clerk-react,nextjs): Speed up clerk-js loading by using a <script/> tag

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };

.changeset/serious-balloons-eat.md

@@ -0,0 +1,9 @@
+---
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+---
+
+Speed up loading of clerk-js by using a `<script/>` tag when html is generated.
+This is supported during SSR, SSG in
+- Next.js Pages Router
+- Next.js App Router

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useTransition } from 'react';
 import { ClerkNextOptionsProvider } from '../../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../../types';
+import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
@@ -73,7 +74,10 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
 
  return (
  <ClerkNextOptionsProvider options={mergedProps}>
- <ReactClerkProvider {...mergedProps}>{children}</ReactClerkProvider>
+ <ReactClerkProvider {...mergedProps}>
+ <ClerkJSScript router='app' />
+ {children}
+ </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );
 };

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -7,8 +7,10 @@ import React from 'react';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import { useSafeLayoutEffect } from '../client-boundary/useSafeLayoutEffect';
 import type { NextClerkProviderProps } from '../types';
+import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 
 export function ClerkProvider({ children, ...props }: NextClerkProviderProps): JSX.Element {
@@ -45,6 +47,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
  {...mergedProps}
  initialState={initialState}
  >
+ <ClerkJSScript router='pages' />
  {children}
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>

packages/nextjs/src/utils/clerk-js-script.tsx

@@ -0,0 +1,47 @@
+import { useClerk } from '@clerk/clerk-react';
+import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import NextScript from 'next/script';
+import React from 'react';
+
+import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
+
+type ClerkJSScriptProps = {
+ router: 'app' | 'pages';
+};
+
+function ClerkJSScript(props: ClerkJSScriptProps) {
+ const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant } = useClerkNextOptions();
+ const { domain, proxyUrl } = useClerk();
+ const options = {
+ domain,
+ proxyUrl,
+ publishableKey: publishableKey!,
+ clerkJSUrl,
+ clerkJSVersion,
+ clerkJSVariant,
+ };
+ const scriptUrl = clerkJsScriptUrl(options);
+
+ /**
+ * Notes:
+ * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
+ * Nextjs App Router will automatically move inline scripts inside `<head/>`
+ * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
+ */
+ const Script = props.router === 'app' ? 'script' : NextScript;
+
+ return (
+ <Script
+ src={scriptUrl}
+ data-clerk-js-script
+ async
+ // `nextjs/script` will add defer by default and does not get removed when we async is true
+ defer={props.router === 'pages' ? false : undefined}
+ crossOrigin='anonymous'
+ strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
+ {...buildClerkJsScriptAttributes(options)}
+ />
+ );
+}
+
+export { ClerkJSScript };

packages/react/src/internal.ts

@@ -1,3 +1,5 @@
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
+
+export { clerkJsScriptUrl, buildClerkJsScriptAttributes } from './utils/loadClerkJsScript';

packages/react/src/utils/loadClerkJsScript.ts

@@ -11,17 +11,31 @@ import { versionSelector } from './versionSelector';
 const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
 
 type LoadClerkJsScriptOptions = Omit<IsomorphicClerkOptions, 'proxyUrl' | 'domain'> & {
- proxyUrl: string;
- domain: string;
+ proxyUrl?: string;
+ domain?: string;
 };
 
-export const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
+const loadClerkJsScript = (opts: LoadClerkJsScriptOptions) => {
  const { publishableKey } = opts;
 
  if (!publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
+ const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+
+ if (existingScript) {
+ return new Promise((resolve, reject) => {
+ existingScript.addEventListener('load', () => {
+ resolve(existingScript);
+ });
+
+ existingScript.addEventListener('error', () => {
+ reject(FAILED_TO_LOAD_ERROR);
+ });
+ });
+ }
+
  return loadScript(clerkJsScriptUrl(opts), {
  async: true,
  crossOrigin: 'anonymous',
@@ -52,17 +66,30 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
  return `https://${scriptHost}/npm/@clerk/clerk-js@${version}/dist/clerk.${variant}browser.js`;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
- const { publishableKey, proxyUrl, domain } = options;
- if (publishableKey) {
- script.setAttribute('data-clerk-publishable-key', publishableKey);
+const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
+ const obj: Record<string, string> = {};
+
+ if (options.publishableKey) {
+ obj['data-clerk-publishable-key'] = options.publishableKey;
  }
 
- if (proxyUrl) {
-script.setAttribute('data-clerk-proxy-url', proxyUrl);
+ if (options.proxyUrl) {
+obj['data-clerk-proxy-url'] = options.proxyUrl;
  }
 
- if (domain) {
- script.setAttribute('data-clerk-domain', domain);
+ if (options.domain) {
+ obj['data-clerk-clerk-domain'] = options.domain;
+ }
+
+ return obj;
+};
+
+const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
+ const attributes = buildClerkJsScriptAttributes(options);
+ for (const attribute in attributes) {
+ script.setAttribute(attribute, attributes[attribute]);
  }
 };
+
+export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export type { LoadClerkJsScriptOptions };