Merge branch 'main' into vi/chore/remove-clerk

.github/workflows/redeploy.yml

@@ -12,10 +12,9 @@ on:
 jobs:
   redeploy:
     runs-on: ubuntu-latest
+    env:
+      DEPLOY_HOOK: ${{ github.ref == 'refs/heads/main' && secrets.WEBSITE_DEPLOY_HOOK || secrets.WEBSITE_DEPLOY_HOOK_CORE_1 }}
     steps:
       - name: Trigger redeploy
         run: |
-          curl -X POST ${{ secrets.WEBSITE_DEPLOY_HOOK }}
-      - name: Trigger search reindex
-        run: |
-          curl -X POST ${{ secrets.SEARCH_INDEX_DEPLOY_HOOK }}
+          curl -X POST ${{ env.DEPLOY_HOOK }}

CONTRIBUTING.md

@@ -225,6 +225,59 @@ description: Some brief, but effective description of the page's content.
 
 These fields should be present on every documentation page.
 
+#### Search
+
+The `search` frontmatter field can be used to control how a page is indexed by [Algolia Crawler](https://www.algolia.com/doc/tools/crawler/getting-started/overview/). It has the following subfields:
+
+| Name       | Type            | Default | Description                                                                                                                                                                                                                                                                                |
+| ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `exclude`  | `boolean`       | `false` | Whether to exclude the page from search entirely                                                                                                                                                                                                                                           |
+| `rank`     | `number`        | `0`     | The value to use for `weight.pageRank` in the index. See [Custom Ranking](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/) and [Boost search results with `pageRank`](https://docsearch.algolia.com/docs/record-extractor/#boost-search-results-with-pagerank) |
+| `keywords` | `Array<string>` | `[]`    | Additional [searchable](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/) keywords to include when indexing the page. These are not visible to users.                                                                                                    |
+
+You may also set `search` to a boolean value, which acts as an `exclude` value. See the first example below.
+
+##### Examples
+
+<details>
+<summary>Exclude a page from search</summary>
+
+```diff
+  ---
+  title: Example
++ search: false
+  ---
+```
+
+</details>
+
+<details>
+<summary>Boost a page in search results</summary>
+
+```diff
+  ---
+  title: Example
++ search:
++   rank: 1
+  ---
+```
+
+</details>
+
+<details>
+<summary>Show a page in results when searching for "supercalifragilisticexpialidocious"</summary>
+
+```diff
+  ---
+  title: Example
++ search:
++   keywords:
++     - supercalifragilisticexpialidocious
+  ---
+```
+
+</details>
+
 ### Headings
 
 Headings should be nested by their rank. Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher ranked section. Please see the [Web Accessibility Initiative documentation](https://www.w3.org/WAI/tutorials/page-structure/headings/) for more information.

docs/authentication/configuration/legal-compliance.mdx

@@ -0,0 +1,11 @@
+---
+title: Legal compliance
+description: Learn how to configure your legal compliance settings in the Clerk Dashboard.
+---
+
+Clerk provides a legal compliance setting that allows you to require users to agree to your terms of service or privacy policy before they can sign up to your application. After enabling the setting, there will be a checkbox to accept the terms in your [`<SignUp />` component](/docs/components/authentication/sign-up) or [Account Portal sign-up page](/docs/customization/account-portal/overview#sign-up).
+
+To configure the setting:
+
+1. In the Clerk Dashboard, navigate to the [**Legal**](https://dashboard.clerk.com/last-active?path=compliance/legal) page.
+1. Enable or disable **Require express consent to legal documents**.

docs/components/clerk-provider.mdx

@@ -226,7 +226,7 @@ The `<ClerkProvider>` component must be added to your React entrypoint.
   - `nonce?`
   - `string`
 
-  This nonce value will be passed through to the `@clerk/clerk-js` script tag. You can use this to implement [strict-dynamic CSP](/docs/security/clerk-csp#implementing-a-strict-dynamic-csp).
+  This nonce value will be passed to the `@clerk/clerk-js` script tag. Use it to implement a [strict-dynamic CSP](/docs/security/clerk-csp#implementing-a-strict-dynamic-csp). Requires the `dynamic` prop to also be set.
 
   ---
 

docs/customization/elements/overview.mdx

@@ -33,7 +33,7 @@ Clerk Elements currently only works with Next.js App Router and [Clerk Core 2](/
 
 To get started, install the Clerk Elements package:
 
-<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
   ```sh {{ filename: 'terminal' }}
   npm install @clerk/elements
   ```

docs/customization/localization.mdx

@@ -63,7 +63,7 @@ Clerk currently supports the following languages with English as the default:
 
 To get started, install the `@clerk/localizations` package.
 
-<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
   ```bash {{ filename: 'terminal' }}
   npm install @clerk/localizations
   ```

docs/customization/themes.mdx

@@ -40,7 +40,7 @@ Applied by default when no other theme is provided.
 
 1. To get started, install the `@clerk/themes` package.
 
-   <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+   <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
      ```bash {{ filename: 'terminal' }}
      npm install @clerk/themes
      ```

docs/deployments/deploy-expo.mdx

@@ -17,11 +17,21 @@ Clerk ensures that security critical nonces will be passed only to allowlisted U
 
 So for maximum security in your production instances, you need to allowlist your custom redirect URLs:
 
-1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections).
-1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
+1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
 1. Scroll to the **Allowlist for mobile OAuth redirect** section and add your redirect URLs.
-   1. The default is `your-app-scheme://oauth-native-callback`
-   1. If you'd like to pass a custom redirect url, make sure you add that to the allowlist.
+   1. The default is `<INSERT-YOUR-APP-SCHEME>://oauth-native-callback`
+   1. If you'd like to pass a custom redirect URL, make sure you add that to the allowlist. The format is `<INSERT-YOUR-APP-SCHEME>/{PATH}`. For example, the redirect URL for the following code example is `myapp://dashboard`.
+      ```ts
+      const { startOAuthFlow } = useOAuth({ strategy: `oauth_apple` })
+
+      const onPress = React.useCallback(async () => {
+        const { createdSessionId, setActive } = await startOAuthFlow({
+          redirectUrl: Linking.createURL('dashboard', { scheme: 'myapp' }),
+        })
+
+        // The rest of your code...
+      }, [])
+      ```
 
 > [!TIP]
 > You can also add redirect URLs via [the Backend API](/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL).

docs/guides/authjs-migration.mdx

@@ -42,7 +42,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth.
 
   Clerk's Next.js SDK gives you access to prebuilt [components](/docs/components/overview), [hooks](/docs/references/nextjs/overview#client-side-helpers), and [helpers](/docs/references/nextjs/overview) for Next.js Server Components, Route Handlers and Middleware. Run the following command to install it:
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash {{ filename: 'terminal' }}
     npm install @clerk/nextjs
     ```
@@ -71,7 +71,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth.
 
   You will need to remove the `<SessionProvider session={session}>` provider from Auth.js and replace it with the `<ClerkProvider />` provider from Clerk. `<ClerkProvider />` will need to wrap your application, or wrap the portion of your app where you want to handle authentication.
 
-  <CodeBlockTabs type="installer" options={["App Router", "Pages Router"]}>
+  <CodeBlockTabs options={["App Router", "Pages Router"]}>
     ```tsx {{ filename: 'app/layout.tsx', mark: [1, 6, 10] }}
     import { ClerkProvider } from '@clerk/nextjs'
     import './globals.css'
@@ -174,7 +174,7 @@ This guide shows how to migrate an application using Auth.js (formerly NextAuth.
 
   Replace any Auth.js `getServerSession(req, res, authOptions)` with Clerk's helpers.
 
-  <Tabs type="installer" items={["App Router", "Pages Router"]}>
+  <Tabs items={["App Router", "Pages Router"]}>
     <Tab>
       You can replace Auth.js's `setServerSession()` with Clerk's [`auth()`](/docs/references/nextjs/auth#auth) helper in order to read your user data.
 

docs/integrations/databases/convex.mdx

@@ -76,7 +76,7 @@ This tutorial assumes that you have already [set up a Clerk application](/docs/q
 
   Run the following command to install Clerk's React SDK:
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn",  "pnpm" ]}>
+  <CodeBlockTabs options={["npm", "yarn",  "pnpm" ]}>
     ```bash {{ filename: 'terminal' }}
     npm install @clerk/clerk-react
     ```

docs/integrations/webhooks/sync-data.mdx

@@ -91,7 +91,7 @@ This guide can be adapted to listen for any Clerk event.
 
   You will use [`svix`](https://www.npmjs.com/package/svix) to verify the webhook signature. Run the following command to install it:
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash {{ filename: 'terminal' }}
     npm install svix
     ```

docs/maintenance-mode.mdx

@@ -0,0 +1,16 @@
+---
+title: Maintenance Mode
+description: Learn about Clerk's Maintenance Mode.
+---
+
+**Maintenance Mode** is a special operational state designed to ensure minimal disruption to signed-in users during critical database upgrades or outages.
+
+## Production instances
+
+Mutation methods (`POST`, `PATCH`, `PUT`, `DELETE`) will be rejected with a `503 Service Unavailable` status, along with an error message informing users that the system is temporarily unavailable. This includes all sign-up and sign-in attempts. Clerk's prebuilt components and the hosted Account Portal will display errors for these requests.
+
+GET requests, as well as session refresh requests ([`/touch`](/docs/reference/frontend-api/tag/Sessions#operation/touchSession) and [`/tokens`](/docs/reference/frontend-api/tag/Sessions#operation/createSessionToken) endpoints), aren't affected. Users with active sessions (already signed in) will not be signed out, and will continue to have access to your app. However, any mutations to their user or org data will return the same `503` error.
+
+## Development instances
+
+During this period, development instances will experience full downtime. Users will be unable to sign up or in, and already signed-in users will be signed out.

docs/manifest.json

@@ -350,6 +350,10 @@
                         {
                           "title": "Restrictions",
                           "href": "/docs/authentication/configuration/restrictions"
+                        },
+                        {
+                          "title": "Legal compliance",
+                          "href": "/docs/authentication/configuration/legal-compliance"
                         }
                       ]
                     ]

docs/references/astro/migrating-from-astro-community-sdk.mdx

@@ -9,7 +9,7 @@ In July 2024, we introduced official support for Astro. This migration guide cov
 
 Uninstall the community SDK and install Clerk's new official SDK for Astro.
 
-<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
   ```bash {{ filename: 'terminal' }}
   npm uninstall astro-clerk-auth
   npm install @clerk/astro

docs/references/astro/react.mdx

@@ -12,7 +12,7 @@ If you have not set up your Astro application to work with Clerk, visit the [Ast
 
   Add the [Astro React integration](https://docs.astro.build/en/guides/integrations-guide/react/) to your project:
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash {{ filename: 'terminal' }}
     npx astro add react
     ```

docs/references/backend/testing-tokens/create-testing-token.mdx

@@ -3,7 +3,7 @@ title: '`createTestingToken()`'
 description: Use Clerk's Backend SDK to create a testing token for the instance.
 ---
 
-Creates a Testing Token for the instance. **It only works on development instances.**
+Creates a Testing Token for the instance.
 
 ```ts
 function createTestingToken(): Promise<TestingToken>

docs/references/expo/local-credentials.mdx

@@ -16,7 +16,7 @@ This guide shows you how to use the `useLocalCredentials()` hook to enhance your
 
   These packages are required to be installed in order to use the `useLocalCredentials()` hook.
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash {{ filename: 'terminal' }}
     npm install expo-local-authentication expo-secure-store
     ```

docs/references/expo/web-support/custom-signup-signin-pages.mdx

@@ -36,7 +36,7 @@ This guide uses [Expo Router](https://docs.expo.dev/router/introduction/) and th
 
   To run your project, use the following command:
 
-  <CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
     ```bash filename="terminal"
     npm run web
     ```

docs/references/express/overview.mdx

@@ -103,7 +103,7 @@ const hasPermission = (req, res, next) => {
 
   // Handle if the user is not authorized
   if (!auth.has({ permission: 'org:admin:testpermission' })) {
-    return response.status(403).send('Forbidden')
+    return res.status(403).send('Forbidden')
   }
 
   return next()

docs/references/javascript/sign-up/authenticate-with.mdx

@@ -58,6 +58,13 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
   - `string | undefined`
 
   Email address to use for targeting a SAML connection at sign-up.
+
+  ---
+
+  - `legalAccepted?`
+  - `boolean`
+
+  The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ## `authenticateWithWeb3()`
@@ -89,6 +96,13 @@ function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise<SignU
   - `Web3Strategy`
 
   The Web3 verification strategy.
+
+  ---
+
+  - `legalAccepted?`
+  - `boolean`
+
+  The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ### `GenerateSignatureParams`
@@ -112,6 +126,13 @@ function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise<SignU
   - `Web3Provider`
 
   The Web3 provider to generate the signature with.
+
+  ---
+
+  - `legalAccepted?`
+  - `boolean`
+
+  The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ## `authenticateWithMetamask()`
@@ -131,6 +152,13 @@ function authenticateWithMetamask(
   - `{[string]: any}`
 
   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.
 </Properties>
 
 ## `authenticateWithCoinbaseWallet()`
@@ -150,6 +178,13 @@ function authenticateWithCoinbaseWallet(
   - `{[string]: any}`
 
   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.
 </Properties>
 
 [signup-ref]: /docs/references/javascript/sign-up/sign-up

docs/references/javascript/sign-up/sign-up.mdx

@@ -264,6 +264,13 @@ function create(params: SignUpCreateParams): Promise<SignUpResource>
   - `boolean`
 
   Transfer the user to a dedicated sign-up for an OAuth flow.
+
+  ---
+
+  - `legalAccepted`
+  - `boolean`
+
+  The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ### `update()`

docs/references/javascript/types/overview.mdx

@@ -7,7 +7,7 @@ Types are a powerful tool for adding type-safety to your application. They can h
 
 To get access to Clerk types, you need to add the `@clerk/types` package to your project. Run the following command to install it:
 
-<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
   ```bash {{ filename: 'terminal' }}
   npm install @clerk/types
   ```

docs/references/javascript/user/user.mdx

@@ -252,6 +252,13 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to
 
   ---
 
+  - `legalAcceptedAt`
+  - `Date`
+
+  Date when the user accepted the legal documents. May be empty if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled.
+
+  ---
+
   - `lastSignInAt`
   - `Date`
 

docs/references/nextjs/clerk-middleware.mdx

@@ -390,6 +390,9 @@ export default clerkMiddleware(
 
 ### Dynamic keys
 
+> [!NOTE]
+> Dynamic keys are not accessible on the client-side.
+
 The following options, known as "Dynamic Keys," are shared to the Next.js application server through `clerkMiddleware`, enabling access by server-side helpers like [`auth()`](/docs/references/nextjs/auth):
 
 - `signUpUrl`
@@ -427,6 +430,3 @@ export default clerkMiddleware(
   },
 )
 ```
-
-> [!NOTE]
-> Dynamic keys are not accessible on the client-side.