diff --git a/docs/_partials/control-components-with-expo.mdx b/docs/_partials/control-components-with-expo.mdx new file mode 100644 index 0000000000..72f5d870e9 --- /dev/null +++ b/docs/_partials/control-components-with-expo.mdx @@ -0,0 +1,213 @@ + + + + ```tsx {{ filename: 'app/page.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/nextjs' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Page() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + ```tsx {{ filename: 'pages/index.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/nextjs' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Page() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + + ```tsx {{ filename: 'app/index.tsx' }} + import { ClerkLoading, ClerkLoaded } from '@clerk/clerk-expo' + import { Text, View } from 'react-native' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Screen() { + return ( + + + Clerk is loading + + + Clerk has loaded (ready or degraded) + + + + ) + } + ``` + + + + ```tsx {{ filename: 'example.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/clerk-react' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/react-router' + + export default function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'routes/index.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/remix' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Index() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/example')({ + component: Example, + }) + + function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + diff --git a/docs/_partials/control-components-without-expo.mdx b/docs/_partials/control-components-without-expo.mdx new file mode 100644 index 0000000000..b52605b839 --- /dev/null +++ b/docs/_partials/control-components-without-expo.mdx @@ -0,0 +1,186 @@ + + + + ```tsx {{ filename: 'app/page.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/nextjs' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Page() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + ```tsx {{ filename: 'pages/index.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/nextjs' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Page() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + + ```tsx {{ filename: 'example.tsx' }} + import { ClerkLoaded, ClerkLoading, ClerkDegraded, ClerkFailed } from '@clerk/clerk-react' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/react-router' + + export default function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'routes/index.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/remix' + + declare global { + interface Window { + Clerk: any + } + } + + export default function Index() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoading, ClerkLoaded, ClerkDegraded, ClerkFailed } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/example')({ + component: Example, + }) + + function Example() { + return ( + <> + +

Clerk is loading...

+ + +

Clerk has loaded (ready or degraded)

+ + +

Clerk is experiencing issues. Please try again later.

+ + + +

Something went wrong with Clerk. Please contact support.

+ + + ) + } + ``` + + diff --git a/docs/components/control/clerk-degraded.mdx b/docs/components/control/clerk-degraded.mdx new file mode 100644 index 0000000000..b608cef1e4 --- /dev/null +++ b/docs/components/control/clerk-degraded.mdx @@ -0,0 +1,12 @@ +--- +title: '``' +description: The `` component indicates that Clerk is partially operational. +--- + +The `` component indicates that Clerk is partially operational. + +## Usage + +It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. + + diff --git a/docs/components/control/clerk-failed.mdx b/docs/components/control/clerk-failed.mdx new file mode 100644 index 0000000000..a018f2646a --- /dev/null +++ b/docs/components/control/clerk-failed.mdx @@ -0,0 +1,12 @@ +--- +title: '``' +description: The `` component indicates that the Clerk object has failed to load. +--- + +The `` component indicates that the Clerk object has failed to load. This is useful for displaying an error message to the user. + +## Usage + +It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. + + diff --git a/docs/components/control/clerk-loaded.mdx b/docs/components/control/clerk-loaded.mdx index 583604a200..9432c247b8 100644 --- a/docs/components/control/clerk-loaded.mdx +++ b/docs/components/control/clerk-loaded.mdx @@ -3,103 +3,10 @@ title: '``' description: The `` component guarantees that the Clerk object has loaded and will be available under `window.Clerk`. This allows you to wrap child components to access the Clerk object without the need to check it exists. --- -The `` component guarantees that the Clerk object has loaded and will be available under `window.Clerk`. This allows you to wrap child components to access the `Clerk` object without the need to check it exists. +The `` component guarantees that the Clerk object has loaded (the `status` is `'ready'` or `'degraded'`) and will be available under `window.Clerk`. This allows you to wrap child components to access the `Clerk` object without the need to check it exists. ## Usage It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. - - - - - ```tsx {{ filename: 'app/page.tsx' }} - import { ClerkLoaded } from '@clerk/nextjs' - - export default function Page() { - return ( - -

Clerk has loaded

- - - ) - } - ``` - - - - ```tsx {{ filename: 'pages/index.tsx' }} - import { ClerkLoaded } from '@clerk/nextjs' - - export default function Page() { - return ( - -

Clerk has loaded

- - - ) - } - ``` - - - - - - ```tsx {{ filename: 'example.tsx' }} - import { ClerkLoaded } from '@clerk/clerk-react' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Example() { - return ( - -

Clerk has loaded

- - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { ClerkLoaded } from '@clerk/remix' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Index() { - return ( -
- -

Clerk has loaded

- -
- ) - } - ``` - - - - ```tsx {{ filename: 'app/index.tsx' }} - import { ClerkLoaded } from '@clerk/clerk-expo' - import { Text, View } from 'react-native' - - export default function Screen() { - return ( - - - Clerk has loaded - - - ) - } - ``` - - + diff --git a/docs/components/control/clerk-loading.mdx b/docs/components/control/clerk-loading.mdx index 06918ed818..2467c10bf5 100644 --- a/docs/components/control/clerk-loading.mdx +++ b/docs/components/control/clerk-loading.mdx @@ -9,130 +9,4 @@ The `` renders its children while Clerk is loading, and is helpful It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. - - - - ```tsx {{ filename: 'app/page.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Page() { - return ( - <> - -

Clerk is loading...

- - -

Clerk has loaded

- - - ) - } - ``` - - ```tsx {{ filename: 'pages/index.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Page() { - return ( - <> - -

Clerk is loading

- - -

Clerk has loaded

- - - ) - } - ``` - - - - - ```tsx {{ filename: 'example.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/clerk-react' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Example() { - return ( - <> - -

Clerk is loading

- - -

Clerk has loaded

- - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { ClerkLoading, ClerkLoaded } from '@clerk/remix' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Index() { - return ( - <> - -

Clerk is loading

- - -

Clerk has loaded

- - - ) - } - ``` - - - - ```tsx {{ filename: 'app/index.tsx' }} - import { ClerkLoading, ClerkLoaded } from '@clerk/clerk-expo' - import { Text, View } from 'react-native' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Screen() { - return ( - - - Clerk is loading - - - Clerk has loaded - - - ) - } - ``` - - + diff --git a/docs/manifest.json b/docs/manifest.json index f041af969e..8dfb2e3fde 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2049,6 +2049,16 @@ "wrap": false, "href": "/docs/components/control/authenticate-with-callback" }, + { + "title": "``", + "wrap": false, + "href": "/docs/components/control/clerk-degraded" + }, + { + "title": "``", + "wrap": false, + "href": "/docs/components/control/clerk-failed" + }, { "title": "``", "wrap": false, diff --git a/docs/references/javascript/clerk.mdx b/docs/references/javascript/clerk.mdx index 7f87209cef..29cf60bd8b 100644 --- a/docs/references/javascript/clerk.mdx +++ b/docs/references/javascript/clerk.mdx @@ -8,52 +8,73 @@ The `Clerk` class is the main entrypoint class for the `@clerk/clerk-js` package ## Properties - - `version` + - `client` + - [`Client`][client-ref] + + The `Client` object for the current window. + + --- + + - `domain` - `string` - A getter for the Clerk SDK version + The current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server. --- - - `loaded` - - `boolean` + - `instanceType` + - `'production' | 'development'` - A getter to see if the `Clerk` object is ready for use or not + Indicates if the Clerk instance is running in production or development mode. --- - `isSatellite` - `boolean` - Clerk Flag for satellite apps + A boolean that indicates if the instance is a satellite app. --- - - `domain` - - `string` + - `isSignedIn` + - `boolean` + + A boolean that indicates if the user is signed in. + + --- + + - `loaded` + - `boolean` + + A boolean that indicates if the `Clerk` object is ready for use. Set to `false` when the `status` is `'loading'` or `'error'`. Set to `true` when the `status` is either `'ready'` or `'degraded'`. + + --- - A getter for the current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server + - `organization` + - [Organization][organization-ref] | null | undefined + + A shortcut to the last active `Session.user.organizationMemberships` which holds an instance of a `Organization` object. If the session is `null` or `undefined`, the user field will match. --- - `proxyUrl` - `string` - A getter for your Clerk app's proxy URL. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https:///__clerk`). + Your Clerk app's proxy URL. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https:///__clerk`). --- - - `instanceType` - - `'production' | 'development'` + - `publishableKey` + - `string | undefined` - A getter to see if a Clerk instance is running in production or development mode + The Clerk Publishable 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. --- - - `client` - - [`Client`][client-ref] + - `sdkMetadata` + - `{ name: string; version: string; environment: string }` - The `Client` object for the current window. + 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). --- @@ -64,24 +85,36 @@ The `Clerk` class is the main entrypoint class for the `@clerk/clerk-js` package --- - - `user` - - [User][user-ref] | null | undefined + - `status` + - `'degraded' | 'error' | 'loading' | 'ready'` - A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match. + The status of the Clerk instance. Possible values are: + + - `'degraded'`: Set when Clerk is partially operational. + - `'error'`: Set when hotloading `clerk-js` failed or `Clerk.load()` failed. + - `'loading'`: Set during initialization. + - `'ready'`: Set when Clerk is fully operational. --- - - `organization` - - [Organization][organization-ref] | null | undefined + - `telemetry?` + - `{ disabled: boolean, debug: boolean }` - A shortcut to the last active `Session.user.organizationMemberships` which holds an instance of a `Organization` object. If the session is `null` or `undefined`, the user field will match. + [Telemetry](/docs/telemetry) configuration. --- - - `publishableKey` - - `string | undefined` + - `user` + - [User][user-ref] | null | undefined - The Clerk Publishable 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. + A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match. + + --- + + - `version` + - `string` + + The Clerk SDK version. ## Methods @@ -963,6 +996,81 @@ await clerk.navigate('/dashboard') The route to navigate to. +### `on()` + +Registers an event handler for a specific Clerk event. + +```ts +type OnEventListener = ( + event: E, + handler: EventHandler, + opt?: { + notify: boolean + }, +) => void +``` + +#### Example + +```js +window.Clerk.on('status', (status) => {}) +window.Clerk.on('status', (status) => {}, { notify: true }) +``` + +#### Parameters + + + - `event` + - `E` + + The event to listen to. Currently, the only supported event is `status`. + + --- + + - `handler` + - `EventHandler` + + The handler to call when the event is triggered. + + --- + + - `opt?` + - `{ notify: boolean }` + + An optional object to control the behavior of the event handler. If true, and the event was previously dispatched, handler will be called immediately with the latest payload + + +### `off()` + +Removes an event handler for a specific Clerk event. + +```ts +type OffEventListener = (event: E, handler: EventHandler) => void +``` + +#### Example + +```js +window.Clerk.off('status') +window.Clerk.off('status', (status) => {}) +``` + +#### Parameters + + + - `event` + - `E` + + The event to remove the handler from. Currently, the only supported event is `status`. + + --- + + - `handler` + - `EventHandler` + + The handler to remove. + + ### `redirectToCreateOrganization()` Redirects to the configured URL where [``](/docs/components/organization/create-organization) is mounted. This method uses the [`navigate()`](#navigate) method under the hood.