feat: adds telemetry page

docs/components/clerk-provider.mdx

@@ -108,6 +108,8 @@ The `<ClerkProvider>` component must be added to your React entrypoint.
 | `isSatellite?`            | `boolean \| ((url: URL) => boolean)`                                                  | This option defines that the application is a satellite application.                                                                                                                                                       |
 | `domain?`                 | `string \| ((url: URL) => boolean)`                                                   | This option sets the domain of the satellite application. If your application is a satellite application, this option is required.                                                                                         |
 | `signInUrl`               | `string`                                                                              | This url will be used for any redirects that might happen and needs to point to your primary application. This option is optional for production instances and required for development instances.                         |
+| `telemetry?`               | `false \| { disabled?: boolean; debug?: boolean } \| undefined`                       | Controls whether or not Clerk will collect [telemetry data](/docs/telemetry).                                                                                                                                              |
+
 
 [components-ref]: /docs/components/overview
 [ap-ref]: /docs/account-portal/overview

docs/manifest.json

@@ -391,7 +391,7 @@
   ],
   [
     {
-      "title": "Security",
+      "title": "Security & Privacy",
       "icon": "lock-closed",
       "root": "security"
     },
@@ -405,6 +405,7 @@
       ["CSRF protection", "/security/csrf-protection"],
       ["Fixation protection", "/security/fixation-protection"],
       ["Password protection and rules", "/security/password-protection"],
+      ["Clerk Telemetry", "/telemetry"],
       "# Protect accounts from attacks",
       ["Brute force attacks and locking user accounts","/security/user-lock-guide"],
       ["Customize max login attempts and duration of of user lockout", "/security/customize-user-lockout"],

docs/references/javascript/clerk/clerk.mdx

@@ -99,6 +99,8 @@ All props below are optional.
 | `allowedRedirectOrigins` | `Array<string \| RegExp> \| undefined` | Optional array of domains used to validate against the query param of an auth redirect.<br />If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. |
 | `isInterstitial` | `boolean \| undefined` | Indicates that Clerk.js will be loaded from interstitial. Defaults to `false` |
 | `isSatellite` | `boolean \| ((url: URL) => boolean) \| undefined` | Clerk Flag for satellite apps. Experimental. |
+| `telemetry?` | `false \| { disabled?: boolean; debug?: boolean } \| undefined` | Controls whether or not Clerk will collect [telemetry data](/docs/telemetry). |
+
 
 ### `signOut()`
 
@@ -230,4 +232,4 @@ In addition to the methods listed above, the `Clerk` class also has the followin
 [user-ref]: /docs/references/javascript/user/user
 [organization-ref]: /docs/references/javascript/organization/organization
 [components-ref]: /docs/components/overview
-[ap-ref]: /docs/account-portal/overview
+[ap-ref]: /docs/account-portal/overview

docs/references/nextjs/current-user.mdx

@@ -1,11 +1,11 @@
 ---
 title: currentUser()
-description: Access the User object inside of your Server Components, Route Handlers, and Server Actions.
+description: Use the currentUser() helper to access information about your user inside of your Server Components, Route Handlers, and Server Actions.
 ---
 
 # `currentUser()`
 
-The `currentUser` helper returns the [`User`][user-object] object of the currently active user. This is the same [`User`][user-object] object that is returned by the [`useUser`](/docs/references/react/use-user) hook. However, it can be used in Server Components, Route Handlers, and Server Actions. Under the hood, this helper calls `fetch()` so it is automatically deduped per request.
+The `currentUser` helper returns the [`Backend API User`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) object of the currently active user. It can be used in Server Components, Route Handlers, and Server Actions. Under the hood, this helper calls `fetch()` so it is automatically deduped per request.
 
 ```tsx filename="app/page.[jsx/tsx]"
 import { currentUser } from '@clerk/nextjs';
@@ -17,6 +17,4 @@ export default async function Page() {
 
   return <div>Hello {user?.firstName}</div>;
 }
-```
-
-[user-object]: /docs/references/javascript/user/user
+```

docs/references/nextjs/read-session-data.mdx

@@ -15,7 +15,7 @@ Clerk provides a set of [hooks and helpers](/docs/references/nextjs/overview#cli
 
 The `auth()` helper will return the [`Authentication`](/docs/references/nextjs/authentication-object) object of the currently active user. Now that request data is available in the global scope through Next.js's `headers()` and `cookies()` methods, passing the request object to Clerk is no longer required.
 
-The `currentUser()` helper will return the [`User`](/docs/references/javascript/user/user) object of the currently active user. This is helpful if you want to render information, like their first and last name, directly from the server.
+The `currentUser()` helper will return the [`Backend API User`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) object of the currently active user. This is helpful if you want to render information, like their first and last name, directly from the server.
 
  Under the hood, `currentUser()` uses the [`clerkClient`](/docs/references/backend/overview) wrapper to make a call to Clerk's Backend API. This does count towards the [Backend API Request Rate Limit](/docs/backend-requests/resources/rate-limits#rate-limits). This also uses `fetch()` so it is automatically deduped per request.
 
@@ -25,7 +25,7 @@ The `currentUser()` helper will return the [`User`](/docs/references/javascript/
 
 <Tabs items={["Server components and actions", "Route Handler", "Route Handler w/ User Fetch"]}>
   <Tab>
-    This example uses the new `auth()` helper to validate an authenticated user and the new `currentUser()` helper to access the `User` object for the authenticated user.
+    This example uses the new `auth()` helper to validate an authenticated user and the new `currentUser()` helper to access the `Backend API User` object for the authenticated user.
 
     ```tsx filename="app/page.tsx"
     import { auth, currentUser } from "@clerk/nextjs";
@@ -39,7 +39,7 @@ The `currentUser()` helper will return the [`User`](/docs/references/javascript/
         // Query DB for user specific information or display assets only to logged in users 
       }
 
-      // Get the User object when you need access to the user's information
+      // Get the Backend API User object when you need access to the user's information
       const user = await currentUser()
       // Use `user` to render user details or create UI elements
     }
