Skip to content

Commit d594e0f

Browse files
manovotnyclaude
manovotny
and
claude
committed
docs: lighten vercel app sub-sections and reposition callouts
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 28b75b2 commit d594e0f

1 file changed

Lines changed: 67 additions & 37 deletions

File tree

‎docs/guides/development/deployment/production.mdx‎

Lines changed: 67 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -47,16 +47,29 @@ If you're using a CSP, follow the instructions in the [CSP guide](/docs/guides/s
4747

4848
## Configure your domain
4949

50-
Production deployments use either a custom domain or a Vercel-provided `*.vercel.app` domain. Pick the section below that matches your setup.
50+
Production deployments use either a custom domain or a Vercel-provided `*.vercel.app` domain.
51+
52+
On `*.vercel.app` instances, core auth emails are delivered through Clerk's shared `accounts.dev` email infrastructure. Custom domains support more features:
53+
54+
| Feature | `*.vercel.app` domain | Custom domain |
55+
| - | :-: | :-: |
56+
| Sign-in and sign-up verification | <CompareYes /> | <CompareYes /> |
57+
| Verification codes | <CompareYes /> | <CompareYes /> |
58+
| Password reset codes | <CompareYes /> | <CompareYes /> |
59+
| Branded email domain | <CompareNo /> | <CompareYes /> |
60+
| Custom email templates | <CompareNo /> | <CompareYes /> |
61+
| Email link authentication | <CompareNo /> | <CompareYes /> |
62+
| Application invitations | <CompareNo /> | <CompareYes /> |
63+
| Organization invitations | <CompareNo /> | <CompareYes /> |
64+
| Hosted Account Portal | <CompareNo /> | <CompareYes /> |
65+
66+
Pick the section below that matches your setup.
5167

5268
### Custom domain {{ id: 'dns-records' }}
5369

5470
If you're using a custom domain, you'll need to be able to add DNS records on it. Clerk uses DNS records to provide session management and emails verified from your domain.
5571

