diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b1f6158d2..4136a9f280 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -575,7 +575,7 @@ The `` component is used at the beginning of a tutorial-type con - Install `@clerk/nextjs` - Set up your environment keys to test your app locally -- Add `` to your application +- Add `` to your application - Use Clerk middleware to implement route-specific authentication - Create a header with Clerk components for users to sign in and out diff --git a/docs/_partials/react-hooks.mdx b/docs/_partials/react-hooks.mdx new file mode 100644 index 0000000000..594ffdf1e8 --- /dev/null +++ b/docs/_partials/react-hooks.mdx @@ -0,0 +1,9 @@ +- [`useUser()`](/docs/references/react/use-user){{ target: '_blank' }} +- [`useClerk()`](/docs/references/react/use-clerk){{ target: '_blank' }} +- [`useAuth()`](/docs/references/react/use-auth){{ target: '_blank' }} +- [`useSignIn()`](/docs/references/react/use-sign-in){{ target: '_blank' }} +- [`useSignUp()`](/docs/references/react/use-sign-up){{ target: '_blank' }} +- [`useSession()`](/docs/references/react/use-session){{ target: '_blank' }} +- [`useSessionList()`](/docs/references/react/use-session-list){{ target: '_blank' }} +- [`useOrganization()`](/docs/references/react/use-organization){{ target: '_blank' }} +- [`useOrganizationList()`](/docs/references/react/use-organization-list){{ target: '_blank' }} diff --git a/docs/advanced-usage/satellite-domains.mdx b/docs/advanced-usage/satellite-domains.mdx index 9a22e430bf..5ffb193f48 100644 --- a/docs/advanced-usage/satellite-domains.mdx +++ b/docs/advanced-usage/satellite-domains.mdx @@ -115,7 +115,7 @@ To access authentication state from a satellite domain, users will be transparen # CLERK_SIGN_UP_URL=http://localhost:3000/sign-up ``` - - You will also need to add the `allowedRedirectOrigins` property to `` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example: + - You will also need to add the `allowedRedirectOrigins` property to `` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example: ```tsx {{ filename: 'app/layout.tsx' }} diff --git a/docs/authentication/configuration/sign-up-sign-in-options.mdx b/docs/authentication/configuration/sign-up-sign-in-options.mdx index 6e4865727a..4184b85cfe 100644 --- a/docs/authentication/configuration/sign-up-sign-in-options.mdx +++ b/docs/authentication/configuration/sign-up-sign-in-options.mdx @@ -17,7 +17,7 @@ Identifiers are how your application recognizes an individual user. There are th In the application configuration screen, you can select multiple identifiers, but at least one is required. -**Email address** is the most common primary identifier. During the sign-up process, a user must supply and verify their email address. They must keep an email address on their account at all times. However, the email address that was used for registration can be later changed from the user's profile page. +**Email address** is the most common primary identifier. When it is the only enabled identifier, users are required to supply an email address during sign-up and keep one on their account at all times. The email address that was supplied during sign-up can be later changed from the user's profile page. When **phone number** is selected as the identifier, a user can sign up with their phone number and receive a code via SMS to verify it. SMS functionality is restricted to phone numbers from countries enabled on your [SMS allowlist](#sms-allowlist). @@ -162,12 +162,12 @@ To enable social connections: ## Web3 authentication -Clerk provides [Web3 authentication](/docs/users/web3) with either MetaMask or Coinbase Wallet. As part of validating the accuracy of the returned Web3 account address, Clerk handles the signing of a message and verifying the signature. Because sign-in with Web3 uses the same abstraction as our other authentication factors, like passwords or email links, other Clerk features like multi-factor authentication and profile enrichment work for Web3 users out-of-the-box. +Clerk provides [Web3 authentication](/docs/users/web3) with either MetaMask, Coinbase Wallet or OKX Wallet. As part of validating the accuracy of the returned Web3 account address, Clerk handles the signing of a message and verifying the signature. Because sign-in with Web3 uses the same abstraction as our other authentication factors, like passwords or email links, other Clerk features like multi-factor authentication and profile enrichment work for Web3 users out-of-the-box. To enable Web3 authentication: 1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page. -1. Toggle on the Web3 provider. Currently, Clerk supports MetaMask and Coinbase Wallet. +1. Enable your preferred Web3 provider. ## Multi-factor authentication diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 026abb0cf8..f0ac052697 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -74,7 +74,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open [nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses. - For further security, Microsoft offers an optional `xms_edov` claim, which provides additional context to determine whether the returned email is verified. + For further security, Microsoft offers an optional `xms_edov` [claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference), which provides additional context to determine whether the returned email is verified. This claim is mandatory for applications backing EASIE connections. To enable it, you must: @@ -83,8 +83,6 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add optional claim**. 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. 1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form. - > [!NOTE] - > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. 1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**. 1. In the sidebar, go to **Manifest**. 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx new file mode 100644 index 0000000000..3ae5b0ce3f --- /dev/null +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -0,0 +1,88 @@ +--- +title: Add a custom OpenID Connect (OIDC) Provider as an enterprise connection +description: Learn how to integrate a custom OIDC provider with Clerk for Enterprise SSO. +--- + + + - Add a custom OIDC provider to authenticate users with Enterprise SSO + + +This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works) provider to authenticate users via Enterprise SSO. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your Identity Provider (IdP). + + + ### Set up an enterprise connection in Clerk + + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For specific domains**. + 1. Under **Third party**, select **OpenID Connect (OIDC)**. + 1. Add the **Name** of the connection. + 1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation). + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. + 1. Select **Add connection**. You will be redirected to the connection's configuration page. Keep this page open. + + ### Configure your IdP + + 1. If necessary, create a new application in your IdP. + 1. In the connection's configuration page of the Clerk Dashboard, copy the **Authorized redirect URI**. + 1. Add the value to your IdP's whitelisted URLs. + 1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them. + + ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk + + 1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. + 1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields. + 1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`. + 1. Select **Save**. + + > [!NOTE] + > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, in the connection's configuration page in the Clerk Dashboard, find the **Identity Provider Configuration** section and select **Use Manual Configuration** to manually configure the connection. + + ### Configure attribute mapping (optional) + + Clerk expects the claims returned by your IdP to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. + + > [!WARNING] + > OIDC Enterprise connections require the [`email_verified`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) claim to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format. + > + > If the IdP doesn't return this claim, you can leave the **Email address verified** field blank and set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). + + ### Allow additional identifiers (optional) + + User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles: + + 1. In the connection's configuration page of the Clerk Dashboard, navigate to the **Advanced** tab. + 1. Enable **Allow additional identifiers**. + 1. Select **Save**. + + ### Enable the connection for Clerk + + To make the connection available for your users to authenticate with: + + 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. At the top of the page, toggle on **Enable connection** and select **Save**. + + ### Test your connection + + The simplest way to test your enterprise connection is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. + + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. + 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: + - **For development** – `https://your-domain.accounts.dev/sign-in` + - **For production** – `https://accounts.your-domain.com/sign-in` + 1. Sign in with your IdP account. + diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 6961a7c90f..5a8df7cb68 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -1,15 +1,15 @@ --- -title: Enterprise SSO +title: Enterprise Single Sign-On (SSO) description: Clerk provides Enterprise SSO to authenticate users via federated Identity Providers such such as Azure AD, Okta, Google Workspace and more. --- -With Enterprise SSO, users can sign in seamlessly using their Identity Provider's (IdP) credentials and have their user data synchronized with Clerk. You can learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). +Enterprise Single Sign-On (SSO) allows users to sign in seamlessly using their Identity Provider (IdP) credentials (e.g.,Azure AD, Okta, or Google Workspace) and have their user data synchronized with Clerk. Clerk supports multiple protocols for implementing Enterprise SSO, including SAML and OIDC. Learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). ## SAML Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an IdP. The following IdPs are supported: [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta). However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. -### Allow subdomains +#### Allow subdomains Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` wouldn't be able to use a SAML connection with the `example.com` domain to authenticate. @@ -24,7 +24,11 @@ To configure subdomains for a SAML connection: > [!NOTE] > To enable the **Allow subdomains** option, your SAML connection domain must be an [eTLD+1](https://developer.mozilla.org/en-US/docs/Glossary/eTLD). -## EASIE +## OIDC + +Clerk supports Enterprise SSO via the OpenID Connect (OIDC) protocol, either through [EASIE](#easie) or by [integrating with any OIDC-compatible provider](/docs/authentication/enterprise-connections/oidc/custom-provider). + +### EASIE [EASIE](https://easie.dev) SSO is a way for applications to provide enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to be an easier alternative to SAML SSO. @@ -33,7 +37,7 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _ - [Google](/docs/authentication/social-connections/google) - [Microsoft](/docs/authentication/social-connections/microsoft) -### Automatic deprovisioning +#### Automatic deprovisioning Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the app. @@ -41,7 +45,7 @@ Within 10 minutes of a user being removed from the OpenID provider (e.g. [suspen It is ultimately the app's responsibility to handle this unauthenticated state and display something appropriate to the user. For example, Next.js apps using [`auth.protect()`](/docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. -## SAML vs. EASIE +### SAML vs. EASIE The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), apps that require single-tenant IdPs should opt for SAML. diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx index 6a15fed211..ee28e7e925 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/backend-requests/making/custom-session-token.mdx @@ -40,11 +40,11 @@ This guide will show you how to customize a session token to include additional export default async function Page() { const { sessionClaims } = await auth() - const firstName = sessionClaims?.fullName + const fullName = sessionClaims?.fullName const primaryEmail = sessionClaims?.primaryEmail - return NextResponse.json({ firstName, primaryEmail }) + return NextResponse.json({ fullName, primaryEmail }) } ``` @@ -55,11 +55,11 @@ This guide will show you how to customize a session token to include additional export default async function handler(req: NextApiRequest, res: NextApiResponse) { const { sessionClaims } = getAuth(req) - const firstName = sessionClaims.fullName + const fullName = sessionClaims.fullName const primaryEmail = sessionClaims.primaryEmail - return res.status(200).json({ firstName, primaryEmail }) + return res.status(200).json({ fullName, primaryEmail }) } ``` @@ -73,14 +73,14 @@ This guide will show you how to customize a session token to include additional 1. Create the `CustomJwtSessionClaims` interface and declare it globally. 1. Add the custom claims to the `CustomJwtSessionClaims` interface. - The following example demonstrates how to add the `firstName` and `primaryEmail` claims to the `CustomJwtSessionClaims` interface. + The following example demonstrates how to add the `fullName` and `primaryEmail` claims to the `CustomJwtSessionClaims` interface. ```tsx {{ filename: 'types/globals.d.ts' }} export {} declare global { interface CustomJwtSessionClaims { - firstName?: string + fullName?: string primaryEmail?: string } } diff --git a/docs/backend-requests/making/jwt-templates.mdx b/docs/backend-requests/making/jwt-templates.mdx index c07b5f5b1a..96d42f6339 100644 --- a/docs/backend-requests/making/jwt-templates.mdx +++ b/docs/backend-requests/making/jwt-templates.mdx @@ -10,8 +10,6 @@ Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/ You can control the claims that will go into these tokens by creating custom **JWT templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format. - - ## What is a JWT template? **JWT templates** are essentially JSON objects that specify claims to be included in the generated tokens, along with their respective values. diff --git a/docs/backend-requests/resources/session-tokens.mdx b/docs/backend-requests/resources/session-tokens.mdx index ae43ef8737..ca19a995cb 100644 --- a/docs/backend-requests/resources/session-tokens.mdx +++ b/docs/backend-requests/resources/session-tokens.mdx @@ -38,7 +38,7 @@ You can also create custom tokens using a [JWT template](/docs/backend-requests/ The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. -A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/making/custom-session-token) or creating a [custom JWT template](/docs/backend-requests/making/jwt-templates). In these cases, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. +A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/making/custom-session-token). In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. Claims to monitor for size limits: @@ -51,7 +51,7 @@ Claims to monitor for size limits: If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit. > [!NOTE] -> If your application encounters this issue, the Clerk Dashboard will display a warning: **"Some users are exceeding cookie size limits"**. To resolve this, update your [custom session token](/docs/backend-requests/making/custom-session-token) or the [JWT template](/docs/backend-requests/making/jwt-templates) that is referenced in the warning. +> If your application encounters this issue, the Clerk Dashboard will display a warning: **"Some users are exceeding cookie size limits"**. To resolve this, update your [custom session token](/docs/backend-requests/making/custom-session-token). ## Validate session tokens diff --git a/docs/components/clerk-provider.mdx b/docs/components/clerk-provider.mdx index 676a3bb84e..bcda26af27 100644 --- a/docs/components/clerk-provider.mdx +++ b/docs/components/clerk-provider.mdx @@ -90,7 +90,14 @@ The recommended approach is to wrap your entire app with `` at th - `allowedRedirectOrigins?` - `Array` - Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. + 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` + + 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. --- @@ -202,7 +209,7 @@ The recommended approach is to wrap your entire app with `` at th - `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 and required for development instances. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + 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. --- diff --git a/docs/components/organization/create-organization.mdx b/docs/components/organization/create-organization.mdx index b083ec1043..c32e40a38f 100644 --- a/docs/components/organization/create-organization.mdx +++ b/docs/components/organization/create-organization.mdx @@ -59,7 +59,7 @@ The following example includes a basic implementation of the ` - ```jsx {{ filename: '/app/create-organization/[[...create-organization]]/page.tsx' }} + ```jsx {{ filename: 'app/create-organization/[[...create-organization]]/page.tsx' }} import { CreateOrganization } from '@clerk/nextjs' export default function CreateOrganizationPage() { diff --git a/docs/components/organization/organization-list.mdx b/docs/components/organization/organization-list.mdx index c11dcfaf9b..d97d8cf159 100644 --- a/docs/components/organization/organization-list.mdx +++ b/docs/components/organization/organization-list.mdx @@ -64,7 +64,7 @@ All props are optional. - ```jsx {{ filename: '/app/discover/page.tsx' }} + ```jsx {{ filename: 'app/discover/page.tsx' }} import { OrganizationList } from '@clerk/nextjs' export default function OrganizationListPage() { diff --git a/docs/components/organization/organization-profile.mdx b/docs/components/organization/organization-profile.mdx index 54f9c09a80..9dc549275b 100644 --- a/docs/components/organization/organization-profile.mdx +++ b/docs/components/organization/organization-profile.mdx @@ -56,7 +56,7 @@ All props are optional. You can embed the `` component using the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-routes). This allows you to redirect the user inside your application. - ```jsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} + ```jsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }} import { OrganizationProfile } from '@clerk/nextjs' export default function OrganizationProfilePage() { diff --git a/docs/components/organization/organization-switcher.mdx b/docs/components/organization/organization-switcher.mdx index 734ae48d85..0edcfc5b1c 100644 --- a/docs/components/organization/organization-switcher.mdx +++ b/docs/components/organization/organization-switcher.mdx @@ -103,7 +103,7 @@ All props below are optional. - ```jsx {{ filename: '/app/organization-switcher/[[...organization-switcher]]/page.tsx' }} + ```jsx {{ filename: 'app/organization-switcher/[[...organization-switcher]]/page.tsx' }} import { OrganizationSwitcher } from '@clerk/nextjs' export default function OrganizationSwitcherPage() { diff --git a/docs/components/protect.mdx b/docs/components/protect.mdx index 44a9a497af..e9f90fe55e 100644 --- a/docs/components/protect.mdx +++ b/docs/components/protect.mdx @@ -158,7 +158,7 @@ The following example uses ``'s `condition` prop to conditionally rende - ```tsx {{ filename: '/app/dashboard/settings/layout.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/layout.tsx' }} import type { PropsWithChildren } from 'react' import { Protect } from '@clerk/nextjs' diff --git a/docs/components/user/user-profile.mdx b/docs/components/user/user-profile.mdx index e303ba5be1..6c9f17b42d 100644 --- a/docs/components/user/user-profile.mdx +++ b/docs/components/user/user-profile.mdx @@ -53,7 +53,7 @@ All props are optional. You can embed the `` component using the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-routes). This allows you to redirect the user inside your application. - ```jsx {{ filename: '/app/user-profile/[[...user-profile]]/page.tsx' }} + ```jsx {{ filename: 'app/user-profile/[[...user-profile]]/page.tsx' }} import { UserProfile } from '@clerk/nextjs' const UserProfilePage = () => diff --git a/docs/components/waitlist.mdx b/docs/components/waitlist.mdx index ee5e0dafd2..e558b24b8e 100644 --- a/docs/components/waitlist.mdx +++ b/docs/components/waitlist.mdx @@ -53,7 +53,7 @@ The following example includes a basic implementation of the `` comp - ```jsx {{ filename: '/app/waitlist/[[...waitlist]]/page.tsx' }} + ```jsx {{ filename: 'app/waitlist/[[...waitlist]]/page.tsx' }} import { Waitlist } from '@clerk/nextjs' export default function WaitlistPage() { diff --git a/docs/custom-flows/email-password.mdx b/docs/custom-flows/email-password.mdx index 37dfa805ef..91d7f95dda 100644 --- a/docs/custom-flows/email-password.mdx +++ b/docs/custom-flows/email-password.mdx @@ -34,7 +34,7 @@ This guide will walk you through how to build a custom email/password sign-up an This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} 'use client' import * as React from 'react' @@ -478,7 +478,7 @@ This guide will walk you through how to build a custom email/password sign-up an This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as React from 'react' diff --git a/docs/custom-flows/saml-connections.mdx b/docs/custom-flows/enterprise-connections.mdx similarity index 64% rename from docs/custom-flows/saml-connections.mdx rename to docs/custom-flows/enterprise-connections.mdx index e062065c88..dd0135cdb6 100644 --- a/docs/custom-flows/saml-connections.mdx +++ b/docs/custom-flows/enterprise-connections.mdx @@ -1,25 +1,25 @@ --- -title: Build a custom flow for authenticating with SAML connections -description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports OAuth connections. +title: Build a custom flow for authenticating with enterprise connections +description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports enterprise connections. --- ## Before you start -You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. +You must configure your application instance through the Clerk Dashboard for the enterprise connection(s) that you want to use. Visit [the appropriate guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. ## Create the sign-up and sign-in flow -When using SAML, the sign-in and sign-up flows are equivalent. A successful SAML flow consists of the following steps: +When using Enterprise SSO, the sign-in and sign-up flows are equivalent. A successful Enterprise SSO flow consists of the following steps: -1. Start the SAML flow by calling [`SignIn.authenticateWithRedirect(params)`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect) or [`SignUp.authenticateWithRedirect(params)`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect). Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider. +1. Start the Enterprise SSO flow by calling [`SignIn.authenticateWithRedirect(params)`][sign-in-redirect] or [`SignUp.authenticateWithRedirect(params)`][sign-up-redirect]. Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider. 1. Create a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) method or render the prebuilt [``](/docs/components/control/authenticate-with-callback) component. The following example shows two files: -1. The sign-in page where the user can start the SAML flow. -1. The SSO callback page where the SAML flow is completed. +1. The sign-in page where the user can start the Enterprise SSO flow. +1. The SSO callback page where the flow is completed. @@ -30,13 +30,13 @@ The following example shows two files: import * as React from 'react' import { useSignIn, useSignUp } from '@clerk/nextjs' - export default function SAMLSignIn() { + export default function Page() { const { signIn } = useSignIn() const { signUp } = useSignUp() if (!signIn || !signUp) return null - const signInWithSAML = (e: React.FormEvent) => { + const signInWithEnterpriseSSO = (e: React.FormEvent) => { e.preventDefault() const email = (e.target as HTMLFormElement).email.value @@ -44,7 +44,7 @@ The following example shows two files: signIn .authenticateWithRedirect({ identifier: email, - strategy: 'saml', + strategy: 'enterprise_sso', redirectUrl: '/sso-callback', redirectUrlComplete: '/', }) @@ -58,9 +58,9 @@ The following example shows two files: } return ( -
signInWithSAML(e)}> + signInWithEnterpriseSSO(e)}> - +
) } @@ -69,10 +69,10 @@ The following example shows two files: ```jsx {{ filename: 'app/sign-up/sso-callback/page.tsx' }} import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' - export default function SSOCallback() { + export default function Page() { // Handle the redirect flow by rendering the // prebuilt AuthenticateWithRedirectCallback component. - // This is the final step in the custom SAML flow. + // This is the final step in the custom Enterprise SSO flow. return } ``` @@ -80,13 +80,13 @@ The following example shows two files: -## SAML account transfer flows +## Enterprise account transfer flows -It is common for users who are authenticating with SAML to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow. +It is common for users who are authenticating with an enterprise account to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow. **If you would like to keep your sign-in and sign-up flows completely separate, then you can skip this section.** -The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace `signIn.authenticateWithRedirect()` with `signUp.authenticateWithRedirect()` in your code. +The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace [`signIn.authenticateWithRedirect()`][sign-in-redirect] with [`signUp.authenticateWithRedirect()`][sign-up-redirect] in your code. @@ -96,13 +96,13 @@ The following example demonstrates how to handle these cases in your sign-in flo import * as React from 'react' import { useSignIn, useSignUp } from '@clerk/nextjs' - export default function SAMLSignIn() { + export default function Page() { const { signIn } = useSignIn() const { signUp, setActive } = useSignUp() if (!signIn || !signUp) return null - const signInWithSAML = (e: React.FormEvent) => { + const signInWithEnterpriseSSO = (e: React.FormEvent) => { e.preventDefault() const email = (e.target as HTMLFormElement).email.value @@ -110,7 +110,7 @@ The following example demonstrates how to handle these cases in your sign-in flo signIn .authenticateWithRedirect({ identifier: email, - strategy: 'saml', + strategy: 'enterprise_sso', redirectUrl: '/sso-callback', redirectUrlComplete: '/', }) @@ -127,7 +127,7 @@ The following example demonstrates how to handle these cases in your sign-in flo if (!signIn || !signUp) return null // If the user has an account in your application, but does not yet - // have a SAML account connected to it, you can transfer the SAML + // have a enterprise account connected to it, you can transfer the enterprise // account to the existing user account. const userExistsButNeedsToSignIn = signUp.verifications.externalAccount.status === 'transferable' && @@ -143,9 +143,9 @@ The following example demonstrates how to handle these cases in your sign-in flo } } - // If the user has a SAML account but does not yet + // If the user has a enterprise account but does not yet // have an account in your app, you can create an account - // for them using the SAML information. + // for them using the enterprise account's information. const userNeedsToBeCreated = signIn.firstFactorVerification.status === 'transferable' if (userNeedsToBeCreated) { @@ -160,18 +160,22 @@ The following example demonstrates how to handle these cases in your sign-in flo } } else { // If the user has an account in your application - // and has an SAML account connected to it, you can sign them in. - signInWithSAML(e) + // and has an enterprise account connected to it, you can sign them in. + signInWithEnterpriseSSO(e) } } return (
handleSignIn(e)}> - +
) } ``` + +[sign-in-redirect]: /docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect + +[sign-up-redirect]: /docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect diff --git a/docs/custom-flows/manage-sms-based-mfa.mdx b/docs/custom-flows/manage-sms-based-mfa.mdx index a3f45b5d15..a16224c6fa 100644 --- a/docs/custom-flows/manage-sms-based-mfa.mdx +++ b/docs/custom-flows/manage-sms-based-mfa.mdx @@ -33,7 +33,7 @@ One of the options that Clerk supports for MFA is **SMS verification codes**. Th - ```tsx {{ filename: '/app/account/manage-mfa/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/account/manage-mfa/page.tsx', collapsible: true }} 'use client' import * as React from 'react' @@ -222,7 +222,7 @@ One of the options that Clerk supports for MFA is **SMS verification codes**. Th - ```tsx {{ filename: '/app/account/add-phone/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/account/add-phone/page.tsx', collapsible: true }} 'use client' import * as React from 'react' diff --git a/docs/custom-flows/manage-totp-based-mfa.mdx b/docs/custom-flows/manage-totp-based-mfa.mdx index 3ddacb47e6..62fee0ab1a 100644 --- a/docs/custom-flows/manage-totp-based-mfa.mdx +++ b/docs/custom-flows/manage-totp-based-mfa.mdx @@ -36,7 +36,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( - ```tsx {{ filename: '/app/account/manage-mfa/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/account/manage-mfa/page.tsx', collapsible: true }} 'use client' import * as React from 'react' @@ -158,7 +158,7 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( - ```tsx {{ filename: '/app/account/manage-mfa/add/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/account/manage-mfa/add/page.tsx', collapsible: true }} 'use client' import { useUser } from '@clerk/nextjs' @@ -305,6 +305,54 @@ One of the options that Clerk supports for MFA is **Authenticator applications ( ``` + + #### Force MFA (optional) + + While Clerk does not natively enforce MFA for all users, you can implement this functionality by using `clerkMiddleware()` to check whether a user has MFA enabled. + + The following example demonstrates how to force MFA for all users. It uses `clerkMiddleware()` to intercept all requests and check whether a user has MFA enabled. If the user does not have MFA enabled, `clerkMiddleware()` redirects them to the `/mfa` page where they can set up MFA. + + ```tsx {{ filename: 'middleware.ts', collapsible: true }} + import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server' + import { NextResponse } from 'next/server' + + const isMFARoute = createRouteMatcher(['/account/manage-mfa/add(.*)']) + const isSignInRoute = createRouteMatcher(['/sign-in(.*)']) + + export default clerkMiddleware(async (auth, req) => { + const { userId } = await auth() + + // Redirect to homepage if the user is signed in and on the sign-in page + if (userId !== null && isSignInRoute(req) && !isMFARoute(req)) { + return NextResponse.redirect(new URL('/', req.url)) + } + + // Check if the user is signed in and not on the MFA page + if (userId !== null && !isMFARoute(req)) { + const res = await fetch(`https://api.clerk.com/v1/users/${userId}`, { + headers: { + Authorization: `Bearer ${process.env.CLERK_SECRET_KEY}`, + }, + }) + + const userData = await res.json() + + // Redirect to MFA setup page if MFA is not enabled + if (userData.two_factor_enabled === false) { + return NextResponse.redirect(new URL('/account/manage-mfa/add', req.url)) + } + } + }) + + export const config = { + matcher: [ + // Skip Next.js internals and all static files, unless found in search params + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + // Always run for API routes + '/(api|trpc)(.*)', + ], + } + ``` diff --git a/docs/custom-flows/sign-out.mdx b/docs/custom-flows/sign-out.mdx index a0c1c889e3..732a57ebf8 100644 --- a/docs/custom-flows/sign-out.mdx +++ b/docs/custom-flows/sign-out.mdx @@ -20,7 +20,7 @@ The `signOut()` function signs a user out of all sessions in a [multi-session ap This example is written for Next.js App Router but can be adapted for any React meta framework, such as Remix. - ```jsx {{ filename: '/app/components/SignOutButton.tsx' }} + ```jsx {{ filename: 'app/components/SignOutButton.tsx' }} 'use client' import { useClerk } from '@clerk/nextjs' diff --git a/docs/customization/elements/examples/shadcn-ui.mdx b/docs/customization/elements/examples/shadcn-ui.mdx index 33b2a88753..94a33ba20c 100644 --- a/docs/customization/elements/examples/shadcn-ui.mdx +++ b/docs/customization/elements/examples/shadcn-ui.mdx @@ -55,7 +55,7 @@ You must also configure the appropriate settings in Clerk: }, ]} > - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' import * as SignUp from '@clerk/elements/sign-up' @@ -321,7 +321,7 @@ You must also configure the appropriate settings in Clerk: }, ]} > - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' import * as SignIn from '@clerk/elements/sign-in' diff --git a/docs/customization/elements/examples/sign-in.mdx b/docs/customization/elements/examples/sign-in.mdx index 0180ae75a2..e82ef39ba6 100644 --- a/docs/customization/elements/examples/sign-in.mdx +++ b/docs/customization/elements/examples/sign-in.mdx @@ -26,7 +26,7 @@ Before you build your sign-in flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -127,7 +127,7 @@ Before you build your sign-in flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -222,7 +222,7 @@ Before you build your sign-in flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -382,7 +382,7 @@ Before you build your sign-in flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' diff --git a/docs/customization/elements/examples/sign-up.mdx b/docs/customization/elements/examples/sign-up.mdx index 8ade4df375..6f2ee7add0 100644 --- a/docs/customization/elements/examples/sign-up.mdx +++ b/docs/customization/elements/examples/sign-up.mdx @@ -25,7 +25,7 @@ Before you build your sign-up flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -175,7 +175,7 @@ Before you build your sign-up flow, you need to configure the appropriate settin } ]} > - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', collapsible: true }} 'use client' import * as Clerk from '@clerk/elements/common' diff --git a/docs/customization/elements/guides/sign-in.mdx b/docs/customization/elements/guides/sign-in.mdx index 89c63d39af..a2d83b1440 100644 --- a/docs/customization/elements/guides/sign-in.mdx +++ b/docs/customization/elements/guides/sign-in.mdx @@ -38,7 +38,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. Create a new route in your Next.js application. The route needs to be an [optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) so the sign-in flow can handled nested paths, as shown in the following example: - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -58,7 +58,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. The Clerk authentication flows are made up of **steps**. Steps handle rendering the UI for each part of the flow. To allow users to create a sign-in attempt, the `start` step needs to be rendered. The following example does so with the `` component: - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [[9, 11]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [[9, 11]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -79,7 +79,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. Make it functional by adding input fields. The following example uses the `` component to render an `identifier` field, as well as the `` component to allow users to sign in with a social connection, like Google: - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [[12, 20]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [[12, 20]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -117,7 +117,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. The following example demonstrates how to conditionally render a form for the `email_code` strategy: - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [[23, 38]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [[23, 38]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -167,7 +167,7 @@ description: Learn how to build a complete sign-in form with Clerk Elements. If your instance is configured to support authenticating with passwords, you must add a few additional steps and verification strategies. You can choose if you want to support providing a password in the `start` step with an additional field, or as an additional verification strategy. For this guide, add it as a standalone verification strategy. - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [[39, 65], [68, 94]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [[39, 65], [68, 94]] }} 'use client' import * as Clerk from '@clerk/elements/common' diff --git a/docs/customization/elements/guides/sign-up.mdx b/docs/customization/elements/guides/sign-up.mdx index 5aed014cf7..eb9e04d147 100644 --- a/docs/customization/elements/guides/sign-up.mdx +++ b/docs/customization/elements/guides/sign-up.mdx @@ -38,7 +38,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. Create a new route in your Next.js application. The route needs to be an [optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) so the sign-up flow can handled nested paths, as shown in the following example: - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx' }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -58,7 +58,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. The Clerk authentication flows are made up of **steps**. Steps handle rendering the UI for each part of the flow. To allow users to create a sign-up attempt, the `start` step needs to be rendered. The following example does so with the `` component: - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', mark: [[9, 11]] }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [[9, 11]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -79,7 +79,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. Make it functional by adding input fields. The following example uses the `` component to render the `emailAddress` and `username` fields, as well as the `` component to allow users to sign up with a social connection, like Google: - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', mark: [[12, 34]] }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [[12, 34]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -128,7 +128,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. The following example demonstrates how to conditionally render a form for the `phone_code` and `email_code` strategies: - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', mark: [[35, 59]] }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [[35, 59]] }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -199,7 +199,7 @@ description: Learn how to build a complete sign-up form with Clerk Elements. Should a user attempt to sign up via Google while a username is a required field, the `continue` step will be necessary to accept the username. The `` component will display any additional required fields. - ```tsx {{ filename: '/app/sign-up/[[...sign-up]]/page.tsx', mark: [[35, 45]] }} + ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [[35, 45]] }} 'use client' import * as Clerk from '@clerk/elements/common' diff --git a/docs/customization/elements/guides/styling.mdx b/docs/customization/elements/guides/styling.mdx index 17aa48d8b8..2f20fb060f 100644 --- a/docs/customization/elements/guides/styling.mdx +++ b/docs/customization/elements/guides/styling.mdx @@ -13,7 +13,7 @@ You can style Clerk Elements components with the following props: This guide will demonstrate multiple different styling approaches using the following basic sign-in flow as a starting point: -```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} +```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -50,7 +50,7 @@ export default function SignInPage() { If you are already using [Tailwind CSS](https://tailwindcss.com/), no additional setup is required. Classes from Tailwind can be applied to most Clerk Elements components. Use your editor's IntelliSense to see if `className` is a valid prop on a component you want to style. -```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} +```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -97,7 +97,7 @@ export default function SignInPage() { Many of the Clerk Elements components accept an `asChild` prop that allows you to swap out the rendered element. This is useful if you have an existing design system or component library that you wish to use with Clerk Elements. -```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} +```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -161,7 +161,7 @@ const CustomInput = forwardRef(function CustomInput(props, forwardedRef) { Classes from an imported CSS module can be applied to most Clerk Elements components with `className`. -```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} +```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' @@ -205,7 +205,7 @@ export default function SignInPage() { You can also use inline styles with Clerk Elements. This is useful when you need to apply styles conditionally or avoid creating a separate CSS file. -```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx' }} +```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} 'use client' import * as Clerk from '@clerk/elements/common' diff --git a/docs/customization/elements/reference/sign-in.mdx b/docs/customization/elements/reference/sign-in.mdx index 0dae331b7c..0594c731ef 100644 --- a/docs/customization/elements/reference/sign-in.mdx +++ b/docs/customization/elements/reference/sign-in.mdx @@ -166,7 +166,7 @@ Conditionally renders its children depending on the authentication strategy that - `name` - - 'saml' | 'ticket' | 'password' | 'passkey' | 'phone\_code' | 'email\_code' | 'web3\_metamask\_signature' | 'web3\_coinbase\_wallet\_signature' | 'reset\_password\_email\_code' | 'reset\_password\_phone\_code' | 'email\_link' | 'totp' | 'backup\_code' | 'oauth' | 'web3' | [OAuthStrategy](https://github.com/clerk/javascript/blob/956d8792fefe9d6a89022f1e938149b25503ec7f/packages/types/src/strategies.ts#L15) + - 'saml' | 'ticket' | 'password' | 'passkey' | 'phone\_code' | 'email\_code' | 'web3\_metamask\_signature' | 'web3\_coinbase\_wallet\_signature' | 'web3\_okx\_wallet\_signature' | 'reset\_password\_email\_code' | 'reset\_password\_phone\_code' | 'email\_link' | 'totp' | 'backup\_code' | 'oauth' | 'web3' | [OAuthStrategy](https://github.com/clerk/javascript/blob/956d8792fefe9d6a89022f1e938149b25503ec7f/packages/types/src/strategies.ts#L15) The name of the strategy for which its children will be rendered. @@ -200,7 +200,7 @@ Renders a button that will change the current strategy that needs to be verified - `name` - - `'email_code' | 'email_link' | 'password' | 'passkey' | 'phone_code' | 'reset_password_email_code' | 'reset_password_phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'` + - `'email_code' | 'email_link' | 'password' | 'passkey' | 'phone_code' | 'reset_password_email_code' | 'reset_password_phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'` The name of the strategy to switch to. diff --git a/docs/customization/organization-profile.mdx b/docs/customization/organization-profile.mdx index 2c9576c876..3d51ea668c 100644 --- a/docs/customization/organization-profile.mdx +++ b/docs/customization/organization-profile.mdx @@ -65,7 +65,7 @@ To add a custom page to the `` component, use the `` or `` component: as a component or as a direct child. ", "Dedicated page"]}> - ```tsx {{ filename: '/app/components/Header.tsx' }} + ```tsx {{ filename: 'app/components/Header.tsx' }} 'use client' import { OrganizationSwitcher } from '@clerk/nextjs' @@ -117,7 +117,7 @@ The following example demonstrates two ways that you can render content in the ` export default Header ``` - ```tsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }} 'use client' import { OrganizationProfile } from '@clerk/nextjs' @@ -247,7 +247,7 @@ You can add external links to the `` navigation sidebar u The following example adds a link to the homepage in the navigation sidebar of the `` component. ", "Dedicated page"]}> - ```tsx {{ filename: '/app/components/Header.tsx' }} + ```tsx {{ filename: 'app/components/Header.tsx' }} 'use client' import { OrganizationSwitcher } from '@clerk/nextjs' @@ -275,7 +275,7 @@ The following example adds a link to the homepage in the navigation sidebar of t export default Header ``` - ```tsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }} 'use client' import { OrganizationProfile } from '@clerk/nextjs' @@ -306,7 +306,7 @@ Note that when reordering default routes, the first item in the navigation sideb ", "Dedicated Page"]}> - ```tsx {{ filename: '/app/components/Header.tsx' }} + ```tsx {{ filename: 'app/components/Header.tsx' }} 'use client' import { OrganizationSwitcher } from '@clerk/nextjs' @@ -358,7 +358,7 @@ Note that when reordering default routes, the first item in the navigation sideb In the following example, `path` is set to `/organization-profile`, so the `` is rendered under the `/organization-profile` path. - ```tsx {{ filename: '/app/organization-profile/[[...organization-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }} 'use client' import { OrganizationProfile } from '@clerk/nextjs' diff --git a/docs/customization/themes.mdx b/docs/customization/themes.mdx index c9a3b5bf6f..650029a450 100644 --- a/docs/customization/themes.mdx +++ b/docs/customization/themes.mdx @@ -490,7 +490,7 @@ To apply a theme to a single Clerk component, pass the `appearance` prop to the - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [2, [7, 9]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [2, [7, 9]] }} import { SignIn } from '@clerk/nextjs' import { dark } from '@clerk/themes' diff --git a/docs/customization/user-profile.mdx b/docs/customization/user-profile.mdx index 4cd67fe367..1fc4d377b3 100644 --- a/docs/customization/user-profile.mdx +++ b/docs/customization/user-profile.mdx @@ -65,7 +65,7 @@ The following example demonstrates two ways that you can render content in the ` ", "Dedicated page"]}> - ```tsx {{ filename: '/app/page.tsx' }} + ```tsx {{ filename: 'app/page.tsx' }} 'use client' import { UserButton } from '@clerk/nextjs' @@ -109,7 +109,7 @@ The following example demonstrates two ways that you can render content in the ` } ``` - ```tsx {{ filename: '/app/user-profile/[[...user-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/user-profile/[[...user-profile]]/page.tsx' }} 'use client' import { UserProfile } from '@clerk/nextjs' @@ -295,7 +295,7 @@ The following example adds a link to the homepage in the navigation sidebar of t ", "Dedicated page"]}> - ```tsx {{ filename: '/app/page.tsx' }} + ```tsx {{ filename: 'app/page.tsx' }} 'use client' import { UserButton } from '@clerk/nextjs' @@ -319,7 +319,7 @@ The following example adds a link to the homepage in the navigation sidebar of t } ``` - ```tsx {{ filename: '/app/user-profile/[[...user-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/user-profile/[[...user-profile]]/page.tsx' }} 'use client' import { UserProfile } from '@clerk/nextjs' @@ -398,7 +398,7 @@ Note that when reordering default routes, the first item in the navigation sideb ", "Dedicated page"]}> - ```tsx {{ filename: '/app/page.tsx' }} + ```tsx {{ filename: 'app/page.tsx' }} 'use client' import { UserButton } from '@clerk/nextjs' @@ -442,7 +442,7 @@ Note that when reordering default routes, the first item in the navigation sideb In the following example, `path` is set to `/user-profile`, so the `` is rendered under the `/user-profile` path. - ```tsx {{ filename: '/app/user-profile/[[...user-profile]]/page.tsx' }} + ```tsx {{ filename: 'app/user-profile/[[...user-profile]]/page.tsx' }} 'use client' import { UserProfile } from '@clerk/nextjs' diff --git a/docs/customization/variables.mdx b/docs/customization/variables.mdx index a1616d461a..f84a42f886 100644 --- a/docs/customization/variables.mdx +++ b/docs/customization/variables.mdx @@ -460,7 +460,7 @@ The following example shows how to customize the [``](/docs/components - ```tsx {{ filename: '/app/sign-in/[[...sign-in]]/page.tsx', mark: [[6, 11]] }} + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', mark: [[6, 11]] }} import { SignIn } from '@clerk/nextjs' export default function Page() { diff --git a/docs/guides/architecture-scenarios.mdx b/docs/guides/architecture-scenarios.mdx index 9ffecf275c..68cb423248 100644 --- a/docs/guides/architecture-scenarios.mdx +++ b/docs/guides/architecture-scenarios.mdx @@ -56,7 +56,7 @@ Clerk offers a number of building blocks to help integrate organizations into yo - The [`` component](/docs/components/organization/organization-switcher) provides a way for your users to select which organization is active. The [`useOrganizationList()` hook](/docs/organizations/custom-organization-switcher) can be used for more control. - The [`useOrganization()` hook](/docs/references/react/use-organization) can be used to fetch the current, active organization. -- The [`` component](/docs/components/protect) enables you to limit who can view certain pages based on their role. Additionally, Clerk exposes a number of helper functions, such as [`auth()`](/docs/references/nextjs/auth), and hooks, such as [`useAuth()`](/docs/references/react/use-auth#how-to-use-the-use-auth-hook), to check the user's authorization throughout your app and API endpoints. +- The [`` component](/docs/components/protect) enables you to limit who can view certain pages based on their role. Additionally, Clerk exposes a number of helper functions, such as [`auth()`](/docs/references/nextjs/auth), and hooks, such as [`useAuth()`](/docs/references/react/use-auth#how-to-use-the-use-auth-hook), to check the user's authorization throughout your app and API endpoints. The organization's ID should be stored in your database alongside each resource so that it can be used to filter and query the resources that should be rendered or returned according to the active organization. diff --git a/docs/guides/authjs-migration.mdx b/docs/guides/authjs-migration.mdx index 21b9212762..f217828b0f 100644 --- a/docs/guides/authjs-migration.mdx +++ b/docs/guides/authjs-migration.mdx @@ -23,7 +23,7 @@ description: Learn how to migrate an application using Auth.js to use Clerk for > - Install `@clerk/nextjs` - Set environment variables - - Wrap your Next.js app in `` + - Wrap your Next.js app in `` - Set up sign-up and sign-in UI - Protect your app - Read user and session data @@ -67,9 +67,9 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth. CLERK_SECRET_KEY={{secret}} ``` - ### Wrap your Next.js app in `` + ### Wrap your Next.js app in `` - Remove the `` provider from Auth.js and replace it with ``. + Remove the `` provider from Auth.js and replace it with ``. diff --git a/docs/guides/reverification.mdx b/docs/guides/reverification.mdx index 31235d932d..c4d1fdac9e 100644 --- a/docs/guides/reverification.mdx +++ b/docs/guides/reverification.mdx @@ -22,7 +22,7 @@ To handle reverification server-side, use the [`auth.has()`](/docs/references/ne The following example uses the [`has()`](/docs/references/nextjs/auth-object#has) helper to check if the user has verified their credentials within a specific time period. The `strict` configuration sets the time period to 10 minutes. If the user hasn't verified their credentials within 10 minutes, the `reverificationError` utility is used to return an error. - ```ts {{ filename: '/app/actions.ts' }} + ```ts {{ filename: 'app/actions.ts' }} 'use server' import { auth, reverificationError } from '@clerk/nextjs/server' @@ -128,7 +128,7 @@ The following example demonstrates how to use the [`useReverification()`](/docs/ - ```tsx {{ filename: '/app/perform-action/page.tsx' }} + ```tsx {{ filename: 'app/perform-action/page.tsx' }} 'use client' import { useReverification } from '@clerk/nextjs' @@ -150,7 +150,7 @@ The following example demonstrates how to use the [`useReverification()`](/docs/ - ```tsx {{ filename: '/app/transfer/page.tsx' }} + ```tsx {{ filename: 'app/transfer/page.tsx' }} 'use client' import { useReverification } from '@clerk/nextjs' diff --git a/docs/guides/waitlist.mdx b/docs/guides/waitlist.mdx index d79ba9e077..4d8b8a951b 100644 --- a/docs/guides/waitlist.mdx +++ b/docs/guides/waitlist.mdx @@ -70,7 +70,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist) The following example includes a basic implementation of the `` component hosted on the `/` route (the home page). You can use this as a starting point for your own implementation. - ```jsx {{ filename: '/app/page.tsx' }} + ```jsx {{ filename: 'app/page.tsx' }} import { Waitlist } from '@clerk/nextjs' export default function Page() { diff --git a/docs/index.mdx b/docs/index.mdx index abd651d85a..554829ae3a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -78,6 +78,12 @@ Find all the guides and resources you need to develop with Clerk. - [TanStack Start (Beta)](/docs/quickstarts/tanstack-start) - Easily add secure and SSR-friendly authentication to your TanStack Start application with Clerk. - ![](data:image/webp;base64,UklGRu4JAABXRUJQVlA4TOEJAAAvP8APEM8Hu9r2tM0n/1KSMjNze8UzdNWu0duOwMzMlfXTGnBt204b3SczDjPU0+Vr5j+nnZ6Zp2dm0vjJ0oUc2bZqZZ1z3rX/cXcdQphEQgoWB0TgMHOHa3JEASCA6mXbtl1bY02NHcC+gJtq6gS2j+Aa/Sf7/8nY7ADw+MR//od0UAdVqEIUojCFeOEKdZ2TC6d7an1+DTIlHUShDur0v2kPEIX1/ZF5rZCuYct/87xXJc3Jdcw4BHhRxdJqF9PdrdRpi51GGXWq0NbpSINW7nVWUXczcgDDExNiEfXqZnAy7g9PvOkcndL6ndA2FYTZ0e8waiGBcsekHQvyZJbM2C5dIKjFQE9hqRgZowLYZ5RSB00iBaNgKQx8DtQvIjlPAAWYEBECKCAEwEeBpigqfJvUv+k1pq4ajyduRLjbAe2/hCJ8eA5ejtzrLD3L+S1LJiwHtfy3qRsMF6O5Zs3w+OdGQFuYDmjCTUfIq2jCRruMVca0QtDGxEN73TM9m9mVTwTQlWqXKebbnReuFRAsKaMztr8sBDF4XQiCZf2gyhm+evx475T/bMXkJ/P/bH7sn4/fpvxg5xfdVOv/C1DP+5nOBtpF8V51yL7Hp19nN/1fWo2BdPkhPBQTrqPW+58ZI04aj9D8dcriIDYfPs2PeQKY0xtmlRvzW5u3wjVx+VkW8V3c9Bcz/d68ppcUT7NN5BwXMtrfxltpLS6TnfpxZ65i9Jva4/F09xKHDn33UUc9g2Lsa8dmfGDtesPbS7Q+O2PMJOiThnjBUOGBPkhPBomjsrRXRWakM5V5K+byF0kO8uIPPOcl/mupUf4X+Q+g+66zmdB050bbJVvZst3+2OJJd7s3ax939pabr/0Tagr9c9w69ufp30Cs+xcogWqHv6AEedBreClwp6kGmkJSOyjPr6vh72iOy4jMPEacH9WAtuOxwWx1qDE9nwH2MhCgNB9uLeTdml/ZZaWrxv9MWjrSMfjLmHJTb50zARERTEvbtrVt5K0IDGF0mDkb6FLaMDPYwxBmzuBRmSF84GFmxkj25WOBISv4v++T/j+i/w7ctnGk0FOwe8XvoKz9f2KnO/V25pQexx1WfZ5zGTjUXY7U3ff4yh32haU7VwF/vYjCtrJNMplMryD55Zckov8O3LaNpCiDFTqX926/4ElBrkDDz3//8+8P//OfGOfufyB+tjW6CgJR/PyL+yNLgruEZqMrucV//eF7w3cAQEAE1gbEyP01jijSv/3Gv2XfGFgyv//B+Lc/ijQvAtH9/esUfXtzaDDyx7d4/TCdCLz/w1dp+OP2PH69dgMO3k81AvHpl19A6swHADs3AFJ9KBAffJGW2wYhzAHYSyUC8eHn6fjs9tAg9t51jekAgv3kEYiP7qXpjutyxnagw9BJKQQfPk7ujutCcjsdZEvS88GTZJ65eeGBlzCh4vVteLLaQV2dln0v4SHw6bOkCqcHNJb3nCewMBRZPOfUsdtlc5ggAu8/fyEgscIBSVX080RFRLDMrHax02GZXk7X3090PT6yOS8qFHRE57rq55oeBsgWF0cWL4BOVstAdOz2EhmL6CDRsxOr82x9gLFozkV+LCDrpDkO9bNw0dEJceK8OjK4ekTLRmzsj+KnljkqGuhXfRy4CAOXomAhc43lW2qdRZaA86PTnS5r+qgnbj1LmU2BpgRcvw+0qOPoIKk+4LLkAyNmqyDnfHX59Mzp4sbNZP6gwHjxmQ0rDutS1HHIccghcjQ1gwdc7teLmdkKoHZwGRis7hoXU3fcI4zzLAgIAAiYP6MTWUIagaQ5ks8fyMi8RLMUQs3Q4hmUrYJY2d7t6OKduGUeJUGbsqwBDXSIEtGUI5MGROCE2LTUz4IW5Y1BxMh2EM+wfNVQVpLrwY0yu5wBVdZIlzSASUGcy6BwKbxWDmtQZhFEgc2D1cHyZUBERCE2PFgKAAIAxFpUVTQOQEAwNQ6aD7jE/f3ZZQazmtXgkhArfasClpkAKPVgBQBUAwDkxHySynVFBseY0dmYP+AzHvfPW2ox29QygKUIAOtbAQaVuFHFbEKXPsUvayoRl6bGJt7M7g9kuH7uDVfb1TCryFI5w8FFxljVxmaNzfqMP+CqUcUncZ80Ozbxek228GZkci7mMak6RKyNLFYj4uZWrRXOSYEM7/SM4pOBzbwxOgaNNfOhmHHxf4y1KWkk01Z9nRXNaZl+fT7k9cmBy9DCKIyL2jp3/mNNuZypS0d9A1q5c3IgOoezXp/qxt5EY94y2+DC3MchB9PQ0NZk1TgX1eewKeTN4P7pBecTGPvQVgiddGBba7PNnO40ue7HxsTecJo/HBv9xL0SrS127XNCCPeNy8zA9EJL82tjI6PXWq7E+RDc85Ny89mZ8+7F7Zvw5AzuBmcvhNCtT9+9YC2SuvUUbXQunj13yYVw7+oL55wl5f5TNIGLyLleFUL/83tKKXWx69ZNp+TFS5d7VERMX/9lPrIbtNZadt10N2496ZeP/5f9OhJ9r6+E0YIUptxHjfhFP+7HCLS8ftUiBnY5Y8x/rdaihqEWi4hWkFfrbVKIdqZuPW6xHZ++wOiQbR8wLUL52tZjvZrQQdFcHtNyT3TH56+a9M9f8i8YYFKFxOyNQd8gYuc3SicSOphQbJmPPU+s1mTXwJD9+QuMaTeDITH7YrD+YwN/L68AKIP4g6YhNfD45gd8p5Qf9wD+MR+6Oj6rTmMGyLEhMddjkF9b5bLyW30bHAD5PJ1giFP8BuV96BmAwW8/zAo/5Vo+5uDP8tLC/NyshCWnFB3YePlPMmWtTZDr1RMUWvQUmJcbdGRZLTkm5sKS+hPLO9geHpGlotYoZWFybml1ZSubTslkvKGuprrKVZoK42Sd56PCnZXVpbnJAifm8HaMPkzNzrO4mYmC2mpOp5QkVotYA9V0oIIg633Pvd0qjE/McGJOsROH7cUFHg+zGZ1OeA2q3tUZRqqYw7WW3hsFD7gRF7cD85bpmUmKMXPzD7LGpMlNUEzq7BvVPD83E4g5HZw4uXKRUsLC/Zy16WQC4wJSSQV80oUSMjHLvGnf9gTLndw+myFXEJDqgEj/jdccCEnPgeAQUw/3AWQzaRVFKhynmTFOjxXHC4/2IykjInXGBD8CRlofHxbGi2OxMHTJHNhPOmdtNsMXjxXOhwgTfuJRKXTLA5Tv7GcaSAclEZR6nlTWJ/x7ZaGJ/7EDxvCFDoqJ9BN7BBceRw6pEEkLCzYJL3yOHhKWuPV5guJLNwfvD4eLFvgQNXLWbYKDB4OyT+yAhjd0NOK69UgkedvEzHQBosphjoR8DBuJQX531u3vjx0+yBcy0Nj0Ps/aLjQT7v3RI+RQt3+f2yuPHbHv6T4nsgEA) + + --- + + - [React Router (Beta)](/docs/quickstarts/react-router) + - Easily add secure, edge- and SSR-friendly authentication to React Router with Clerk. + - {} ## Explore by backend framework diff --git a/docs/manifest.json b/docs/manifest.json index d3e4639d9a..c9ba7a21ef 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -30,6 +30,12 @@ "href": "/docs/quickstarts/nextjs", "icon": "nextjs" }, + { + "title": "React Router", + "tag": "(Beta)", + "href": "/docs/quickstarts/react-router", + "icon": "react-router" + }, { "title": "Remix", "href": "/docs/quickstarts/remix", @@ -579,6 +585,17 @@ } ] ] + }, + { + "title": "OIDC", + "items": [ + [ + { + "title": "Custom provider", + "href": "/docs/authentication/enterprise-connections/oidc/custom-provider" + } + ] + ] } ] ] @@ -1673,8 +1690,8 @@ "href": "/docs/custom-flows/oauth-connections" }, { - "title": "SAML connections", - "href": "/docs/custom-flows/saml-connections" + "title": "Enterprise connections", + "href": "/docs/custom-flows/enterprise-connections" }, { "title": "Sign out", @@ -1861,17 +1878,6 @@ "title": "Overview", "href": "/docs/references/react/overview" }, - { - "title": "Guides", - "items": [ - [ - { - "title": "Add React Router", - "href": "/docs/references/react/add-react-router" - } - ] - ] - }, { "title": "Client-side Helpers", "items": [ @@ -2282,21 +2288,16 @@ "href": "/docs/references/expo/overview" }, { - "title": "useLocalCredentials()", - "href": "/docs/references/expo/use-local-credentials" - }, - { - "title": "Web support", - "collapse": true, + "title": "Hooks", "items": [ [ { - "title": "Overview", - "href": "/docs/references/expo/web-support/overview" + "title": "useLocalCredentials()", + "href": "/docs/references/expo/use-local-credentials" }, { - "title": "Add custom sign-up and sign-in pages", - "href": "/docs/references/expo/web-support/custom-signup-signin-pages" + "title": "useOAuth()", + "href": "/docs/references/expo/use-oauth" } ] ] @@ -2312,6 +2313,26 @@ { "title": "Use biometrics with local credentials", "href": "/docs/references/expo/local-credentials" + }, + { + "title": "Offline support", + "href": "/docs/references/expo/offline-support" + } + ] + ] + }, + { + "title": "Web support", + "collapse": true, + "items": [ + [ + { + "title": "Overview", + "href": "/docs/references/expo/web-support/overview" + }, + { + "title": "Add custom sign-up and sign-in pages", + "href": "/docs/references/expo/web-support/custom-signup-signin-pages" } ] ] @@ -2382,6 +2403,55 @@ ] ] }, + { + "title": "React Router", + "collapse": true, + "icon": "react-router", + "tag": "(Beta)", + "items": [ + [ + { + "title": "Overview", + "href": "/docs/references/react-router/overview" + }, + { + "title": "Guides", + "items": [ + [ + { + "title": "Read session and user data", + "href": "/docs/references/react-router/read-session-data" + }, + { + "title": "Add custom sign up and sign in pages", + "href": "/docs/references/react-router/custom-signup-signin-pages" + }, + { + "title": "Library mode", + "href": "/docs/references/react-router/library-mode" + } + ] + ] + }, + { + "title": "General References", + "items": [ + [ + { + "title": "`rootAuthLoader()`", + "wrap": false, + "href": "/docs/references/react-router/root-auth-loader" + }, + { + "title": "`getAuth()`", + "href": "/docs/references/react-router/get-auth" + } + ] + ] + } + ] + ] + }, { "title": "Remix", "collapse": true, diff --git a/docs/manifest.schema.json b/docs/manifest.schema.json index dce30cb164..1909c9e4e3 100644 --- a/docs/manifest.schema.json +++ b/docs/manifest.schema.json @@ -125,6 +125,7 @@ "react", "redwood", "remix", + "react-router", "rocket", "route", "ruby", @@ -137,7 +138,8 @@ "user-circle", "user-dotted-circle", "vue", - "x" + "x", + "expo" ] } } diff --git a/docs/organizations/verify-user-permissions.mdx b/docs/organizations/verify-user-permissions.mdx index 1d0063c620..b46651b529 100644 --- a/docs/organizations/verify-user-permissions.mdx +++ b/docs/organizations/verify-user-permissions.mdx @@ -24,7 +24,7 @@ The following examples work for both SSR and CSR. The following example uses the `` component to only render the form for users with the correct permission. The example uses the `fallback` prop to render a different UI if the user is not authorized. - ```tsx {{ filename: '/app/dashboard/settings/form.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/form.tsx' }} 'use client' import { Protect } from '@clerk/nextjs' @@ -44,7 +44,7 @@ The following examples work for both SSR and CSR. The following example uses `has()` to inspect a user's permissions granularly. If the user doesn't have the permission, `has()` returns `false`, causing the component to return `null` instead of rendering its children. - ```tsx {{ filename: '/app/dashboard/settings/form.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/form.tsx' }} 'use client' import { useAuth } from '@clerk/nextjs' @@ -76,7 +76,7 @@ The following examples work for both SSR and CSR. > [!WARNING] > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks). - ```tsx {{ filename: '/app/dashboard/settings/layout.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/layout.tsx' }} import type { PropsWithChildren } from 'react' import { Protect } from '@clerk/nextjs' @@ -92,7 +92,7 @@ The following examples work for both SSR and CSR. > [!WARNING] > Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks). - ```tsx {{ filename: '/app/dashboard/settings/layout.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/layout.tsx' }} import type { PropsWithChildren } from 'react' import { auth } from '@clerk/nextjs/server' @@ -121,7 +121,7 @@ The following examples work for both SSR and CSR. - If the user is authenticated but is not authorized (as in, does not have the `org:team_settings:read` permission), `auth.protect()` will throw a `404` error. - If the user is both authenticated and authorized, `auth.protect()` will return the user's `userId`. - ```tsx {{ filename: '/app/dashboard/settings/page.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/page.tsx' }} import { auth } from '@clerk/nextjs/server' export default async function Page() { @@ -322,7 +322,7 @@ You can pass a `role` the same way you can pass a `permission` in all the exampl The following example uses ``'s `condition` prop to conditionally render its children if the user has the correct role. - ```tsx {{ filename: '/app/dashboard/settings/Page.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/Page.tsx' }} import { Protect } from '@clerk/nextjs' export default function Page() { @@ -347,7 +347,7 @@ You can pass a `role` the same way you can pass a `permission` in all the exampl - If the user is authenticated but is not authorized (as in, does not have the `org:admin` or `org:billing_manager` role), `auth.protect()` will throw a `404` error. - If the user is both authenticated and authorized, `auth.protect()` will return the user's `userId`. - ```tsx {{ filename: '/app/dashboard/settings/page.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/page.tsx' }} import { auth } from '@clerk/nextjs/server' export default async function Page() { @@ -363,7 +363,7 @@ You can pass a `role` the same way you can pass a `permission` in all the exampl The following example uses `has()` to inspect a user's roles granularly. If the user doesn't have the correct role, `has()` returns `false`, causing the component to return `null` instead of rendering its children. - ```tsx {{ filename: '/app/dashboard/settings/form.tsx' }} + ```tsx {{ filename: 'app/dashboard/settings/form.tsx' }} 'use client' import { useAuth } from '@clerk/nextjs' diff --git a/docs/quickstarts/chrome-extension.mdx b/docs/quickstarts/chrome-extension.mdx index 3cb0d1d644..f361d050e4 100644 --- a/docs/quickstarts/chrome-extension.mdx +++ b/docs/quickstarts/chrome-extension.mdx @@ -21,7 +21,7 @@ description: Add authentication and user management to your Chrome Extension wit - Create a new app with Plasmo - Install `@clerk/chrome-extension` - Set your Clerk API keys - - Add `` and Clerk components to your app + - Add `` and Clerk components to your app - Configure your app to use a consistent CRX ID - Build, load, and test your Chrome Extension diff --git a/docs/quickstarts/expo.mdx b/docs/quickstarts/expo.mdx index 08b1465e5e..c9d126d8cf 100644 --- a/docs/quickstarts/expo.mdx +++ b/docs/quickstarts/expo.mdx @@ -27,7 +27,7 @@ description: Add authentication and user management to your Expo app with Clerk. > - Install `@clerk/expo` - Set your Clerk API keys - - Add `` + - Add `` - Protect specific pages with authentication - Use Clerk hooks to enable users to sign in and out @@ -209,7 +209,7 @@ description: Add authentication and user management to your Expo app with Clerk. First, protect your sign-up and sign-in pages. - 1. Create an `(auth)` route group. This will group your sign-up and sign-in pages. + 1. Create an `(auth)` [route group](https://docs.expo.dev/router/layouts/#groups). This will group your sign-up and sign-in pages. 1. In the `(auth)` group, create a `_layout.tsx` file. 1. Paste the following code. The [`useAuth()`](/docs/references/react/use-auth) hook is used to access the user's authentication state. If the user is already signed in, they will be redirected to the home page. @@ -410,14 +410,18 @@ description: Add authentication and user management to your Expo app with Clerk. For more information about building these custom flows, including guided comments in the code examples, see the [Build a custom email/password authentication flow](/docs/custom-flows/email-password) guide. - ### Protect your pages + ### Conditionally render content You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). For this quickstart, you'll use: - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. - To get started, create a `(home)` [route group](https://docs.expo.dev/router/layouts/#groups) with the following layout file: + To get started: + + 1. Create a `(home)` route group. + 1. In the `(home)` group, create a `_layout.tsx` file. + 1. Paste the following code. ```tsx filename="app/(home)/_layout.tsx" import { Stack } from 'expo-router/stack' @@ -427,7 +431,7 @@ description: Add authentication and user management to your Expo app with Clerk. } ``` - Then, in the same folder, create an `index.tsx` file and add the following code. It displays the user's email if they're signed in, or sign-in and sign-up links if they're not: + Then, in the same folder, create an `index.tsx` file with the following code. It displays the user's email if they're signed in, or sign-in and sign-up links if they're not: ```tsx filename="app/(home)/index.tsx" import { SignedIn, SignedOut, useUser } from '@clerk/clerk-expo' diff --git a/docs/quickstarts/nextjs.mdx b/docs/quickstarts/nextjs.mdx index aea98c36c5..3d1c45d557 100644 --- a/docs/quickstarts/nextjs.mdx +++ b/docs/quickstarts/nextjs.mdx @@ -21,7 +21,7 @@ description: Add authentication and user management to your Next.js app with Cle - Install `@clerk/nextjs` - Set your Clerk API keys - Add `clerkMiddleware()` - - Add `` and Clerk components + - Add `` and Clerk components diff --git a/docs/quickstarts/react-router.mdx b/docs/quickstarts/react-router.mdx new file mode 100644 index 0000000000..cdaab7e726 --- /dev/null +++ b/docs/quickstarts/react-router.mdx @@ -0,0 +1,220 @@ +--- +title: React Router Quickstart (Beta) +description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your React Router application. +--- + + + - Install `@clerk/react-router` + - Set your Clerk API keys + - Configure `rootAuthLoader()` + - Add `` and Clerk components + + +Clerk's [React Router SDK](/docs/references/react-router/overview) provides prebuilt components, hooks, and stores to make it easy to integrate authentication and user management in your React Router app. This guide assumes that you're using [React Router v7 or later](https://api.reactrouter.com/v7). + + + ### Install `@clerk/react-router` + + Run the following command to install the SDK: + + + ```bash {{ filename: 'terminal' }} + npm install @clerk/react-router + ``` + + ```bash {{ filename: 'terminal' }} + yarn add @clerk/react-router + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/react-router + ``` + + + ### Set your Clerk API keys + + + Add the following keys to your `.env` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable and Secret Key. + 1. Paste your keys into your `.env` file. + + The final result should resemble the following: + + + ```env {{ filename: '.env' }} + VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} + CLERK_SECRET_KEY={{secret}} + ``` + + ### Configure `rootAuthLoader()` + + The `rootAuthLoader()` function provides access to authentication state in any React Router route. + + The following code shows how to add this function to your `root.tsx` file. If you're using [Clerk's React Router quickstart](https://github.com/clerk/clerk-react-router-quickstart) or the [React Router template](https://reactrouter.com/start/framework/installation), most of this code will already be present. + + To load additional data or configure options, see the [`rootAuthLoader()`](/docs/references/react-router/root-auth-loader) reference. + + ```tsx {{ filename: 'app/root.tsx', mark: [1, [6, 8]], collapsible: true }} + import { rootAuthLoader } from '@clerk/react-router/ssr.server' + import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router' + import type { Route } from './+types/root' + import stylesheet from './app.css?url' + + export async function loader(args: Route.LoaderArgs) { + return rootAuthLoader(args) + } + + export const links: Route.LinksFunction = () => [ + { rel: 'preconnect', href: 'https://fonts.googleapis.com' }, + { + rel: 'preconnect', + href: 'https://fonts.gstatic.com', + crossOrigin: 'anonymous', + }, + { + rel: 'stylesheet', + href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap', + }, + { rel: 'stylesheet', href: stylesheet }, + ] + + export function Layout({ children }: { children: React.ReactNode }) { + return ( + + + + + + + + + {children} + + + + + ) + } + + export default function App() { + return + } + + export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) { + let message = 'Oops!' + let details = 'An unexpected error occurred.' + let stack: string | undefined + + if (isRouteErrorResponse(error)) { + message = error.status === 404 ? '404' : 'Error' + details = + error.status === 404 ? 'The requested page could not be found.' : error.statusText || details + } else if (import.meta.env.DEV && error && error instanceof Error) { + details = error.message + stack = error.stack + } + + return ( +
+

{message}

+

{details}

+ {stack && ( + 
+            {stack}
+
+ )} +
+ ) + } + ``` + + ### Add `` and Clerk components to your app + + + + It's required to pass `loaderData` to the `` component. This data is provided by the `rootAuthLoader()` function. It's also recommended to pass the `signUpFallbackRedirectUrl` and `signInFallbackRedirectUrl` props. These specify the fallback URL to redirect to after the user signs up or signs in, respectively, if there's no `redirect_url` in the path already. + + You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). + + The following example adds `` and creates a header using the following Clerk components: + + - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. + - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. + - [``](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options. + - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](/docs/deployments/clerk-environment-variables) are set for the sign-in URL, this component links to the [Account Portal sign-in page](/docs/customization/account-portal/overview#sign-in). + + ```tsx {{ filename: 'app/root.tsx' }} + // Other imports + + import { ClerkProvider, SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/react-router' + + export default function App({ loaderData }: Route.ComponentProps) { + return ( + +
+ + + + + + +
+
+ +
+ + ) + } + + // Rest of the root.tsx code + ``` + + ### Create your first user + + Run your project with the following command: + + + ```bash {{ filename: 'terminal' }} + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + + Visit your app's homepage at [`http://localhost:5173`](http://localhost:5173). Sign up to create your first user. + diff --git a/docs/quickstarts/react.mdx b/docs/quickstarts/react.mdx index 9951acbcd9..a7384e1c8d 100644 --- a/docs/quickstarts/react.mdx +++ b/docs/quickstarts/react.mdx @@ -23,7 +23,7 @@ description: Add authentication and user management to your React app with Clerk - Create a new React app using Vite - Install `@clerk/clerk-react` - Set your Clerk API keys - - Add `` + - Add `` - Create a header with Clerk components for users to sign in and out @@ -148,7 +148,7 @@ description: Add authentication and user management to your React app with Clerk ### Create a header with Clerk components - You can control which content signed-in and signed-out users can see with the [prebuilt control components](/docs/components/overview#what-are-control-components). Create a header using the following components: + You can control which content signed-in and signed-out users can see with the [prebuilt control components](/docs/components/overview#what-are-control-components). The following example creates a header using the following components: - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. @@ -195,7 +195,10 @@ description: Add authentication and user management to your React app with Clerk ## Next step: Add routing with React Router -React has many options for handling routing, and you are free to choose the option that suits you best. If you would like to learn how to integrate React Router's latest Data API-based router (also known as Data Router), see the [dedicated guide](/docs/references/react/add-react-router). +React Router can be integrated with Clerk in two ways: + +- As a framework: Use Clerk's built-in [React Router integration](/docs/quickstarts/react-router) +- As a library: Manually integrate React Router into your Clerk application using [library mode](/docs/references/react-router/library-mode) ## More resources diff --git a/docs/quickstarts/tanstack-start.mdx b/docs/quickstarts/tanstack-start.mdx index 94725c86ef..33b15bf8c5 100644 --- a/docs/quickstarts/tanstack-start.mdx +++ b/docs/quickstarts/tanstack-start.mdx @@ -26,7 +26,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat - Install `@clerk/tanstack-start` - Set your Clerk API keys - Add `createClerkHandler()` - - Add `` + - Add `` - Protect your pages diff --git a/docs/references/astro/overview.mdx b/docs/references/astro/overview.mdx index 02c00f4563..559c351041 100644 --- a/docs/references/astro/overview.mdx +++ b/docs/references/astro/overview.mdx @@ -1,5 +1,5 @@ --- -title: Astro and Clerk +title: Clerk Astro SDK description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Astro application. --- diff --git a/docs/references/chrome-extension/overview.mdx b/docs/references/chrome-extension/overview.mdx index df84258fed..2f2ba6ffd8 100644 --- a/docs/references/chrome-extension/overview.mdx +++ b/docs/references/chrome-extension/overview.mdx @@ -1,6 +1,6 @@ --- -title: Chrome Extension SDK -description: Learn how to integrate Clerk into your Chrome Extension +title: Clerk Chrome Extension SDK +description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Chrome Extension. --- Clerk provides a Chrome Extension SDK that allows you to easily integrate Clerk into your Chrome Extension. This SDK provides a simple way to authenticate users and manage their sessions. diff --git a/docs/references/expo/local-credentials.mdx b/docs/references/expo/local-credentials.mdx index 75ff945425..ecd1ce0080 100644 --- a/docs/references/expo/local-credentials.mdx +++ b/docs/references/expo/local-credentials.mdx @@ -41,7 +41,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your The following example demonstrates how to use `useLocalCredentials()` in a custom flow for signing users in. - ```tsx {{ filename: '/app/sign-in.tsx' }} + ```tsx {{ filename: 'app/sign-in.tsx' }} import { useSignIn } from '@clerk/clerk-expo' import { useLocalCredentials } from '@clerk/clerk-expo/local-credentials' import { Link, Stack, useRouter } from 'expo-router' @@ -117,7 +117,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your The following example demonstrates how to use the `userOwnsCredentials` and `clearCredentials` properties of the `useLocalCredentials()` hook in order to remove the stored credentials if those belong to the signed in user. - ```tsx {{ filename: '/app/user.tsx' }} + ```tsx {{ filename: 'app/user.tsx' }} import { useUser, useClerk } from '@clerk/clerk-expo' import { useLocalCredentials } from '@clerk/clerk-expo/local-credentials' @@ -143,7 +143,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your The following example demonstrates how to use `userOwnsCredentials` and `setCredentials` properties of the `useLocalCredentials()` hook in order to update the stored credentials if those belong to the signed in user. - ```tsx {{ filename: '/app/update-user.tsx' }} + ```tsx {{ filename: 'app/update-user.tsx' }} import { useUser, useClerk } from '@clerk/clerk-expo' import { useLocalCredentials } from '@clerk/clerk-expo/local-credentials' diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx new file mode 100644 index 0000000000..a281071efa --- /dev/null +++ b/docs/references/expo/offline-support.mdx @@ -0,0 +1,73 @@ +--- +title: Enable offline support in your Expo app +description: Learn how to enable offline support in your Expo app with Clerk. +--- + +> [!WARNING] +> **This is an experimental API.** +> +> The `__experimental_resourceCache` property introduced in this guide is an experimental feature. It is subject to change in future updates, so use it cautiously in production environments. Ensure thorough testing and stay informed through [the package's changelog](https://github.com/clerk/javascript/blob/main/packages/expo/CHANGELOG.md). + +The Clerk Expo SDK provides enhanced offline support to improve reliability and user experience. This update enables your app to bootstrap offline using cached Clerk resources, ensuring quick initialization without requiring an internet connection. + +It offers the following benefits: + +- Initialization of the Clerk SDK is now more resilient to network failures. +- Faster resolution of the `isLoaded` property and the [``](/docs/components/control/clerk-loaded) control component with only a single network fetch attempt. If the fetch fails, it gracefully falls back to cached resources. +- Network errors are no longer muted, allowing developers to catch and handle them effectively in their custom flows. +- The [`getToken()`](/docs/references/javascript/session#get-token) function in the `useAuth()` hook now supports returning cached tokens, minimizing disruptions caused by network failures. + +## How to enable offline support + +To enable offline support in your Expo app, follow these steps: + + + ### Install the necessary peer dependencies + + The `expo-secure-store` package is required to use the offline support feature. + + + ```bash {{ filename: 'terminal' }} + npm install expo-secure-store + ``` + + ```bash {{ filename: 'terminal' }} + yarn add expo-secure-store + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add expo-secure-store + ``` + + + ### Use the `__experimental_resourceCache` property on `ClerkProvider` + + On [``](/docs/components/clerk-provider), pass the `secureStore` object to the `__experimental_resourceCache` property, as shown in the following example: + + ```tsx {{ filename: 'app/_layout.tsx', mark: [4, [14, 18]] }} + import { ClerkProvider, ClerkLoaded } from '@clerk/clerk-expo' + import { Slot } from 'expo-router' + import { tokenCache } from '../token-cache' + import { secureStore } from '@clerk/clerk-expo/secure-store' + + export default function RootLayout() { + const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY! + + if (!publishableKey) { + throw new Error('Add EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY to your .env file') + } + + return ( + + + + + + ) + } + ``` + diff --git a/docs/references/expo/overview.mdx b/docs/references/expo/overview.mdx index bf8578c3fd..8afb14999e 100644 --- a/docs/references/expo/overview.mdx +++ b/docs/references/expo/overview.mdx @@ -1,5 +1,5 @@ --- -title: Expo and Clerk +title: Clerk Expo SDK description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Expo application. --- diff --git a/docs/references/expo/use-local-credentials.mdx b/docs/references/expo/use-local-credentials.mdx index 77286541fc..f08349cd38 100644 --- a/docs/references/expo/use-local-credentials.mdx +++ b/docs/references/expo/use-local-credentials.mdx @@ -6,6 +6,7 @@ description: Clerk's useLocalCredentials() hook enables you to store and access The `useLocalCredentials()` hook enables you to store a user's password credentials on their device and subsequently use biometrics for sign-in. This enhances the user experience by allowing users to sign in using Face ID or another biometric authentication method during future sign-ins. > [!WARNING] +> This hook isn't supported in web apps and can only be used in native apps. > This API is available only for [@clerk/clerk-expo v2](/docs/upgrade-guides/expo-v2/upgrade) >=2.2.0. > Be aware that this works only for sign-in attempts with the [password strategy](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies). diff --git a/docs/references/expo/use-oauth.mdx b/docs/references/expo/use-oauth.mdx index 8c686d8c9b..560328433e 100644 --- a/docs/references/expo/use-oauth.mdx +++ b/docs/references/expo/use-oauth.mdx @@ -3,7 +3,7 @@ title: '`useOAuth()`' description: Clerk's useOAuth() hook is used to create a new OAuth flow. --- -The `useOAuth()` hook is used to create a new OAuth flow. +The `useOAuth()` hook is used to create a new OAuth flow. It can be used in both web and native apps. ## Parameters diff --git a/docs/references/javascript/clerk/clerk.mdx b/docs/references/javascript/clerk/clerk.mdx index 05425728ea..a576657395 100644 --- a/docs/references/javascript/clerk/clerk.mdx +++ b/docs/references/javascript/clerk/clerk.mdx @@ -148,21 +148,21 @@ function authenticateWithMetamask({ - `redirectUrl?` - `string | undefined` - Full URL or path to navigate to after a successful sign in or sign up. + The full URL or path to navigate to after a successful sign in or sign up. --- - `signUpContinueUrl?` - `string | undefined` - The location to continue navigation to in the sign up process if data is missing. + The URL to navigate to in the sign-up process if data is missing. --- - `customNavigate?` - `((to: string) => Promise | unknown) | undefined` - Allows you to define a custom navigation function + A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. ### `authenticateWithCoinbaseWallet()` @@ -181,21 +181,66 @@ function authenticateWithCoinbaseWallet({ - `redirectUrl?` - `string | undefined` - Full URL or path to navigate to after a successful sign in or sign up. + The full URL or path to navigate to after a successful sign in or sign up. --- - `signUpContinueUrl?` - `string | undefined` - The location to continue navigation to in the sign up process if data is missing. + The full URL or path to navigate to in the sign-up process if data is missing. --- - `customNavigate?` - `((to: string) => Promise | unknown) | undefined` - Allows you to define a custom navigation function + A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. + + +### `authenticateWithOKXWallet()` + +Starts a sign-in flow that uses the OKX Wallet to authenticate the user using their Web3 wallet address. + +```typescript +function authenticateWithOKXWallet(props?: AuthenticateWithOKXWalletParams): Promise +``` + +#### `AuthenticateWithOKXWalletParams` + + + - `redirectUrl?` + - `string | undefined` + + The full URL or path to navigate to after a successful sign-in or sign-up. + + --- + + - `signUpContinueUrl?` + - `string | undefined` + + The full URL or path to navigate to in the sign-up process if data is missing. + + --- + + - `customNavigate?` + - `((to: string) => Promise | unknown) | undefined` + + A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. + + --- + + - `unsafeMetadata?` + - [`SignUpUnsafeMetadata`](/docs/references/javascript/types/metadata#sign-up-unsafe-metadata) + + Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created `User` object. + + --- + + - `legalAccepted?` + - `boolean` + + The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents. ### `authenticateWithWeb3()` @@ -215,21 +260,21 @@ function authenticateWithWeb3({ - `redirectUrl?` - `string | undefined` - Full URL or path to navigate to after a successful sign in or sign up. + The full URL or path to navigate to after a successful sign in or sign up. --- - `signUpContinueUrl?` - `string | undefined` - The location to continue navigation to in the sign up process if data is missing. + The full URL or path to navigate to in the sign-up process if data is missing. --- - `customNavigate?` - `((to: string) => Promise | unknown) | undefined` - Allows you to define a custom navigation function + A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. --- @@ -264,7 +309,7 @@ class Clerk { - `options?` - [DomainOrProxyUrl](#domain-or-proxy-url) | undefined - The domain or proxy URL used to connect to Clerk + The domain or proxy URL used to connect to Clerk. #### `DomainOrProxyUrl` @@ -275,14 +320,14 @@ Only one of the two properties are allowed to be set at a time. - `proxyUrl?` - `never | string | ((url: URL) => string)` - The proxy URL used to connect to Clerk. If a function, will be called with a `URL` made from `window.location.href` + The proxy URL used to connect to Clerk. If a function, will be called with a `URL` made from `window.location.href`. --- - `domain?` - `never | string | ((url: URL) => string)` - The domain used to connect to Clerk. If a function, will be called with a `URL` made from `window.location.href` + The domain used to connect to Clerk. If a function, will be called with a `URL` made from `window.location.href`. ### `load()` @@ -331,7 +376,7 @@ All props below are optional. - `polling` - `boolean | undefined` - Dictates if we should poll against Clerk's backend every 5 minutes. Defaults to `true` + Dictates if we should poll against Clerk's backend every 5 minutes. Defaults to `true`. --- @@ -345,21 +390,21 @@ All props below are optional. - `standardBrowser` - `boolean | undefined` - Controls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to `true` + Controls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to `true`. --- - `supportEmail` - `string | undefined` - Optional support email for display in authentication screens + Optional support email for display in authentication screens. --- - `touchSession` - `boolean | undefined` - Indicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to `true` + Indicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to `true`. --- @@ -412,17 +457,24 @@ All props below are optional. --- - - `allowedRedirectOrigins` - - `Array | undefined` + - `allowedRedirectOrigins?` + - `Array` + + 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` - Optional array of domains used to validate against the query param of an auth redirect.
If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. + 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. --- - `isSatellite` - `boolean | ((url: URL) => boolean) | undefined` - Clerk Flag for satellite apps. Experimental. + Clerk flag for satellite apps. Experimental. --- @@ -461,7 +513,7 @@ function signOut( - `redirectUrl?` - `string` - Full URL or path to navigate to after sign out is complete. + The full URL or path to navigate to after sign out is complete. ## Components diff --git a/docs/references/javascript/overview.mdx b/docs/references/javascript/overview.mdx index 55031d0fdf..289ee7529c 100644 --- a/docs/references/javascript/overview.mdx +++ b/docs/references/javascript/overview.mdx @@ -1,6 +1,6 @@ --- -title: ClerkJS -description: ClerkJS is Clerk's foundational JavaScript library for building user management and authentication. +title: Clerk JavaScript SDK +description: Clerk's JavaScript SDK is a foundational library for building user management and authentication. --- ClerkJS is our foundational JavaScript library for building user management and authentication. It enables you to register, sign in, verify and manage users for your application using highly customizable flows. diff --git a/docs/references/javascript/sign-in/authenticate-with.mdx b/docs/references/javascript/sign-in/authenticate-with.mdx index bd7949b32c..de335f09e1 100644 --- a/docs/references/javascript/sign-in/authenticate-with.mdx +++ b/docs/references/javascript/sign-in/authenticate-with.mdx @@ -19,16 +19,20 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi - `strategy` - - [OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' + - [OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' | 'enterprise\_sso' - The strategy corresponding to the OAuth provider. For example: `oauth_facebook`, `oauth_github`, etc. + The strategy to use for authentication. The following strategies are supported: + + - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). + - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. --- - `redirectUrl` - `string` - Full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `` component. + The full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `` component. --- @@ -36,6 +40,13 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi - `string` The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in. + + --- + + - `identifier` + - `string | undefined` + + Identifier to use for targeting an enterprise connection at sign-in. ### `authenticateWithMetamask()` @@ -66,6 +77,14 @@ function authenticateWithCoinbaseWallet(): Promise | - | - | | `Promise` | A `Promise` which resolves to the current [`SignIn`][signin-ref]. | +### `authenticateWithOKXWallet()` + +Starts a sign-in flow that uses the OKX Wallet to authenticate the user using their Web3 wallet address. Returns a `Promise` which resolves to the current [`SignIn`][signin-ref]. + +```typescript +function authenticateWithOKXWallet(): Promise +``` + ### `authenticateWithWeb3()` Starts a sign-in flow that authenticates the user against their Web3 wallet address. diff --git a/docs/references/javascript/sign-in/first-factor.mdx b/docs/references/javascript/sign-in/first-factor.mdx index 424004f283..2191b569ca 100644 --- a/docs/references/javascript/sign-in/first-factor.mdx +++ b/docs/references/javascript/sign-in/first-factor.mdx @@ -28,6 +28,7 @@ function prepareFirstFactor(params: PrepareFirstFactorParams): Promise - `phone_code`: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The `phone_number_id` parameter can also be specified to select which of the user's known phone numbers the SMS will go to. - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. + - `web3_okx_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). --- @@ -49,7 +50,7 @@ function prepareFirstFactor(params: PrepareFirstFactorParams): Promise - `web3WalletId?` - `string` - Unique identifier for the user's Web3 wallet address. This parameter will work only when the `web3_metamask_signature` or `web3_coinbase_wallet_signature` strategy is specified. + Unique identifier for the user's Web3 wallet address. This parameter will work only when the `strategy` is set to `web3_metamask_signature`, `web3_coinbase_wallet_signature`, or `web3_okx_wallet_signature`. --- @@ -97,6 +98,7 @@ function attemptFirstFactor(params: AttemptFirstFactorParams): Promise - `'password'`: The verification will attempt to be completed with the user's password. - `'web3_metamask_signature'`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). - `'web3_coinbase_wallet_signature'`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). + - `'web3_okx_wallet_signature'`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). - `'passkey'`: The verification will attempt to be completed using the user's passkey. - `'reset_password_phone_code'`: Used when the user is trying to reset their password. The user will receive a one-time code via SMS. - `'reset_password_email_code'`: Used when the user is trying to reset their password. The user will receive a one-time code via email. diff --git a/docs/references/javascript/sign-in/sign-in.mdx b/docs/references/javascript/sign-in/sign-in.mdx index f435a46aaf..9eac85f5f2 100644 --- a/docs/references/javascript/sign-in/sign-in.mdx +++ b/docs/references/javascript/sign-in/sign-in.mdx @@ -128,6 +128,7 @@ function create(params: SignInCreateParams): Promise - `phone_code`: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The `phone_number_id` parameter can also be specified to select which of the user's known phone numbers the SMS will go to. - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. + - `web3_okx_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). - `ticket`: The user will be authenticated via the ticket _or token_ generated from the Backend API. - `google_one_tap`: The user will be authenticated with the Google One Tap UI. It's recommended to use [`authenticateWithGoogleOneTap()`](/docs/components/authentication/google-one-tap#authenticate-with-google-one-tap) instead, as it will also set the user's current session as active for you. @@ -258,6 +259,7 @@ In addition to the methods listed above, the `SignIn` class also has the followi - [`authenticateWithRedirect()`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect) - [`authenticateWithMetamask()`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-metamask) - [`authenticateWithCoinbaseWallet()`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-coinbase-wallet) +- [`authenticateWithOKXWallet()`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-okx-wallet) - [`authenticateWithWeb3()`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-web3) ## Example diff --git a/docs/references/javascript/sign-up/authenticate-with.mdx b/docs/references/javascript/sign-up/authenticate-with.mdx index c98405e5ad..60c9f35c44 100644 --- a/docs/references/javascript/sign-up/authenticate-with.mdx +++ b/docs/references/javascript/sign-up/authenticate-with.mdx @@ -38,26 +38,27 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi --- - `strategy` - - `'oauth_' | 'saml'` + - `'oauth_' | 'saml' | 'enterprise_sso'` The strategy to use for authentication. The following strategies are supported: - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). - - `saml`: The user will be authenticated with SAML. + - `saml`: The user will be authenticated with SAML. **Deprecated** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. --- - `identifier` - `string | undefined` - Identifier to use for targeting a SAML connection at sign-up. + Identifier to use for targeting an enterprise connection at sign-up. --- - `emailAddress` - `string | undefined` - Email address to use for targeting a SAML connection at sign-up. + Email address to use for targeting an enterprise connection at sign-up. --- @@ -171,6 +172,16 @@ function authenticateWithCoinbaseWallet( ): Promise ``` +## `authenticateWithOKXWallet()` + +Starts a sign-up flow that uses the OKX Wallet to authenticate the user using their public Web3 wallet address. + +```typescript +function authenticateWithOKXWallet( + params?: SignUpAuthenticateWithWeb3Params, +): Promise +``` + ### `SignUpAuthenticateWithWeb3Params` @@ -178,13 +189,6 @@ function authenticateWithCoinbaseWallet( - [`SignUpUnsafeMetadata`](/docs/references/javascript/types/metadata#sign-up-unsafe-metadata) Custom fields that will be attached to the [`User`](/docs/references/javascript/user/user) object post-signup. - - --- - - - `legalAccepted?` - - `boolean` - - The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents. [signup-ref]: /docs/references/javascript/sign-up/sign-up diff --git a/docs/references/javascript/sign-up/sign-up.mdx b/docs/references/javascript/sign-up/sign-up.mdx index 52ac67d571..94a3311c4d 100644 --- a/docs/references/javascript/sign-up/sign-up.mdx +++ b/docs/references/javascript/sign-up/sign-up.mdx @@ -338,6 +338,7 @@ In addition to the methods listed above, the `SignUp` class also has the followi - [`authenticateWithRedirect()`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect) - [`authenticateWithMetamask()`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-metamask) - [`authenticateWithCoinbaseWallet()`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-coinbase-wallet) +- [`authenticateWithOKXWallet()`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-okx-wallet) - [`authenticateWithWeb3()`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-web3) ### Verification diff --git a/docs/references/javascript/sign-up/verification.mdx b/docs/references/javascript/sign-up/verification.mdx index 7a15cb0e2c..56ac49d739 100644 --- a/docs/references/javascript/sign-up/verification.mdx +++ b/docs/references/javascript/sign-up/verification.mdx @@ -20,17 +20,19 @@ function prepareVerification(params: PrepareVerificationParams): Promise - `strategy` - - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'oauth_' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'` + - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'enterprise_sso' | 'oauth_' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'` The verification strategy to validate the user's sign-up request. The following strategies are supported: - `phone_code`: Send an SMS with a unique token to input. - `email_code`: Send an email with a unique token to input. - `email_link`: Send an email with a link which validates sign-up - - `saml`: The user will be authenticated with SAML. **Experimental** + - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. + - `web3_okx_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. --- @@ -54,7 +56,7 @@ function attemptVerification(params: AttemptVerificationParams): Promise - `strategy` - - `'phone_code' | 'email_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'` + - `'phone_code' | 'email_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'` The verification strategy to complete the user's sign-up request against. The following strategies are supported: @@ -62,6 +64,7 @@ function attemptVerification(params: AttemptVerificationParams): Promise - `email_code`: Validates an email with a unique token to input. - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. + - `web3_okx_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. --- diff --git a/docs/references/javascript/sign-up/web3-verification.mdx b/docs/references/javascript/sign-up/web3-verification.mdx index e938b76c33..e20aad4e3b 100644 --- a/docs/references/javascript/sign-up/web3-verification.mdx +++ b/docs/references/javascript/sign-up/web3-verification.mdx @@ -23,11 +23,13 @@ function prepareWeb3WalletVerification( - `strategy` - `'web3_metamask_signature'` - `'web3_coinbase_wallet_signature'` + - `'web3_okx_wallet_signature'` The verification strategy to validate the user's sign-up request. The following strategies are supported: - `web3_metamask_signature`: User will need to sign a message and generate a signature using MetaMask browser extension. - `web3_coinbase_wallet_signature`: User will need to sign a message and generate a signature using Coinbase Wallet. + - `web3_okx_wallet_signature`: User will need to sign a message and generate a signature using OKX Wallet. ## `attemptWeb3WalletVerification()` diff --git a/docs/references/javascript/types/sign-in-first-factor.mdx b/docs/references/javascript/types/sign-in-first-factor.mdx index 1d5fc7a6fc..8e4d3892fa 100644 --- a/docs/references/javascript/types/sign-in-first-factor.mdx +++ b/docs/references/javascript/types/sign-in-first-factor.mdx @@ -32,6 +32,7 @@ type SignInFirstFactor = - `"reset_password_email_code"` - `"web3_metamask_signature"` - `"web3_coinbase_wallet_signature"` + - `"web3_okx_wallet_signature"` - [`OAuthStrategy`](/docs/references/javascript/types/oauth) - `"saml"` @@ -54,7 +55,7 @@ type SignInFirstFactor = - `web3WalletId` - `string` - The ID of the Web3 wallet that will be used to sign a message. Populated when the `strategy` is `"web3_metamask_signature"` or `"web3_coinbase_wallet_signature"`. + The ID of the Web3 wallet that will be used to sign a message. Populated when the `strategy` is `"web3_metamask_signature"`, `"web3_coinbase_wallet_signature"`, or `"web3_okx_wallet_signature"`. --- @@ -73,7 +74,7 @@ type SignInFirstFactor = - `primary` - `boolean` - Whether the factor is the primary factor.
Populated when the strategy is `"email_code"`, `"email_link"`, `"phone_code"`, `"web3_metamask_signature"`, `"web3_coinbase_wallet_signature"`, `"reset_password_email_code"`, or `"reset_password_phone_code"`. + Whether the factor is the primary factor.
Populated when the strategy is `"email_code"`, `"email_link"`, `"phone_code"`, `"web3_metamask_signature"`, `"web3_coinbase_wallet_signature"`, `"web3_okx_wallet_signature"`, `"reset_password_email_code"`, or `"reset_password_phone_code"`. ## `EmailCodeFactor` diff --git a/docs/references/javascript/types/verification.mdx b/docs/references/javascript/types/verification.mdx index c0955b8f32..432df00c99 100644 --- a/docs/references/javascript/types/verification.mdx +++ b/docs/references/javascript/types/verification.mdx @@ -48,7 +48,7 @@ An interface that represents the state of the verification process of a sign-in - `unverified`: The verification has not been verified yet. - `verified`: The verification has been verified. - - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [SAML](/docs/custom-flows/saml-connections#saml-account-transfer-flows) authentication flows. + - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [Enterprise SSO](/docs/custom-flows/enterprise-connections#enterprise-account-transfer-flows) authentication flows. - `failed`: The verification has failed. - `expired`: The verification has expired. diff --git a/docs/references/javascript/web3-wallet/verification.mdx b/docs/references/javascript/web3-wallet/verification.mdx index d993b853d1..a3931c3d49 100644 --- a/docs/references/javascript/web3-wallet/verification.mdx +++ b/docs/references/javascript/web3-wallet/verification.mdx @@ -19,11 +19,13 @@ function prepareVerification(params: PrepareWeb3WalletVerificationParams): Promi - `strategy` - `'web3_metamask_signature'` - `'web3_coinbase_wallet_signature'` + - `'web3_okx_wallet_signature'` The verification strategy. Possible strategy values are: - `web3_metamask_signature`: User will need to sign a message and generate a signature using MetaMask browser extension. - `web3_coinbase_wallet_signature`: User will need to sign a message and generate a signature using Coinbase Wallet. + - `web3_okx_wallet_signature`: User will need to sign a message and generate a signature using OKX Wallet. ### `prepareVerification()` returns diff --git a/docs/references/javascript/web3-wallet/web3-wallet.mdx b/docs/references/javascript/web3-wallet/web3-wallet.mdx index 7d3859e005..42591c0f61 100644 --- a/docs/references/javascript/web3-wallet/web3-wallet.mdx +++ b/docs/references/javascript/web3-wallet/web3-wallet.mdx @@ -5,7 +5,7 @@ description: The Web3Wallet object describes a Web3 wallet address. The address The `Web3Wallet` object describes a Web3 wallet address. The address can be used as a proof of identification for users. -Web3 addresses must be verified to ensure that they can be assigned to their rightful owners. The verification is completed via Web3 wallet browser extensions, such as [Metamask](https://metamask.io/) and [Coinbase Wallet](https://www.coinbase.com/wallet). The `Web3Wallet3` object holds all the necessary state around the verification process. +Web3 addresses must be verified to ensure that they can be assigned to their rightful owners. The verification is completed via Web3 wallet browser extensions, such as [Metamask](https://metamask.io/), [Coinbase Wallet](https://www.coinbase.com/wallet), and [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). The `Web3Wallet3` object holds all the necessary state around the verification process. The verification process always starts with the [`Web3Wallet.prepareVerification()`](/docs/references/javascript/web3-wallet/verification#prepare-verification) or [`signIn.prepareFirstFactor()`](/docs/references/javascript/sign-in/first-factor#prepare-first-factor) method, which will send the wallet address to the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }} and will receive a nonce that needs to be signed by the Web3 wallet browser extension. diff --git a/docs/references/nextjs/auth-object.mdx b/docs/references/nextjs/auth-object.mdx index d32ad7e978..7ccbab87e2 100644 --- a/docs/references/nextjs/auth-object.mdx +++ b/docs/references/nextjs/auth-object.mdx @@ -1,9 +1,9 @@ --- -title: '`Auth` object' +title: Auth object description: The Auth object contains information about the current user's session. --- -The `Auth` object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and [`getAuth()`](/docs/references/nextjs/get-auth) helpers, and the `request` object in server contexts. +The `Auth` object contains important information like the current user's session ID, user ID, and organization ID. It also contains methods to check for permissions and retrieve the current user's session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts. ## `Auth` object properties diff --git a/docs/references/nextjs/overview.mdx b/docs/references/nextjs/overview.mdx index e7819082ff..0cb5731a05 100644 --- a/docs/references/nextjs/overview.mdx +++ b/docs/references/nextjs/overview.mdx @@ -1,44 +1,30 @@ --- -title: Next.js reference overview +title: Clerk Next.js SDK description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your Next.js application. --- -Clerk makes it simple to add authentication to your Next.js application. This documentation covers the capabilities and methods available from Clerk's Next.js SDK. - -## Guides - -- [Read session and user data](/docs/references/nextjs/read-session-data) -- [Add a custom sign-in-or-up page](/docs/references/nextjs/custom-sign-in-or-up-page) -- [Integrate Clerk into your app with tRPC](/docs/references/nextjs/trpc) +Clerk makes it simple to add authentication to your Next.js application. This reference lists the features and methods available in Clerk's Next.js SDK. ## Client-side helpers -Because Clerk Next.js is a wrapper around Clerk React, you can utilize the hooks that Clerk React provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, and a set of useful helper methods for signing in and signing up. You can learn more about these hooks [in the React SDK reference](/docs/references/react/overview). +Because the Next.js SDK is built on top of the Clerk React SDK, you can utilize the hooks that the React SDK provides. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more about these hooks in the [React SDK reference](/docs/references/react/overview). -{/* TODO: We can use a partial here. */} + -- [`useUser()`](/docs/references/react/use-user) -- [`useClerk()`](/docs/references/react/use-clerk) -- [`useAuth()`](/docs/references/react/use-auth) -- [`useSignIn()`](/docs/references/react/use-sign-in) -- [`useSignUp()`](/docs/references/react/use-sign-up) -- [`useSession()`](/docs/references/react/use-session) -- [`useSessionList()`](/docs/references/react/use-session-list) -- [`useOrganization()`](/docs/references/react/use-organization) -- [`useOrganizationList()`](/docs/references/react/use-organization-list) +## Server-side helpers -## App router references +### App router -Clerk provides first-class support for the [Next.js App Router](https://nextjs.org/docs/app). The below methods and references show how to integrate Clerk features into applications that take advantage of the latest App Router and React Server Components features. +Clerk provides first-class support for the [Next.js App Router](https://nextjs.org/docs/app). The following references show how to integrate Clerk features into apps using the latest App Router and React Server Components features. - [`auth()`](/docs/references/nextjs/auth) - [`currentUser()`](/docs/references/nextjs/current-user) - [Route Handlers](/docs/references/nextjs/route-handlers) - [Server Actions](/docs/references/nextjs/server-actions) -## Pages router references +### Pages router -Clerk continues to provide drop-in support for the Next.js Pages Router. In addition to the main Clerk integration, several methods are available for instrumenting authentication within Pages Router-based applications. +Clerk continues to provide drop-in support for the Next.js Pages Router. In addition to the main Clerk integration, the following references are available for apps using Pages Router. - [`getAuth()`](/docs/references/nextjs/get-auth) - [`buildClerkProps()`](/docs/references/nextjs/build-clerk-props) @@ -47,7 +33,7 @@ Clerk continues to provide drop-in support for the Next.js Pages Router. In addi ### `Auth` object -Both `auth()` and `getAuth()` return an `Auth` object. This JavaScript object contains important information like session data, your user's ID, as well as their organization ID. Learn more about the `Auth` object [here](/docs/references/nextjs/auth-object). +Both `auth()` (App Router) and `getAuth()` (Pages Router) return an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}. ### `clerkMiddleware()` diff --git a/docs/references/react-router/custom-signup-signin-pages.mdx b/docs/references/react-router/custom-signup-signin-pages.mdx new file mode 100644 index 0000000000..1bb6e01d6d --- /dev/null +++ b/docs/references/react-router/custom-signup-signin-pages.mdx @@ -0,0 +1,91 @@ +--- +title: Build your own sign-up and sign-in pages for your React Router app with Clerk +description: Learn how to add custom sign-up and sign-in pages to your React Router app with Clerk's prebuilt components. +--- + +This guide shows you how to use the [``](/docs/components/authentication/sign-in) and [``](/docs/components/authentication/sign-up) components with the [React Router Splat route](https://reactrouter.com/start/framework/routing#splats) to build custom sign-up and sign-in pages for your React Router app. See the [quickstart tutorial](/docs/quickstarts/react-router) for a step-by-step guide. + +If the prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow guides](/docs/custom-flows/overview). + + + ### Build a sign-up page + + The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. + + ```tsx {{ filename: 'app/routes/sign-up.tsx' }} + import { SignUp } from '@clerk/react-router' + + export default function SignUpPage() { + return ( +
+

Sign up route

+ +
+ ) + } + ``` + + ### Build a sign-in page + + The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. + + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} + import { SignIn } from '@clerk/react-router' + + export default function SignInPage() { + return ( +
+

Sign in route

+ +
+ ) + } + ``` + + ### Configure routes + + React Router expects you to define routes in [`app/routes.ts`](https://reactrouter.com/start/framework/routing). Add the previously created sign-in and sign-up pages to your route configuration. + + ```tsx {{ filename: 'app/routes.ts', mark: [5, 6] }} + import { type RouteConfig, index, route } from '@react-router/dev/routes' + + export default [ + index('routes/home.tsx'), + route('sign-in/*', 'routes/sign-in.tsx'), + route('sign-up/*', 'routes/sign-up.tsx'), + ] satisfies RouteConfig + ``` + + ### Configure redirect behavior + + Update your environment variables to point to your custom sign-up and sign-in pages. Learn more about the available [environment variables](/docs/deployments/clerk-environment-variables). + + ```env {{ filename: '.env' }} + CLERK_SIGN_IN_FALLBACK_URL=/ + CLERK_SIGN_UP_FALLBACK_URL=/ + CLERK_SIGN_IN_URL=/sign-in + CLERK_SIGN_UP_URL=/sign-up + ``` + + These values control the behavior of the `` and `` components and when you visit the respective links at the bottom of each component. + + ### Visit your new pages + + Run your project with the following command: + + + ```bash {{ filename: 'terminal' }} + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + + Visit your new custom pages locally at [localhost:5173/sign-up](http://localhost:5173/sign-up) and [localhost:5173/sign-in](http://localhost:5173/sign-in). + diff --git a/docs/references/react-router/get-auth.mdx b/docs/references/react-router/get-auth.mdx new file mode 100644 index 0000000000..9715c265c6 --- /dev/null +++ b/docs/references/react-router/get-auth.mdx @@ -0,0 +1,118 @@ +--- +title: '`getAuth()`' +description: The getAuth() helper retrieves authentication state from the request object. +--- + +The `getAuth()` helper retrieves authentication state from the request object. + +## Parameters + + + - `request` + + The request object. + + --- + + - `opts?` + + An optional object that can be used to configure the behavior of the `getAuth()` function. It accepts the following properties: + + - `secretKey?`: A string that represents the secret key used to sign the session token. If not provided, the secret key is retrieved from the environment variable `CLERK_SECRET_KEY`. + + +## Returns + +`getAuth()` returns the [`Auth`](/docs/references/nextjs/auth-object){{ target: '_blank' }} object. + +## Usage + +### Server data loading + +The following example demonstrates how to use `getAuth()` to protect a profile page route and load user data. +If the user is authenticated, their `userId` is passed to the Backend SDK's [`getUser()`](/docs/references/backend/user/get-user){{ target: '_blank' }} method to retrieve the user's information. + +```tsx {{ filename: 'app/routes/profile.tsx' }} +import { redirect } from 'react-router' +import { getAuth } from '@clerk/react-router/ssr.server' +import { createClerkClient } from '@clerk/react-router/api.server' +import type { Route } from './+types/profile' + +export async function loader(args: Route.LoaderArgs) { + const { userId } = await getAuth(args) + + if (!userId) { + return redirect('/sign-in?redirect_url=' + args.request.url) + } + + const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser( + userId, + ) + + return { + user: JSON.stringify(user), + } +} + +export default function Profile({ loaderData }: Route.ComponentProps) { + return ( +
+

