From bd1a2b57db73a923b1c4519a7b9c128430088d69 Mon Sep 17 00:00:00 2001 From: Lennart Date: Thu, 12 Dec 2024 16:24:47 +0100 Subject: [PATCH] feat: Add React Router docs (#1760) Co-authored-by: Brad Cornes Co-authored-by: victoria Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/_partials/react-hooks.mdx | 9 + docs/index.mdx | 6 + docs/manifest.json | 66 +++- docs/manifest.schema.json | 1 + docs/quickstarts/react-router.mdx | 220 ++++++++++++ docs/quickstarts/react.mdx | 7 +- docs/references/nextjs/auth-object.mdx | 4 +- docs/references/nextjs/overview.mdx | 32 +- .../custom-signup-signin-pages.mdx | 91 +++++ docs/references/react-router/get-auth.mdx | 118 +++++++ docs/references/react-router/library-mode.mdx | 128 +++++++ docs/references/react-router/overview.mdx | 33 ++ .../react-router/read-session-data.mdx | 54 +++ .../react-router/root-auth-loader.mdx | 159 +++++++++ docs/references/react/add-react-router.mdx | 334 ------------------ docs/references/react/overview.mdx | 46 ++- .../remix/custom-signup-signin-pages.mdx | 8 +- docs/telemetry.mdx | 12 +- .../create-a-minimal-reproduction.mdx | 2 + 19 files changed, 944 insertions(+), 386 deletions(-) create mode 100644 docs/_partials/react-hooks.mdx create mode 100644 docs/quickstarts/react-router.mdx create mode 100644 docs/references/react-router/custom-signup-signin-pages.mdx create mode 100644 docs/references/react-router/get-auth.mdx create mode 100644 docs/references/react-router/library-mode.mdx create mode 100644 docs/references/react-router/overview.mdx create mode 100644 docs/references/react-router/read-session-data.mdx create mode 100644 docs/references/react-router/root-auth-loader.mdx delete mode 100644 docs/references/react/add-react-router.mdx 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/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,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) + + --- + + - [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 351643127d..4b6bc45721 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", @@ -1872,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": [ @@ -2404,6 +2399,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..d2e07cba0d 100644 --- a/docs/manifest.schema.json +++ b/docs/manifest.schema.json @@ -125,6 +125,7 @@ "react", "redwood", "remix", + "react-router", "rocket", "route", "ruby", 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..21ba2e4f7f 100644 --- a/docs/quickstarts/react.mdx +++ b/docs/quickstarts/react.mdx @@ -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/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 0dd5f02bd3..0cb5731a05 100644 --- a/docs/references/nextjs/overview.mdx +++ b/docs/references/nextjs/overview.mdx @@ -3,42 +3,28 @@ 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 custom sign up and sign in pages](/docs/references/nextjs/custom-signup-signin-pages) -- [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 ed6e50fc46..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 (`/dashboard/`) 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/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/telemetry.mdx b/docs/telemetry.mdx index 770a82178b..e34347da2b 100644 --- a/docs/telemetry.mdx +++ b/docs/telemetry.mdx @@ -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/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