56-
To see what DNS records you need, navigate to the [**Domains**](https://dashboard.clerk.com/~/domains) page in the Clerk Dashboard.
57-
58-
> [!NOTE]
59-
> It can take up to 48hrs for DNS records to fully propagate.
72+
To see what DNS records you need, navigate to the [**Domains**](https://dashboard.clerk.com/~/domains) page in the Clerk Dashboard. After you add them, propagation can take up to 48 hours.
6073

6174
> [!TIP]
6275
> If you're unable to add a CNAME record for the Frontend API, you can use a proxy instead. See [Proxying the Clerk Frontend API](/docs/guides/dashboard/dns-domains/proxy-fapi) for more information.
@@ -65,6 +78,9 @@ To see what DNS records you need, navigate to the [**Domains**](https://dashboar
6578

6679
Production instances can use a Vercel-provided `*.vercel.app` domain. This setup is designed for Vercel apps and doesn't require you to add Clerk DNS records manually. Instead, Clerk routes browser auth traffic through your Vercel app using the `https://<your-app>.vercel.app/__clerk` proxy path.
6780

81+
> [!NOTE]
82+
> This setup requires a Clerk SDK release with Vercel auto-proxy support: `@clerk/nextjs` 7.2.8+, `@clerk/clerk-js` 6.7.8+, or `@clerk/backend` 3.4.2+.
83+
6884
If you're using a Next.js proxy, ensure the matcher includes Clerk's proxy path:
6985

7086
```ts {{ filename: 'proxy.ts' }}
@@ -81,47 +97,61 @@ export const config = {
8197

8298
After you update your proxy's matcher, in the Clerk Dashboard, return to the [**Domains**](https://dashboard.clerk.com/~/domains) page and select **Verify proxy** to confirm that Clerk can reach the `__clerk` proxy path. Keep `/__clerk/(.*)` as a separate matcher entry, even if you already have a broad matcher, because Clerk also loads browser assets from `/__clerk/npm/...`. Without the explicit matcher, a static-asset exclusion can skip those requests and authentication can fail.
8399

84-
When using this setup:
100+
Sign-up, sign-in, social OAuth callbacks, email-code verification, password verification, `auth()`, and `getToken()` all use the same auto-proxy path on your app domain.
85101

86-
- Use production Clerk API keys (`pk_live_` and `sk_live_`).
87-
- Use a Clerk SDK release with Vercel auto-proxy support: `@clerk/nextjs` 7.2.8+, `@clerk/clerk-js` 6.7.8+, or `@clerk/backend` 3.4.2+.
102+
#### Authentication on the app domain
88103

89-
Sign-up, sign-in, social OAuth callbacks, email-code verification, password verification, `auth()`, and `getToken()` all use the same auto-proxy path on your app domain.
104+
Production `*.vercel.app` instances have the hosted Account Portal disabled by default. The built-in Clerk components render in modal mode on your app's own domain, so they work without additional configuration:
90105

91-
Core auth emails are delivered through Clerk's shared `accounts.dev` email infrastructure, so custom domains are still recommended when you need full branded production behavior:
106+
- `<SignIn />` and `<SignUp />` render on the page where you place them.
107+
- `<UserButton />` opens `<UserProfile />` in a modal on the app domain.
108+
- `<OrganizationSwitcher />` opens `<CreateOrganization />` and `<OrganizationProfile />` in modals on the app domain.
109+
- `<SignOutButton />` and `clerk.signOut()` redirect to `/` by default.
92110

93-
| Feature | `*.vercel.app` domain | Custom domain |
94-
| - | :-: | :-: |
95-
| Sign-in and sign-up verification | <CompareYes /> | <CompareYes /> |
96-
| Verification codes | <CompareYes /> | <CompareYes /> |
97-
| Password reset codes | <CompareYes /> | <CompareYes /> |
98-
| Branded email domain | <CompareNo /> | <CompareYes /> |
99-
| Custom email templates | <CompareNo /> | <CompareYes /> |
100-
| Email link authentication | <CompareNo /> | <CompareYes /> |
101-
| Application invitations | <CompareNo /> | <CompareYes /> |
102-
| Organization invitations | <CompareNo /> | <CompareYes /> |
103-
| Hosted Account Portal | <CompareNo /> | <CompareYes /> |
111+
If you need to opt out of modal mode or use programmatic redirects, the configuration depends on the mechanism.
104112

105-
#### Authentication on the app domain
113+
##### Components in navigation mode
114+
115+
To make `<UserButton />` or `<OrganizationSwitcher />` navigate to dedicated pages instead of opening modals, pass navigation-mode props on the component instance and host the corresponding flow as a page.
116+
117+
For `<UserButton />`:
118+
119+
```tsx {{ prettier: false }}
120+
// Open <UserProfile /> as a page at /user-profile instead of a modal
121+
<UserButton userProfileMode="navigation" userProfileUrl="/user-profile" />
122+
123+
// Render the matching page at /user-profile
124+
<UserProfile path="/user-profile" routing="path" />
125+
```
126+
127+
`<OrganizationSwitcher />` uses the same pattern across its two flows. Render `<CreateOrganization />` and `<OrganizationProfile />` on the matching pages:
106128

107-
Production `*.vercel.app` instances have the hosted Account Portal disabled by default. The built-in Clerk components render in modal mode on your app's own domain, so they work without additional configuration.
129+
```tsx {{ prettier: false }}
130+
// Open <CreateOrganization /> and <OrganizationProfile /> as pages instead of modals
131+
<OrganizationSwitcher
132+
createOrganizationMode="navigation"
133+
createOrganizationUrl="/create-organization"
134+
organizationProfileMode="navigation"
135+
organizationProfileUrl="/organization"
136+
/>
137+
```
108138

109-
| Component | Behavior on `*.vercel.app` |
110-
| - | - |
111-
| `<SignIn />`, `<SignUp />` | Render on the app domain. |
112-
| `<UserButton />` | Opens `<UserProfile />` in a modal on the app domain. |
113-
| `<OrganizationSwitcher />` | Opens `<CreateOrganization />` and `<OrganizationProfile />` in modals on the app domain. |
114-
| `<SignOutButton>`, `clerk.signOut()` | Redirect to `/` by default. |
139+
##### Standalone redirect helpers
115140

116-
Programmatic redirect helpers and `navigation`-mode components read URLs from the instance's display config, which on a `*.vercel.app` instance point to the disabled Account Portal subdomain. To use them, host the corresponding flow on your app and pass the URL explicitly:
141+
`clerk.redirectToUserProfile()`, `clerk.redirectToCreateOrganization()`, and `clerk.redirectToOrganizationProfile()` resolve to URLs in the instance's display config, which on a `*.vercel.app` instance points to the disabled Account Portal subdomain. They can't be overridden via `<ClerkProvider>` or component props. For these flows on `*.vercel.app`, use the navigation-mode component pattern above instead of calling the helpers directly.
117142

118-
| API | Required configuration |
119-
| - | - |
120-
| `clerk.redirectToUserProfile()` | Render `<UserProfile path="/user-profile" routing="path" />` and pass `<UserButton userProfileMode="navigation" userProfileUrl="/user-profile" />`. |
121-
| `clerk.redirectToCreateOrganization()` | Render `<CreateOrganization path="/create-organization" routing="path" />` and pass `createOrganizationUrl` to relevant components. |
122-
| `clerk.redirectToOrganizationProfile()` | Render `<OrganizationProfile path="/organization" routing="path" />` and pass `organizationProfileUrl` to relevant components. |
123-
| Waitlist flows | Render `<Waitlist />` on your app and pass `waitlistUrl` to `<ClerkProvider>` or `<Waitlist />`. |
124-
| Multi-session single sign-out | Pass `signInUrl` to `<ClerkProvider>` so Clerk can build the session-switch URL on your app. |
143+
`clerk.redirectToWaitlist()` and multi-session single sign-out are overridable via props on `<ClerkProvider>`:
144+
145+
```tsx
146+
<ClerkProvider
147+
// Used by clerk.redirectToWaitlist()
148+
waitlistUrl="/waitlist"
149+
// Used to build the session-switch URL for multi-session sign-out
150+
signInUrl="/sign-in"
151+
>
152+
{/* ... */}
153+
</ClerkProvider>
154+
```
125155

126156
#### Verifying session tokens
127157

0 commit comments

Comments
 (0)