Profile Data

+ 
+        {JSON.stringify(loaderData, null, 2)}
+
+
+ ) +} +``` + +### Server action + +Unlike the previous example that loads data when the page loads, the following example uses `getAuth()` to only fetch user data after submitting the form. The helper runs on form submission, authenticates the user, and processes the form data. + +```tsx {{ filename: 'app/routes/profile-form.tsx' }} +import { redirect, Form } from 'react-router' +import { getAuth } from '@clerk/react-router/ssr.server' +import { createClerkClient } from '@clerk/react-router/api.server' +import type { Route } from './+types/profile-form' + +export async function action(args: Route.ActionArgs) { + const { userId } = await getAuth(args) + + if (!userId) { + return redirect('/sign-in?redirect_url=' + args.request.url) + } + + const formData = await args.request.formData() + const name = formData.get('name')?.toString() + + const user = await createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY, + }).users.getUser(userId) + + return { + name, + user: JSON.stringify(user), + } +} + +export default function ProfileForm({ actionData }: Route.ComponentProps) { + return ( +
+

Profile Data

+ +
+ + + +
+ + {actionData ? ( + 
+          {JSON.stringify(actionData, null, 2)}
+
+ ) : null} +
+ ) +} +``` diff --git a/docs/references/react-router/library-mode.mdx b/docs/references/react-router/library-mode.mdx new file mode 100644 index 0000000000..87e57aef0f --- /dev/null +++ b/docs/references/react-router/library-mode.mdx @@ -0,0 +1,128 @@ +--- +title: React Router library mode +description: Learn how to use Clerk with React Router in library mode to add authentication to your application. +--- + +> [!WARNING] +> The React Router SDK is currently in beta. + + + - Install `@clerk/react-router` + - Set your Clerk API keys + - Add `` + - Protect your pages + + +React Router can be used as a framework or as a standalone library. This guide explains how to add React Router authentication to an existing React application using library mode. To use React Router as a framework instead, see the [React Router quickstart](/docs/quickstarts/react-router). + + + ### Install `@clerk/react-router` + + Clerk's [React Router SDK](/docs/references/react-router/overview) provides prebuilt components, hooks, and stores to make it easy to integrate authentication and user management in your React Router app. + + Run the following command to install the SDK: + + + ```bash {{ filename: 'terminal' }} + npm install @clerk/react-router + ``` + + ```bash {{ filename: 'terminal' }} + yarn add @clerk/react-router + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/react-router + ``` + + + ### Set your Clerk API keys + + > [!NOTE] + > You will not need the Clerk Secret Key in React Router's library mode, as it should never be used on the client-side. + + + Add your Clerk Publishable Key to your `.env` file. This key can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. + 1. Add your key to your `.env` file. + + The final result should resemble the following: + + + ```env {{ filename: '.env' }} + VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} + ``` + + ### Add `` to your app + + + + You must pass your Publishable Key as a prop, as shown in the following example: + + ```tsx {{ filename: 'src/main.tsx', mark: [4, 8, [13, 17]] }} + import { StrictMode } from 'react' + import { createRoot } from 'react-dom/client' + import { BrowserRouter, Routes, Route } from 'react-router' + import { ClerkProvider } from '@clerk/react-router' + import './index.css' + import App from './App.tsx' + + const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + createRoot(document.getElementById('root')!).render( + + + + + } /> + + + + , + ) + ``` + + ### Create a header with Clerk components + + You can control which content signed-in and signed-out users can see with the [prebuilt control components](/docs/components/overview#what-are-control-components). The following example creates a header using the following components: + + - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. + - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. + - [``](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options. + - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page or displays the sign-in modal. + + ```tsx {{ filename: 'src/App.tsx' }} + import { SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/react-router' + + export default function App() { + return ( +
+ + + + + + +
+ ) + } + ``` + diff --git a/docs/references/react-router/overview.mdx b/docs/references/react-router/overview.mdx new file mode 100644 index 0000000000..b7669134cf --- /dev/null +++ b/docs/references/react-router/overview.mdx @@ -0,0 +1,33 @@ +--- +title: Clerk React Router SDK +description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your React Router application. +--- + +> [!WARNING] +> The React Router SDK is currently in beta. + +Clerk makes it simple to add authentication to your React Router application. This reference lists the features and methods available in Clerk's React Router SDK. + +## Client-side helpers + +The Clerk React Router SDK is built on top of the Clerk React SDK and provides access to all of Clerk React's hooks. These hooks give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more about these hooks in the [React SDK reference](/docs/references/react/overview). + + + +## Server-side helpers + +The following references show how to integrate Clerk features into applications using React Router server functions and API routes. + +- [`getAuth()`](/docs/references/react-router/get-auth) +- [`rootAuthLoader()`](/docs/references/react-router/root-auth-loader) + +### `Auth` object + +The `getAuth()` method returns an `Auth` object. This JavaScript object contains important information like the current user's session ID, user ID, and organization ID. Learn more about the [`Auth` object](/docs/references/nextjs/auth-object){{ target: '_blank' }}. + +## React Router implementations + +React Router can be integrated with Clerk in two ways: + +- As a framework (recommended): Configure your app using [Clerk's React Router SDK](/docs/quickstarts/react-router) +- As a library: Manually integrate React Router into your React + Vite app using [library mode](/docs/references/react-router/library-mode) diff --git a/docs/references/react-router/read-session-data.mdx b/docs/references/react-router/read-session-data.mdx new file mode 100644 index 0000000000..23398a1e38 --- /dev/null +++ b/docs/references/react-router/read-session-data.mdx @@ -0,0 +1,54 @@ +--- +title: Read session and user data in your React Router app with Clerk +description: Learn how to use Clerk's hooks and helpers to access the active session and user data in your React Router application. +--- + +Clerk provides a set of [hooks and helpers](/docs/references/react-router/overview#client-side-helpers) that you can use to access the active session and user data in your React Router application. Here are examples of how to use these helpers in both the client and server-side to get you started. + +## Server-side + +To access active session and user data on the server-side, use the `getAuth()` helper. See the [reference documentation](/docs/references/react-router/get-auth) for more information, including code examples. + +## Client-side + +To access active session and user data on the client-side, use Clerk's `useAuth()` and `useUser()` hooks. + +### `useAuth()` + +The [`useAuth()`](/docs/references/react/use-auth){{ target: '_blank' }} hook provides information about 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, as shown in the following example: + +```tsx {{ filename: 'app/routes/use-auth.tsx' }} +import { useAuth } from '@clerk/react-router' + +export default function UseAuthPage() { + const { isLoaded, userId } = useAuth() + + // Return null if the user signs out while on the page + // or if the auth state is still loading + if (!isLoaded || !userId) { + return null + } + + return
Hello, {userId}!
+} +``` + +### `useUser()` + +The [`useUser()`](/docs/references/react/use-user){{ target: '_blank' }} hook provides the current user's [`User`](/docs/references/javascript/user/user){{ target: '_blank' }} object, which holds all of the information for a user of your application and provides a set of methods to manage their account. + +```tsx {{ filename: 'app/routes/use-user.tsx' }} +import { useUser } from '@clerk/react-router' + +export default function UseUserPage() { + const { isLoaded, isSignedIn, user } = useUser() + + // Return null if the user signs out while on the page + // or if the auth state is still loading + if (!isLoaded || !isSignedIn) { + return null + } + + return
Hello, {user.firstName}!
+} +``` diff --git a/docs/references/react-router/root-auth-loader.mdx b/docs/references/react-router/root-auth-loader.mdx new file mode 100644 index 0000000000..cf465b889e --- /dev/null +++ b/docs/references/react-router/root-auth-loader.mdx @@ -0,0 +1,159 @@ +--- +title: '`rootAuthLoader()`' +description: The rootAuthLoader() function configures Clerk to handle authentication state for React Router routes. +--- + +The `rootAuthLoader()` function configures Clerk to handle authentication state for React Router routes, allowing easy access to user session information in your app. + +## Configure `rootAuthLoader()` + +In your `root.tsx` file, add `rootAuthLoader` to the `loader` function. If your app doesn't have a loader function yet, you'll need to add it manually. + +```tsx {{ filename: 'app/root.tsx' }} +import { rootAuthLoader } from '@clerk/react-router/ssr.server' +import type { Route } from './+types/root' + +export async function loader(args: Route.LoaderArgs) { + return rootAuthLoader(args) +} +``` + +You can also pass [options](#root-auth-loader-options) to the `rootAuthLoader()` as the second argument. + +```tsx {{ filename: 'app/root.tsx', mark: [5] }} +import { rootAuthLoader } from '@clerk/react-router/ssr.server' +import type { Route } from './+types/root' + +export async function loader(args: Route.LoaderArgs) { + return rootAuthLoader(args, { signInUrl: '/sign-in' }) +} +``` + +### Loading additional data + +If you need to load additional data, you can pass your loader directly to `rootAuthLoader()` as the second argument. The options object is passed as the third argument. + +```tsx {{ filename: 'app/root.tsx', mark: [7, 13] }} +import { rootAuthLoader } from '@clerk/react-router/ssr.server' +import type { Route } from './+types/root' + +export async function loader(args: Route.LoaderArgs) { + return rootAuthLoader( + args, + ({ request, context, params }) => { + // Loader + const { userId } = request.auth + + return { userId } + }, + { signInUrl: '/sign-in' }, // Options + ) +} +``` + +## `rootAuthLoader()` options + + + - `secretKey?` + - `string` + + The Clerk Secret Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + --- + + - `jwtKey?` + - `string` + + 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. For more information, refer to [Manual JWT verification](/docs/backend-requests/handling/manual-jwt). + + --- + + - `publishableKey?` + - `string` + + The Clerk Publishable Key from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + --- + + - `domain?` + - `string` + + The domain of a [satellite application](/docs/advanced-usage/satellite-domains) in a multi-domain setup. + + --- + + - `isSatellite?` + - `boolean` + + Whether the instance is a satellite domain in a multi-domain setup. Defaults to `false`. + + --- + + - `proxyUrl?` + - `string` + + The proxy URL from a multi-domain setup. + + --- + + - `sdkMetadata?` + - `{ name: string, version: string }` + + Metadata about the SDK. + + --- + + - `telemetry?` + - `{ disabled: boolean, debug: boolean }` + + [Telemetry](/docs/telemetry) configuration. + + --- + + - `userAgent?` + - `string` + + The User-Agent request header passed to the Clerk API. + + --- + + - `apiUrl?` + - `string` + + The [Clerk Backend API](/docs/reference/backend-api){{ target: '_blank' }} endpoint. Defaults to `'https://api.clerk.com'`. + + --- + + - `apiVersion?` + - `string` + + The version passed to the Clerk API. Defaults to `'v1'`. + + --- + + - `audience?` + - `string | string[]` + + A string or list of [audiences](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). + + --- + + - `authorizedParties?` + - `string[]` + + An allowlist of origins to verify against, to protect your application from the subdomain cookie leaking attack.
For example: `['http://localhost:3000', 'https://example.com']` + + --- + + - `signInUrl?` + - `string` + + The full URL or path to the sign in page. Use this property to provide the target of the 'Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpUrl?` + - `string` + + The full URL or path to the sign up page. Use this property to provide the target of the 'Sign up' link that's rendered. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + diff --git a/docs/references/react/add-react-router.mdx b/docs/references/react/add-react-router.mdx deleted file mode 100644 index 469ba35c67..0000000000 --- a/docs/references/react/add-react-router.mdx +++ /dev/null @@ -1,334 +0,0 @@ ---- -title: Add React Router to your Clerk-powered React application -description: Learn how to add React Router to your React application using their Data API router. ---- - - - - Install `react-router-dom` - - Create components for your routes - - Create layouts - - Wire layouts and routes up with `createBrowserRouter` - - -> [!WARNING] -> This tutorial is written for [React Router 6](https://reactrouter.com/6.28.0/home) and doesn't support [loaders](https://reactrouter.com/6.28.0/route/loader) and [actions](https://reactrouter.com/6.28.0/route/action). - -Learn how to add React Router to your application using React Router's new Data API router. This tutorial will cover configuring layouts and setting up protected routes. - - - ### Install `react-router-dom` - - React Router's `react-router-dom` is a mature, battle tested routing package for React that gives you many options. As it is the most popular routing option, it will be used for this guide. - - - ```bash {{ filename: 'terminal' }} - npm install react-router-dom - ``` - - ```bash {{ filename: 'terminal' }} - yarn add react-router-dom - ``` - - ```bash {{ filename: 'terminal' }} - pnpm add react-router-dom - ``` - - - ### Create components for your routes - - The exact routes you will need depends on your application. For this guide, you will create `/`, `/contact`, `/dashboard`, `/sign-in`, and `sign-up` routes. The `/dashboard` route will contain a default route (`/dashbard/`) and an invoices route (`/dashboard/invoices`). The first step will be creating basic components for these routes. - - Use the tabs below to find the example components and recreate these files using the path from each tab. - - - ```tsx {{ filename: 'src/routes/index.tsx' }} - import { Link } from 'react-router-dom' - - export default function IndexPage() { - return ( -
-

This is the index page

-
-
    -
  • - Sign Up -
    • -
  • - Sign In -
    • -
  • - Contact -
    • -
  • - Dashboard -
    • -
-
-
- ) - } - ``` - - ```tsx {{ filename: 'src/routes/contact.tsx' }} - import { Link } from 'react-router-dom' - - export default function ContactPage() { - return ( - <> -

Contact

-

- This is a public page meant to contain a contact form and other related contact details. -

-
    -
  • - Return to Index -
    • -
  • - Dashboard -
    • -
- - ) - } - ``` - - ```tsx {{ filename: 'src/routes/sign-in.tsx' }} - import { SignIn } from '@clerk/clerk-react' - - export default function SignInPage() { - return - } - ``` - - ```tsx {{ filename: 'src/routes/sign-up.tsx' }} - import { SignUp } from '@clerk/clerk-react' - - export default function SignUpPage() { - return - } - ``` - - ```tsx {{ filename: 'src/routes/dashboard.tsx' }} - import { Link } from 'react-router-dom' - - export default function DashboardPage() { - return ( - <> -

Dashboard page

-

This is a protected page.

- -
    -
  • - Invoices -
    • -
  • - Return to index -
    • -
- - ) - } - ``` - - ```tsx {{ filename: 'src/routes/dashboard.invoices.tsx' }} - import { Link } from 'react-router-dom' - - export default function InvoicesPage() { - return ( - <> -

Invoices page

-

This is a protected page.

- -
    -
  • - Dashboard -
    • -
  • - Return to index -
    • -
- - ) - } - ``` - - - ### Create layouts - - You're going to create two layouts for your application. One will mount [``](/docs/components/clerk-provider) and act as a top level layout. It will also be a place for a header, footer, and other standard elements for your application. - - The second layout will be non-rendering and will protect everything in the `/dashboard` route. This avoids the need for per-page auth checks or for using Clerk's control components. - - - ```tsx {{ filename: 'src/layouts/root-layout.tsx' }} - import { Link, Outlet, useNavigate } from 'react-router-dom' - import { ClerkProvider, SignedIn, SignedOut, UserButton } from '@clerk/clerk-react' - - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Missing Publishable Key') - } - - export default function RootLayout() { - const navigate = useNavigate() - - return ( - navigate(to)} - routerReplace={(to) => navigate(to, { replace: true })} - publishableKey={PUBLISHABLE_KEY} - > -
-
-
-

Clerk + React + React Router App

-
- - - - - Sign In - -
-
-
- -
- - ) - } - ``` - - ```tsx {{ filename: 'src/layouts/dashboard-layout.tsx' }} - import * as React from 'react' - import { useAuth } from '@clerk/clerk-react' - import { Outlet, useNavigate } from 'react-router-dom' - - export default function DashboardLayout() { - const { userId, isLoaded } = useAuth() - const navigate = useNavigate() - - console.log('test', userId) - - React.useEffect(() => { - if (isLoaded && !userId) { - navigate('/sign-in') - } - }, [isLoaded]) - - if (!isLoaded) return 'Loading...' - - return - } - ``` - - - #### Key Takeaways - - - The new root-layout.tsx has a simple header that includes the `` and a link to the `/sign-in` page instead of a ``. The rendering of these is controlled by the `` and `` control components. This is very similar to the [Embed the `` and ``](/docs/quickstarts/react#embed-the-user-button-and-sign-in-button) step from the [React Quickstart](/docs/quickstarts/react). - - Both the layouts contain an `` component from `react-router-dom`. This behaves similar to `{children}` in Next.js or more generic React components. You will take advantage of this component in the next step. - - ### Wire layouts and routes up with `createBrowserRouter` - - With all the routes and layouts you need created, you now need to wire up the layouts and the routes with the `createBrowserRouter` function from `react-router-dom`. This will use the Data API (aka Data Router) to configure your application. - - You can start by removing `src/App.tsx`—the contents of that file were moved to `src/layouts/root-layout.tsx`. - - In `src/main.tsx`, import `RouterProvider` and `createBrowserRouter()` from `react-router-dom`, as well as all of the default components from the layouts and routes you created. Replace the contents inside of `` with only ` `. Lastly, you will build the `router` using `createBrowserRouter()`. - - ```tsx {{ filename: 'src/main.tsx' }} - import React from 'react' - import ReactDOM from 'react-dom/client' - import './index.css' - import { RouterProvider, createBrowserRouter } from 'react-router-dom' - - // Import the layouts - import RootLayout from './layouts/root-layout' - import DashboardLayout from './layouts/dashboard-layout' - - // Import the components - import IndexPage from './routes' - import ContactPage from './routes/contact' - import SignInPage from './routes/sign-in' - import SignUpPage from './routes/sign-up' - import DashboardPage from './routes/dashboard' - import InvoicesPage from './routes/dashboard.invoices' - - const router = createBrowserRouter([ - { - element: , - children: [ - { path: '/', element: }, - { path: '/contact', element: }, - { path: '/sign-in/*', element: }, - { path: '/sign-up/*', element: }, - { - element: , - path: 'dashboard', - children: [ - { path: '/dashboard', element: }, - { path: '/dashboard/invoices', element: }, - ], - }, - ], - }, - ]) - - ReactDOM.createRoot(document.getElementById('root')!).render( - - - , - ) - ``` - - Visit [`http://localhost:5173`](http://localhost:5173) and explore your app's pages. - - #### Key Takeaways - - - The top most object in the `router` is the `` component, and everything else is a child. Any child route will be mounted where the `` component is inside the root layout. This wraps the entire application with `` and allows you to add a header, footer, sidebars and other pieces that will be available to the entire application. - - Several routes are direct children of the root layout. These are all public routes. You can use control components like `` or check the `userId` from `useAuth()` if you want to make content protected. - - The `` is child of the root layout, renders nothing, and has a check to see if the `userId` exists. This will confirm that a user is signed in. If the `userId` is not truthy, then the user will be redirected to the `/sign-in` route to sign-in. That protects all pages in the `/dashboard` route. All children of `/dashboard` will be mounted inside of the `` component in the dashboard layout. - - -Your application is setup with `react-router-dom` and ready for you to add more layouts and routes as needed! If you want to get started using a template from this guide, clone the following repository and then checkout the `integrate-react-router-dom-using-data-router-method` branch. - -- [Clerk + React Quickstart](https://github.com/clerk/clerk-react-quickstart) - -### Next steps - - - - [Customization & Localization](/docs/customization/overview) - - Learn how to customize and localize the Clerk components. - - --- - - - [Authentication Components](/docs/components/authentication/sign-in) - - Learn more about all our authentication components. - - --- - - - [Client Side Helpers](/docs/references/react/use-user) - - Learn more about our client-side helpers and how to use them. - diff --git a/docs/references/react/overview.mdx b/docs/references/react/overview.mdx index 50b72d2f59..0545b4f8a1 100644 --- a/docs/references/react/overview.mdx +++ b/docs/references/react/overview.mdx @@ -1,19 +1,47 @@ --- title: Clerk React SDK -description: Learn how to integrate React into your Clerk application. +description: Learn how to integrate Clerk into your React application using the Clerk React SDK. --- -The Clerk React SDK is a wrapper around the Clerk JavaScript SDK. It is the recommended way to integrate Clerk into your React application. +The React SDK is built on top of the JavaScript SDK, and is the recommended method for integrating Clerk into your React application. -> [!WARNING] -> If you are using Next.js, install the `@clerk/nextjs` package, as `@clerk/clerk-react` is incompatible. See the [Next.js](/docs/references/nextjs/overview) documentation for more information. +## Key features -Clerk React provides React.js implementations of [Clerk components](/docs/components/overview); highly customizable, prebuilt components that you can use to build beautiful user management applications. You can find display components for building [sign-in](/docs/components/authentication/sign-in), [sign-up](/docs/components/authentication/sign-up), [account switching](/docs/components/user/user-button), and [user profile management](/docs/components/user/user-profile) pages as well as flow [control components](/docs/components/control/signed-in) that act as helpers for implementing a seamless authentication experience. +### Pre-built components -Clerk React provides a suite of [custom hooks](/docs/references/react/use-user). These hooks give you access to the [`Clerk` object](/docs/references/javascript/clerk/clerk), and a set of useful helper methods for signing in and signing up. +The React SDK provides access to [Clerk components](/docs/components/overview) for user and organization management, including: -## Setting up Clerk React +- [Sign-in](/docs/components/authentication/sign-in) +- [Sign-up](/docs/components/authentication/sign-up) +- [Account switching](/docs/components/user/user-button) +- [User profile management](/docs/components/user/user-profile) +- [Organization switching](/docs/components/organization/organization-switcher) +- [Organization management](/docs/components/organization/organization-profile) +- [Control components](/docs/components/control/signed-in) -You need to create a Clerk application in the Clerk Dashboard before you can set up Clerk React. For more information, see the [setup guide](/docs/quickstarts/setup-clerk). +### Custom hooks -Once a Clerk application has been created, you can install and start using Clerk React in your application. [The quickstart guide](/docs/quickstarts/react) will have all the information you need to get started. +The React SDK provides access to custom hooks that provide direct access to the [`Clerk` object](/docs/references/javascript/clerk/clerk), a user's [`User` object](/docs/references/javascript/user/user), and helper methods for authentication flows. + + + +## Framework-specific SDKs + +> [!IMPORTANT] +> Clerk provides optimized SDKs for specific React frameworks. If you're using one of the supported frameworks below, you should use its dedicated SDK instead of `@clerk/clerk-react`. +> +> For example, Next.js applications **must** use `@clerk/nextjs` as `@clerk/clerk-react` is not compatible. + +Clerk offers framework-specific SDKs that are customized to provide the better developer experience and integration with each framework's features. Choose the appropriate SDK based on your framework: + +| Framework | Package | Docs | +| - | - | - | +| Next.js | `@clerk/nextjs` | [Next.js SDK](/docs/references/nextjs/overview) | +| React Router | `@clerk/clerk-react-router` | [React Router SDK](/docs/references/react-router/overview) | +| Remix | `@clerk/remix` | [Remix SDK](/docs/references/remix/clerk-app) | +| Astro | `@clerk/astro` | [Astro SDK](/docs/references/astro/overview) | +| Tanstack Start | `@clerk/tanstack-start` | [Tanstack Start SDK](/docs/references/tanstack-start/overview) | + +## Set up Clerk React + +Before you can add Clerk to your React application, you must create a Clerk app in the Clerk Dashboard. To get started, follow the [setup guide](/docs/quickstarts/setup-clerk). Then, follow the [quickstart guide](/docs/quickstarts/react) to set up the React SDK in your app. diff --git a/docs/references/react/use-sign-in.mdx b/docs/references/react/use-sign-in.mdx index c178a6a80d..aa194cb672 100644 --- a/docs/references/react/use-sign-in.mdx +++ b/docs/references/react/use-sign-in.mdx @@ -77,7 +77,7 @@ The `status` property of the `SignIn` object can be one of the following values: | Values | Descriptiom | | - | - | | `complete` | The user has been signed in and custom flow can proceed to `setActive()` to create session. | -| `needs_first_factor` | The First Factor verification is missing. One of `email_link`, `email_code`, `phone_code`, `web3_metamask_signature`, `web3_coinbase_wallet_signature` or `oauth_provider` is required to verify user. See [First Factor](/docs/references/javascript/sign-in/first-factor) for details. | +| `needs_first_factor` | The first factor verification is missing. One of `email_link`, `email_code`, `phone_code`, `web3_metamask_signature`, `web3_coinbase_wallet_signature`, `web3_okx_wallet_signature` or `oauth_provider` is required to verify the user. See [the reference](/docs/references/javascript/sign-in/first-factor) for more information. | | `needs_second_factor` | The Second Factor verification is missing. The Second Factor is an optional step to provide additional verification and includes `phone_code` and `totp`. See [Second Factor](/docs/references/javascript/sign-in/second-factor) for details. | | `needs_identifier` | The user's identifier (email address, phone number, username, etc.) hasn't been provided. | | `needs_new_password` | The user needs to set a new password. | diff --git a/docs/references/redwood/overview.mdx b/docs/references/redwood/overview.mdx index 938bd3f4b0..02fcd94e68 100644 --- a/docs/references/redwood/overview.mdx +++ b/docs/references/redwood/overview.mdx @@ -1,5 +1,5 @@ --- -title: Use Clerk with RedwoodJS +title: Clerk RedwoodJS SDK description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your RedwoodJS application. --- diff --git a/docs/references/remix/clerk-app.mdx b/docs/references/remix/clerk-app.mdx index d165a65a56..c1070fc202 100644 --- a/docs/references/remix/clerk-app.mdx +++ b/docs/references/remix/clerk-app.mdx @@ -80,7 +80,14 @@ export default ClerkApp(App) - `allowedRedirectOrigins?` - `Array` - Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. + 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` + + 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. [components-ref]: /docs/components/overview diff --git a/docs/references/remix/custom-signup-signin-pages.mdx b/docs/references/remix/custom-signup-signin-pages.mdx index 3157c9702e..f0a2cb40dd 100644 --- a/docs/references/remix/custom-signup-signin-pages.mdx +++ b/docs/references/remix/custom-signup-signin-pages.mdx @@ -13,7 +13,7 @@ The functionality of the components are controlled by the instance settings you > Just getting started with Clerk and Remix? See the [quickstart tutorial](/docs/quickstarts/remix)! - ## Build your sign-up page + ### Build your sign-up page The following example demonstrates how to render the [``](/docs/components/authentication/sign-up) component. @@ -30,7 +30,7 @@ The functionality of the components are controlled by the instance settings you } ``` - ## Build your sign-in page + ### Build your sign-in page The following example demonstrates how to render the [``](/docs/components/authentication/sign-in) component. @@ -47,7 +47,7 @@ The functionality of the components are controlled by the instance settings you } ``` - ## Configure your sign-up and sign-in pages + ### Configure your sign-up and sign-in pages @@ -78,7 +78,7 @@ The functionality of the components are controlled by the instance settings you These values control the behavior of the components when you sign in or sign up and when you click on the respective links at the bottom of each component. - ## Visit your new pages + ### Visit your new pages Run your project with the following terminal command from the root directory of your project: diff --git a/docs/references/tanstack-start/overview.mdx b/docs/references/tanstack-start/overview.mdx index 59c1d555ca..68a1d12288 100644 --- a/docs/references/tanstack-start/overview.mdx +++ b/docs/references/tanstack-start/overview.mdx @@ -1,5 +1,5 @@ --- -title: "TanStack Start and Clerk" +title: Clerk TanStack Start SDK description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your TanStack Start application. --- diff --git a/docs/telemetry.mdx b/docs/telemetry.mdx index 770a82178b..9e5dfc27ab 100644 --- a/docs/telemetry.mdx +++ b/docs/telemetry.mdx @@ -72,7 +72,7 @@ CLERK_TELEMETRY_DISABLED=1 ### `telemetry` prop -If you are using `@clerk/clerk-react` directly, or using an SDK that doesn't have environment variable support, you can opt out by passing the `telemetry` prop to ``: +If you are using `@clerk/clerk-react` directly, or using an SDK that doesn't have environment variable support, you can opt out by passing the `telemetry` prop to ``: ```tsx @@ -80,7 +80,9 @@ If you are using `@clerk/clerk-react` directly, or using an SDK that doesn't hav ### Framework specific instructions - + ```env {{ filename: '.env.local' }} NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED=1 ``` @@ -109,4 +111,12 @@ If you are using `@clerk/clerk-react` directly, or using an SDK that doesn't hav ```env {{ filename: '.env.local' }} PUBLIC_CLERK_TELEMETRY_DISABLED=1 ``` + + ```env {{ filename: '.env' }} + VITE_CLERK_TELEMETRY_DISABLED=1 + ``` + + ```env {{ filename: '.env' }} + VITE_CLERK_TELEMETRY_DISABLED=1 + ``` diff --git a/docs/testing/overview.mdx b/docs/testing/overview.mdx index e42790ca92..03e99e2955 100644 --- a/docs/testing/overview.mdx +++ b/docs/testing/overview.mdx @@ -21,7 +21,7 @@ Obtained via the [Backend API](/docs/reference/backend-api/tag/Testing-Tokens){{ Once retrieved, include the token value in the `__clerk_testing_token` query parameter in your Frontend API requests. For example, a sign-up request using a Testing Token would look like this: ```shell -POST https://happy-hippo-1.clerk.accounts.dev/v1/sign_ups?__clerk_testing_token=1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy +POST https://happy-hippo-1.clerk.accounts.dev/v1/client/sign_ups?__clerk_testing_token=1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy ``` For more information, feedback or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package. diff --git a/docs/testing/playwright/overview.mdx b/docs/testing/playwright/overview.mdx index 045c7a409f..db52bdaf37 100644 --- a/docs/testing/playwright/overview.mdx +++ b/docs/testing/playwright/overview.mdx @@ -49,6 +49,9 @@ description: Use Playwright to write end-to-end tests with Clerk. import { clerkSetup } from '@clerk/testing/playwright' import { test as setup } from '@playwright/test' + // Setup must be run serially, this is necessary if Playwright is configured to run fully parallel: https://playwright.dev/docs/test-parallel + setup.describe.configure({ mode: 'serial' }) + setup('global setup', async ({}) => { await clerkSetup() }) diff --git a/docs/troubleshooting/create-a-minimal-reproduction.mdx b/docs/troubleshooting/create-a-minimal-reproduction.mdx index e6865777ae..7018ee20f3 100644 --- a/docs/troubleshooting/create-a-minimal-reproduction.mdx +++ b/docs/troubleshooting/create-a-minimal-reproduction.mdx @@ -19,9 +19,11 @@ The best way to create a minimal reproduction is to start fresh, with a minimal - [Vanilla JS](https://github.com/clerkinc/clerk-js-starter) - [Expo](https://github.com/clerkinc/clerk-expo-starter) - [Remix](https://github.com/clerk/clerk-remix-v2) +- [React Router](https://github.com/clerk/clerk-react-router-quickstart) - [Redwood](https://github.com/clerkinc/clerk-redwood-starter) - [Rails](https://github.com/clerkinc/clerk-rails-starter) - [Chrome Extension](https://github.com/clerkinc/clerk-chrome-extension-starter) +- [Tanstack Start](https://github.com/clerk/clerk-tanstack-start-quickstart) ## Steps to create a minimal reproduction diff --git a/docs/users/web3.mdx b/docs/users/web3.mdx index cb5f89563b..a823fee5ae 100644 --- a/docs/users/web3.mdx +++ b/docs/users/web3.mdx @@ -7,9 +7,9 @@ Learn how to use Clerk to quickly and easily add secure authentication and user ## Before you start -You need to create a Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/) and configure the application to use **Sign in with Metamask** or **Sign in with Coinbase Wallet**. For more information on how to set up a Clerk application, see the [setup guide](/docs/quickstarts/setup-clerk). To enable Metamask or Coinbase Wallet authentication, see the [dedicated guide](/docs/authentication/configuration/sign-up-sign-in-options#web3-authentication). +You need to create a Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/) and configure the application to use **Sign in with Metamask**, **Sign in with Coinbase Wallet** or **Sign in with OKX Wallet**. For more information on how to set up a Clerk application, see the [setup guide](/docs/quickstarts/setup-clerk). To enable Metamask, Coinbase Wallet, or OKX Wallet authentication, see the [dedicated guide](/docs/authentication/configuration/sign-up-sign-in-options#web3-authentication). -Ensure that you have downloaded the [Metamask](https://metamask.io/download/) or [Coinbase Wallet](https://www.coinbase.com/wallet/downloads) plugins and installed it on your browser to ensure a seamless sign-in flow. +Ensure that you've installed the [Metamask](https://metamask.io/download/), [Coinbase Wallet](https://www.coinbase.com/wallet/downloads), or [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet) plugins for a seamless sign-in experience. ## Creating a new Next.js app @@ -17,9 +17,9 @@ Once you have a Clerk application set up in the dashboard, it's time to create a ## Accessing the Web3 address from the frontend -At this point, you should have a Next.js application integrated with Clerk and with Metamask or Coinbase Wallet authentication enabled. Run `npm run dev` and visit `localhost:3000`. If you followed the guide, all of the pages to your application should be protected, and you should see your sign-in page. +At this point, your Next.js application should be integrated with Clerk and configured for authentication using Metamask, Coinbase Wallet, or OKX Wallet. Run `npm run dev` and visit `localhost:3000`. If you followed the guide, all pages in your application will be protected, and you should see your sign-in page. -After signing in with Metamask or Coinbase Wallet, you'll be presented with the Next.js default start screen. Let's modify the start screen to display a user's primary Web3 address on the page. +After signing in with your Web3 provider, you'll be presented with the Next.js default start screen. Let's modify the start screen to display a user's primary Web3 address on the page. In this example, the [`User`](/docs/references/javascript/user/user) object for the current user can be accessed through the [`useUser()`](/docs/references/react/use-user) hook. The user's primary Web3 address can then be retrieved from the `User` object. diff --git a/styleguides/STYLEGUIDE.md b/styleguides/STYLEGUIDE.md index 4a6de61262..83c03cdbba 100644 --- a/styleguides/STYLEGUIDE.md +++ b/styleguides/STYLEGUIDE.md @@ -397,7 +397,7 @@ Component references should be wrapped in `< />` if they are self closing. Other The last case is incorrect because the `` component will never wrap children, and therefore, should have a self-closing tag. -> Use the `` component. +> Use the `` component. The last case is incorrect because the `` component will always wrap children and will never be self-closing.