Merge branch 'main' into laura/orgs-471-update-docs-for-clerkexpo

docs/_partials/clerk-middleware-options.mdx

@@ -57,17 +57,17 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
 
   ---
 
-  - `signInUrl?`
+  - `signInUrl`
   - `string`
 
-  An alternative sign in URL.
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
 
   ---
 
-  - `signUpUrl?`
+  - `signUpUrl`
   - `string`
 
-  An alternative sign up URL.
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
 
   ---
 

docs/_partials/clerk-provider/properties.mdx

@@ -0,0 +1,229 @@
+{/* IsomorphicClerkOptions & children: React.ReactNode */}
+
+<Properties>
+  - `afterMultiSessionSingleSignOutUrl`
+  - `string`
+
+  The full URL or path to navigate to after a signing out from a currently active account in a multi-session app.
+
+  ---
+
+  - `afterSignOutUrl`
+  - `string`
+
+  The full URL or path to navigate to after a successful sign-out.
+
+  ---
+
+  - `allowedRedirectOrigins`
+  - `Array<string | RegExp>`
+
+  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.
+
+  ---
+
+  - `allowedRedirectProtocols`
+  - `Array<string>`
+
+  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.
+
+  ---
+
+  - `appearance`
+  - <code>[Appearance](/docs/customization/overview) | undefined</code>
+
+  Optional object to style your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
+
+  ---
+
+  - `clerkJSUrl`
+  - `string`
+
+  Define the URL that `@clerk/clerk-js` should be hot-loaded from.
+
+  ---
+
+  - `clerkJSVariant`
+  - `'headless' | ''`
+
+  If your web application only uses [control components](/docs/components/overview#control-components), you can set this value to `headless` and load a minimal ClerkJS bundle for optimal page performance.
+
+  ---
+
+  - `clerkJSVersion`
+  - `string`
+
+  Define the npm version for `@clerk/clerk-js`.
+
+  ---
+
+  - `domain`
+  - `string | ((url: URL) => boolean)`
+
+  **Required if your application is a satellite application.** Sets the domain of the satellite application.
+
+  ---
+
+  - `dynamic`
+  - `boolean`
+
+  (For Next.js only) Indicates whether or not Clerk should make dynamic auth data available based on the current request. Defaults to `false`. Opts the application into dynamic rendering when `true`. For more information, see [Next.js rendering modes and Clerk](/docs/references/nextjs/rendering-modes).
+
+  ---
+
+  - `initialState`
+  - `InitialState`
+
+  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](/docs/references/sdk/overview).
+
+  ---
+
+  - `isSatellite`
+  - `boolean | ((url: URL) => boolean)`
+
+  Whether the application is a satellite application.
+
+  ---
+
+  - `localization`
+  - <code>[Localization](/docs/customization/localization) | undefined</code>
+
+  Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
+
+  ---
+
+  - `nonce`
+  - `string`
+
+  This nonce value will be passed to the `@clerk/clerk-js` script tag. Use it to implement a [strict-dynamic CSP](/docs/security/clerk-csp#implementing-a-strict-dynamic-csp). Requires the `dynamic` prop to also be set.
+
+  ---
+
+  - `publishableKey`
+  - `string`
+
+  The Clerk Publishable Key for your instance. This can be found on the [**API keys**](https://dashboard.clerk.com/last-activepath=api-keys) page in the Clerk Dashboard.
+
+  ---
+
+  - `proxyUrl`
+  - `string | ((url: URL) => string)`
+
+  The URL that Clerk will proxy requests to. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
+
+  ---
+
+  - `routerPush`
+  - `(to: string) => Promise<unknown> | void`
+
+  A function which takes the destination path as an argument and performs a "push" navigation.
+
+  ---
+
+  - `routerReplace`
+  - `(to: string) => Promise<unknown> | void`
+
+  A function which takes the destination path as an argument and performs a "replace" navigation.
+
+  ---
+
+  - `sdkMetadata`
+  - `{ name: string; version: string; environment: string }`
+
+  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](/docs/references/sdk/overview).
+
+  ---
+
+  - `selectInitialSession`
+  - `(client: ClientResource) => ActiveSessionResource | null`
+
+  By default, the last active session is used during client initialization. This option allows you to override that behavior, e.g. by selecting a specific session.
+
+  ---
+
+  - `signInFallbackRedirectUrl`
+  - `string`
+
+  The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpFallbackRedirectUrl`
+  - `string`
+
+  The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signInForceRedirectUrl`
+  - `string`
+
+  If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpForceRedirectUrl`
+  - `string`
+
+  If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signInUrl`
+  - `string`
+
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpUrl`
+  - `string`
+
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `standardBrowser`
+  - `boolean`
+
+  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`.
+
+  ---
+
+  - `supportEmail`
+  - `string`
+
+  Optional support email for display in authentication screens. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages.
+
+  ---
+
+  - `syncHost`
+  - `string`
+
+  **Chrome Extension only** To enable, pass the URL of the web application that the extension will sync the authentication state from. See the [dedicated guide](/docs/references/chrome-extension/sync-host) for more information.
+
+  ---
+
+  - `telemetry`
+  - `false | { disabled: boolean; debug: boolean } | undefined`
+
+  Controls whether or not Clerk will collect [telemetry data](/docs/telemetry). If set to `debug`, telemetry events are only logged to the console and not sent to Clerk.
+
+  ---
+
+  - `touchSession`
+  - `boolean`
+
+  By default, [the Clerk Frontend API `touch` endpoint](/docs/reference/frontend-api/tag/Sessions#operation/touchSession){{ target: '_blank' }} is called during page focus to keep the last active session alive. This option allows you to disable this behavior.
+
+  ---
+
+  - `waitlistUrl`
+  - `string`
+
+  The full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist).
+</Properties>
+
+[components-ref]: /docs/components/overview
+
+[ap-ref]: /docs/customization/account-portal/overview

docs/_partials/hooks/use-auth.mdx

@@ -0,0 +1,24 @@
+The following example uses the `useAuth()` hook to access the current auth state, as well as helper methods to manage the current active session. The hook returns `userId`, which can be used to protect your routes.
+
+```tsx {{ filename: 'example.tsx' }}
+export default function Example() {
+  const { isLoaded, isSignedIn, userId, sessionId, getToken } = useAuth()
+
+  if (!isLoaded) {
+    return <div>Loading...</div>
+  }
+
+  if (!isSignedIn) {
+    // You could also add a redirect to the sign-in page here
+    return <div>Sign in to view this page</div>
+  }
+
+  return (
+    <div>
+      Hello, {userId}! Your current active session is {sessionId}.
+    </div>
+  )
+}
+```
+
+{/* TODO: Keep in sync with /tanstack-start/read-session-data and /expo/read-session-user-data */}

docs/_partials/hooks/use-user.mdx

@@ -0,0 +1,19 @@
+The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively.
+
+```tsx {{ filename: 'src/Example.tsx' }}
+export default function Example() {
+  const { isSignedIn, user, isLoaded } = useUser()
+
+  if (!isLoaded) {
+    return <div>Loading...</div>
+  }
+
+  if (!isSignedIn) {
+    return <div>Sign in to view this page</div>
+  }
+
+  return <div>Hello {user.firstName}!</div>
+}
+```
+
+{/* TODO: Keep in sync with /references/tanstack-start/read-session-data and /references/expo/read-session-user-data */}

docs/_partials/root-auth-loader.mdx

@@ -0,0 +1,99 @@
+The `rootAuthLoader()` function accepts an optional object. The following options are available:
+
+<Properties>
+  - `audience?`
+  - `string | string[]`
+
+  A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). If passed, it is checked against the `aud` claim in the token.
+
+  ---
+
+  - `authorizedParties?`
+  - `string[]`
+
+  An allowlist of origins to verify against, to protect your application from the subdomain cookie leaking attack.<br />For example: `['http://localhost:3000', 'https://example.com']`
+
+  ---
+
+  - `domain?`
+  - `string`
+
+  The domain used for satellites to inform Clerk where this application is deployed.
+
+  ---
+
+  - `isSatellite?`
+  - `boolean`
+
+  When using Clerk's satellite feature, this should be set to `true` for secondary domains.
+
+  ---
+
+  - `jwtKey`
+  - `string`
+
+  Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt).
+
+  ---
+
+  - `proxyUrl?`
+  - `string`
+
+  Specify the URL of the proxy, if using a proxy.
+
+  ---
+
+  - `publishableKey`
+  - `string`
+
+  The Clerk Publishable Key for your instance. This can be found in the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show Publishable Key** section in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
+
+  ---
+
+  - `secretKey?`
+  - `string`
+
+  The Clerk Secret Key for your instance. This can be found on the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) instead.
+
+  ---
+
+  - `signInUrl`
+  - `string`
+
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpUrl`
+  - `string`
+
+  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](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signInFallbackRedirectUrl?`
+  - `string`
+
+  The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpFallbackRedirectUrl?`
+  - `string`
+
+  The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signInForceRedirectUrl?`
+  - `string`
+
+  If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+
+  ---
+
+  - `signUpForceRedirectUrl?`
+  - `string`
+
+  If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+</Properties>