@@ -70,7 +70,7 @@ The `currentUser()` helper will return the [`User`](/docs/references/javascript/
   <Tab>
     A Route Handler added to [`publicRoutes`](/docs/references/nextjs/auth-middleware#making-pages-public-using-public-routes) can still use the [`auth()`](/docs/references/nextjs/auth) helper to return information about the user or their authentication state, or to control access to some or all of the Route Handler. The `auth()` helper does require [Middleware](/docs/references/nextjs/auth-middleware). 
 
-    In this example, the `auth()` helper is used to validate an authenticated user and the `currentUser()` helper is used to access the `User` object for the authenticated user.
+    In this example, the `auth()` helper is used to validate an authenticated user and the `currentUser()` helper is used to access the `Backend API User` object for the authenticated user.
 
    ```tsx filename="app/api/user/route.ts"
     import { NextResponse } from 'next/server';
@@ -85,6 +85,7 @@ The `currentUser()` helper will return the [`User`](/docs/references/javascript/
         return new NextResponse("Unauthorized", { status: 401 });
       }
 
+      // Get the Backend API User object when you need access to the user's information
       const user = await currentUser();
 
       // Perform your Route Handler's logic with the returned user object

docs/references/nextjs/route-handlers.mdx

@@ -35,20 +35,24 @@ Clerk provides integrations with a number of popular databases. Below is an exam
 import { NextResponse } from 'next/server';
 import { auth } from '@clerk/nextjs';
 export async function GET() {
-  const {userId, getToken} = auth();
+  const { userId, getToken } = auth();
+
   if(!userId){
     return new Response("Unauthorized", { status: 401 });
   }
-  const token = await getToken({template: "supabase"});
+
+  const token = await getToken({ template: "supabase" });
+
   // Fetch data from Supabase and return it.
   const data = { supabaseData: 'Hello World' };
+
   return NextResponse.json({ data });
 }
 ```
 
 ## Retrieve the current user
 
-In some cases, you might need the current user in your Route Handler. Clerk provides an asynchronous helper called `currentUser` to retrieve it.
+In some cases, you might need the current user in your Route Handler. Clerk provides an asynchronous helper called [`currentUser`](/docs/references/nextjs/current-user) to retrieve it.
 
 ```ts filename="app/api/route.ts"
 import { NextResponse } from 'next/server';

docs/references/nextjs/server-actions.mdx

@@ -7,7 +7,7 @@ description: Learn how to use Clerk with Server Actions.
 
 Clerk provides helpers to allow you to protect your Server Actions, fetch the current user, and interact with the Clerk API.
 
-Below are some examples of usage both in server components or client components.
+Below are some examples of usage both in Server Components or Client Components.
 
 ## With server components
 
@@ -41,7 +41,7 @@ export default function AddToCart() {
 
 ### Accessing the current user
 
-Current user data is important for data enrichment. You can use the `currentUser()` helper to achieve this.
+Current user data is important for data enrichment. You can use the [`currentUser()`](/docs/references/nextjs/current-user) helper to achieve this.
 
 ```tsx filename="app/page.[jsx/tsx]"
 import { currentUser } from '@clerk/nextjs';
@@ -50,14 +50,17 @@ export default function AddHobby() {
   async function addHobby(formData: FormData) {
     'use server';
     const user = await currentUser();
+
     if (!user) {
       throw new Error('You must be signed in to use this feature');
     }
+
     const serverData = {
       usersHobby: formData.get("hobby"),
       userId: user.id,
       profileImage: user.profileImageUrl
     };
+
     console.log('add item server action completed with user details ', serverData);
   }
 
@@ -74,9 +77,9 @@ export default function AddHobby() {
 }
 ```
 
-## With client components
+## With Client Components
 
-When using client components, you need to make sure you use prop drilling to ensure that headers are available.
+When using Client Components, you need to make sure you use prop drilling to ensure that headers are available.
 
 ### Protect your actions
 
@@ -88,9 +91,11 @@ import { auth } from '@clerk/nextjs';
 
 export async function addItem(formData: FormData) {
   const { userId } = auth();
+
   if (!userId) {
     throw new Error('You must be signed in to add an item to your cart');
   }
+
   console.log('add item server action', formData);
 }
 ```
@@ -107,7 +112,7 @@ export default function Hobby() {
 }
 ```
 
-#### Client component
+#### Client Component
 
 ```tsx filename="ui.[jsx/tsx]"
 "use client"
@@ -136,14 +141,17 @@ import { currentUser } from "@clerk/nextjs";
 
 export async function addHobby(formData: FormData) {
   const user = await currentUser();
+
   if (!user) {
     throw new Error('You must be signed in to use this feature');
   }
+
   const serverData = {
     usersHobby: formData.get("hobby"),
     userId: user.id,
     profileImage: user.profileImageUrl
   };
+
   console.log('add Hobby completed with user details ', serverData);
 }
 ```

docs/telemetry.mdx

@@ -0,0 +1,116 @@
+---
+title: Clerk Telemetry
+description: Clerk collects telemetry data from its SDKs about general product and feature usage.
+---
+
+# Clerk Telemetry
+
+Clerk collects telemetry data from its SDKs about general product and feature usage. Participation in telemetry collection is optional and users of the product can opt-out at any time.
+
+## Why is Clerk collecting telemetry data?
+
+While we actively engage with our users and community to gather feedback and inform our product roadmap, the information collected from these efforts only represents a small subset of our users.
+
+Collecting telemetry data gives us a clearer picture into how our SDKs, components, and authentication helpers are used for a diverse set of problems. This data provides valuable insights to help us prioritize features that are useful and impactful for as many of our users as possible.
+
+## What data is being collected?
+
+We track general usage information about our SDKs, components, and authentication helpers from **development instances only**. While we collect identifiers that allows us to associate events with specific Clerk instances, **we do not collect any information from your users**.
+
+Examples of data we are interested in:
+
+- How often are our different components (`<SignIn />`, `<SignUp />`, `<UserProfile />`) rendered?
+- What props are being used?
+- How are developers utilizing the `appearance` prop on our components?
+- What versions of our SDKs are being used?
+- What associated framework versions are being used? (e.g. what `next` version is being used along with `@clerk/nextjs`)
+- Usage of new features
+
+<Callout type="info">
+  We regularly audit this list to ensure it is an accurate representation of the data we are collecting. To audit telemetry data sent from our SDKs yourself, you can set a `CLERK_TELEMETRY_DEBUG=1` environment variable in your application. In this mode, telemetry events are only logged to the console and not sent to Clerk.
+</Callout>
+
+An example event looks like this:
+
+```js
+{
+  event: 'COMPONENT_MOUNTED',
+  cv: '4.62.1',
+  sdk: '@clerk/nextjs',
+  sdkv: '4.25.6',
+  pk: 'pk_test_YmFsYW5jZWQtY293YmlyZC0xNi5jbGVyay5hY2NvdW50cy5kDXyk',
+  payload: { component: 'SignIn', appearanceProp: false },
+}
+```
+
+- `event` — A unique identifier for the event type.
+- `cv` — Clerk Version. The version of the core Clerk library in use.
+- `sdk` — SDK. The Clerk SDK that is being used.
+- `sdkv` — SDK Version. The version of the Clerk SDK.
+- `pk` — Publishable Key. The instance's publishable key.
+- `payload` — Each unique event can provide custom data as part of the payload. As seen above, for the `COMPONENT_MOUNTED` event we track the component name and additional data about prop usage.
+
+## What about sensitive data?
+
+We will not collect sensitive data from your application or development environment that is not directly related to your implementation of Clerk's SDKs. Notably, we will not collect: environment variables unrelated to Clerk, any information about your users, file paths, contents of files, logs, git remote information, or raw JavaScript errors.
+
+## How is my data protected?
+
+Clerk takes data privacy and protection seriously. Telemetry data is most useful in aggregate form to gain product insights, and the raw data is only available to a small subset of Clerk employees.
+
+We will never share with or sell telemetry data to third parties. The data is used strictly to help improve the Clerk product.
+
+## How do I opt-out?
+
+### Environment variables
+
+<Callout type="warning">
+  Note that the variable name might differ between frameworks. See the [framework specific instructions](#framework-specific-instructions) below.
+</Callout>
+
+For meta-framework SDKs, you can opt-out of telemetry collection by setting the environment variable: 
+
+```env filename=".env.local"
+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 `<ClerkProvider />`:
+
+```tsx
+<ClerkProvider telemetry={false} />
+```
+
+### Framework specific instructions
+
+<CodeBlockTabs options={["Next.js", "React", "Remix", "Gatsby", "JavaScript", "Chrome Extension", "Expo"]}>
+```env filename=".env.local"
+NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED=1
+```
+
+```tsx
+<ClerkProvider telemetry={false} />
+```
+
+```env filename=".env.local"
+CLERK_TELEMETRY_DISABLED=1
+```
+
+```env filename=".env.local"
+GATSBY_CLERK_TELEMETRY_DISABLED=1
+```
+
+```js
+const clerk = new Clerk(publishableKey)
+c.load({ telemetry: false })
+```
+
+```tsx
+<ClerkProvider telemetry={false} />
+```
+
+```tsx
+<ClerkProvider telemetry={false} />
+```
+</CodeBlockTabs>