Add new Clerk Dashboard docs and restructure overview page by manovotny · Pull Request #3241 · clerk/clerk-docs

manovotny · 2026-03-20T23:16:13Z

🔎 Previews:

What does this solve? What changed?

The Dashboard team has shipped several new features (analytics, user/org profile pages with activity heatmaps, billing metrics) but the Clerk Dashboard docs section only had two pages: Overview and DNS & Domains. This PR expands the section to document these features and restructures the overview page, which had grown unwieldy.

New pages (4):

Analytics — Documents the Dashboard analytics page: report customization (date range, interval, preferences persistence), user vs. org analytics toggle, data methodology (active users, active orgs, sign-ins, sign-ups, retention, data freshness), and FAQ (dev instances excluded, impersonated sessions excluded, M2M excluded).
User profile — Documents the user profile page in the Dashboard: activity heatmap, user details and management actions (with cross-link to impersonation docs), organizations membership, and billing metrics (MRR, lifetime revenue, LTV).
Organization profile — Documents the organization profile page: activity heatmap (% of members active), org details, member management, and billing metrics.
Manage team access — Extracted from the overview page. Contains all workspace role definitions (Owner, Admin, Developer, Support, Viewer) with their permission tables. The Important banner about plan availability was moved below the roles summary table for better reading flow.

Restructured overview page:

Renamed sidebar title from "Overview" to "Manage your workspace" (file path unchanged — preserves all inbound links from typedoc, redirects, and other docs)
Removed redundant paragraph about workspace selection behavior
Replaced ~140 lines of inline roles content with a link to the new Manage team access page
Updated "Invite team members" section to "Invite and manage team members" — now mentions the global Invite button in the nav and how to manage members via the Team tab
Normalized Dashboard URLs from dashboard.clerk.com/settings to dashboard.clerk.com/~/settings for consistency

Cross-links added:

docs/guides/users/managing.mdx — "see also" link to the new user profile page
docs/guides/organizations/create-and-manage.mdx — "see also" link to the new organization profile page

What we intentionally did NOT move (and why):

DNS & Domains — The PDF suggested moving this out of the Dashboard section. After analysis, we left it in place. The content (satellite domains, proxy FAPI, subdomain allowlist) is configured via the Dashboard, and moving it would risk breaking cross-references for no strong organizational gain. Can be revisited separately.
Impersonation — The PDF suggested moving this into the Dashboard section. The impersonation page is heavily code-focused (actor tokens, detecting impersonated sessions in Next.js/Express/Astro/etc.), so it belongs under User management. The new user profile page cross-links to it where relevant.
Enrichment / Session replay — Marked as "Future" in the PDF. Not included in this PR.

Deadline

No rush

Other resources

DOCS-11628
Dashboard team's starter plan PDF (shared internally)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel · 2026-03-20T23:16:19Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Apr 1, 2026 2:56pm

Settings and Team are workspace-scoped routes that don't use the /~/ prefix (which is for app-scoped routes). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The numbered steps already explain both methods (Invite button and Team page), so the intro paragraph was duplicating the instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Link the Analytics Dashboard page and convert the data methodology subsections into a scannable table format. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Unlink the inline impersonation mention to avoid linking the same guide twice in one paragraph. Change 'details section' to 'user profile' since there is no UI element labeled 'details'. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rename 'Organization activity' to 'Member activity' to match the actual Dashboard UI label. Change 'details section' to 'organization profile' for consistency. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

manovotny · 2026-03-23T15:54:14Z

@SarahSoutoul all feedback has been addressed.

Analytics lives on the project's Overview page at dashboard.clerk.com, not a separate /~/analytics route. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Clarify active organization eligibility and bold the key term. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Active user in analytics counts sign-up day activity, while MRU excludes it. Add a tooltip to clarify the difference. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

manovotny · 2026-04-01T14:55:07Z

@alexisintech @nate-watkin all feedback addressed. This is ready for final review.

alexisintech

lets 🚢 thanks for the work on this 🙏

Fixes a typo, removes documentation for unshipped heatmap features, and updates analytics copy and FAQs based on internal feedback. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add new Clerk Dashboard docs and restructure overview page

4b5cba3

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

manovotny requested a review from a team as a code owner March 20, 2026 23:16

vercel bot deployed to Preview March 20, 2026 23:17 View deployment

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/overview.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/overview.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/overview.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/user-profile.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/user-profile.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/organization-profile.mdx Outdated

SarahSoutoul self-assigned this Mar 23, 2026

Fix Dashboard URLs for workspace-scoped routes

3d3a6a2

Settings and Team are workspace-scoped routes that don't use the /~/ prefix (which is for app-scoped routes). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview March 23, 2026 15:12 View deployment

manovotny and others added 4 commits March 23, 2026 10:26

Remove redundant intro from invite section

f23db43

The numbered steps already explain both methods (Invite button and Team page), so the intro paragraph was duplicating the instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add Analytics link and convert data methodology to table

83093fd

Link the Analytics Dashboard page and convert the data methodology subsections into a scannable table format. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Rename to Member activity and soften section label

ac64236

Rename 'Organization activity' to 'Member activity' to match the actual Dashboard UI label. Change 'details section' to 'organization profile' for consistency. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview March 23, 2026 15:28 View deployment

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx Outdated

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx Outdated

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx Outdated

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/manage-team-access.mdx Outdated

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/manage-team-access.mdx Outdated

SarahSoutoul assigned alexisintech Mar 23, 2026

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/manage-team-access.mdx Outdated

alexisintech reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/manage-team-access.mdx Outdated

Fix Analytics page link to point to Dashboard Overview

b7195ea

Analytics lives on the project's Overview page at dashboard.clerk.com, not a separate /~/analytics route. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview March 23, 2026 17:19 View deployment

Apply suggestions from code review

dcbb124

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>

vercel bot deployed to Preview March 23, 2026 17:22 View deployment

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx Outdated

SarahSoutoul reviewed Mar 23, 2026

View reviewed changes

Comment thread docs/guides/dashboard/analytics.mdx

Remove duplicate Dashboard link in analytics intro

1d0a8a3

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview March 23, 2026 17:28 View deployment

Apply suggestions from code review

d1ccb93

Clarify active organization eligibility and bold the key term. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview March 30, 2026 16:23 View deployment

Add MRU tooltip to distinguish active user from MRU

7dfa8e6

Active user in analytics counts sign-up day activity, while MRU excludes it. Add a tooltip to clarify the difference. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview April 1, 2026 14:56 View deployment

alexisintech approved these changes Apr 1, 2026

View reviewed changes

manovotny merged commit 3173818 into main Apr 1, 2026
8 checks passed

manovotny deleted the manovotny/manovotny/docs-11628-implement-proposed-changes-to-clerk-das branch April 1, 2026 21:27

manovotny mentioned this pull request Apr 1, 2026

Fix copy and remove unshipped features from Dashboard docs #3263

Merged

Conversation

manovotny commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Previews:

What does this solve? What changed?

Deadline

Other resources

Uh oh!

vercel bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

manovotny commented Mar 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

manovotny commented Apr 1, 2026

Uh oh!

alexisintech left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

manovotny commented Mar 20, 2026 •

edited

Loading

vercel bot commented Mar 20, 2026 •

edited

Loading