feat(react): Implement waitlist hook with signal primitives #7097
Conversation
This commit introduces the Waitlist resource, enabling users to join a waitlist via email. It includes new hooks for accessing and interacting with the waitlist functionality in React applications. Co-authored-by: bryce <bryce@clerk.dev>
Co-authored-by: bryce <bryce@clerk.dev>
Co-authored-by: bryce <bryce@clerk.dev>
|
Cursor Agent can help with this pull request. Just |
🦋 Changeset detectedLatest commit: 2da25c6 The changes in this PR will be included in the next version bump. This PR includes changesets to release 19 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis pull request introduces a comprehensive waitlist feature across the Clerk ecosystem. The changes include: fixing a typo in the environment configuration constant from 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Co-authored-by: bryce <bryce@clerk.dev>
| get __internal_waitlist() { | ||
| if (!this._waitlistInstance) { | ||
| this._waitlistInstance = new Waitlist(null); | ||
| this.waitlistResourceSignal({ resource: this._waitlistInstance }); | ||
| } | ||
| return this._waitlistInstance; | ||
| } |
There was a problem hiding this comment.
The proxy layer needed a way to access a waitlist instance, and so this property was added. It would be nice if there was a way to avoid having to do this though... 🤔
…hook-with-signal-primitives-3ad1
…hook-with-signal-primitives-3ad1
…hook-with-signal-primitives-3ad1
nikosdouvlis
force-pushed
the
vincent-and-the-doctor
branch
from
d24d455 to
12a12f5
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (4)
packages/shared/src/types/clerk.ts (1)
46-46: Consider using type-only import for better tree-shaking.The refactoring to import
JoinWaitlistParamsandWaitlistResourcefrom'./waitlist'is good for maintaining a single source of truth. However, since these are type-only imports, consider using theimport typesyntax for better tree-shaking optimization.As per coding guidelines, apply this diff:
-import type { JoinWaitlistParams, WaitlistResource } from './waitlist'; +import type { JoinWaitlistParams, WaitlistResource } from './waitlist';Actually, the import already uses
import type, so this is already optimal. The change is good as-is!integration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx (1)
11-22: TightenFormDatatyping and add an explicit return typeTo avoid relying on a cast from
FormData.getand to follow the explicit-return-type guideline, you could slightly adjusthandleSubmit:-export function Waitlist({ className, ...props }: React.ComponentProps<'div'>) { +export function Waitlist({ className, ...props }: React.ComponentProps<'div'>): JSX.Element { const { waitlist, errors, fetchStatus } = useWaitlist(); - const handleSubmit = async (formData: FormData) => { - const emailAddress = formData.get('emailAddress') as string | null; - - if (!emailAddress) { - return; - } - - await waitlist.join({ emailAddress }); - }; + const handleSubmit = async (formData: FormData): Promise<void> => { + const value = formData.get('emailAddress'); + if (typeof value !== 'string' || !value) { + return; + } + + await waitlist.join({ emailAddress: value }); + };This keeps the behavior the same while making the typing more robust.
packages/clerk-js/src/core/resources/Waitlist.ts (1)
34-47: Optional: avoidas anyon the request bodyThe join flow and eventBus wiring look correct. The only minor nit is the
body: params as anycast; if_fetchcan accept a typed payload, consider tightening this:- const json = await BaseResource._fetch<WaitlistJSON>({ - path: '/waitlist', - method: 'POST', - body: params as any, - }); + const json = await BaseResource._fetch<WaitlistJSON>({ + path: '/waitlist', + method: 'POST', + body: params, // keep typed as JoinWaitlistParams if `_fetch` supports it + });If
_fetchtruly requires an untyped value, the current code is fine.packages/react/src/hooks/useClerkSignal.ts (1)
8-27: Hook wiring forwaitlistlooks correct; consider adding telemetry for parityThe new
'waitlist'overload and branches insubscribe/getSnapshotare consistent withsignIn/signUp, anduseWaitlist()is a thin, correct wrapper.If you want analytics parity with the other hooks, you could extend the switch to record telemetry for
useWaitlistas well:switch (signal) { case 'signIn': clerk.telemetry?.record(eventMethodCalled('useSignIn', { apiVersion: '2025-11' })); break; case 'signUp': clerk.telemetry?.record(eventMethodCalled('useSignUp', { apiVersion: '2025-11' })); break; + case 'waitlist': + clerk.telemetry?.record(eventMethodCalled('useWaitlist', { apiVersion: '2025-11' })); + break; default: break; }Not required for correctness, but useful if you're tracking hook adoption.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (2)
packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snapis excluded by!**/*.snappackages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snapis excluded by!**/*.snap
📒 Files selected for processing (18)
integration/presets/envs.ts(2 hunks)integration/templates/custom-flows-react-vite/src/main.tsx(2 hunks)integration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx(1 hunks)integration/testUtils/index.ts(2 hunks)integration/testUtils/waitlistService.ts(1 hunks)integration/tests/custom-flows/waitlist.test.ts(1 hunks)integration/tests/waitlist-mode.test.ts(1 hunks)packages/clerk-js/src/core/resources/Waitlist.ts(3 hunks)packages/clerk-js/src/core/signals.ts(3 hunks)packages/clerk-js/src/core/state.ts(6 hunks)packages/localizations/README.md(1 hunks)packages/react/src/hooks/index.ts(1 hunks)packages/react/src/hooks/useClerkSignal.ts(4 hunks)packages/react/src/stateProxy.ts(5 hunks)packages/shared/src/types/clerk.ts(1 hunks)packages/shared/src/types/state.ts(6 hunks)packages/shared/src/types/waitlist.ts(1 hunks)packages/tanstack-react-start/package.json(0 hunks)
💤 Files with no reviewable changes (1)
- packages/tanstack-react-start/package.json
🧰 Additional context used
📓 Path-based instructions (19)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
All code must pass ESLint checks with the project's configuration
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.{js,jsx,ts,tsx,json,md,yml,yaml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/localizations/README.mdpackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Follow established naming conventions (PascalCase for components, camelCase for variables)
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.ts?(x)
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/typescript.mdc)
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Implement type guards forunknowntypes using the patternfunction isType(value: unknown): value is Type
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details in classes
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Use mixins for shared behavior across unrelated classes in TypeScript
Use generic constraints with bounded type parameters like<T extends { id: string }>
Use utility types likeOmit,Partial, andPickfor data transformation instead of manual type construction
Use discriminated unions instead of boolean flags for state management and API responses
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation at the type level
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Document functions with JSDoc comments including @param, @returns, @throws, and @example tags
Create custom error classes that extend Error for specific error types
Use the Result pattern for error handling instead of throwing exceptions
Use optional chaining (?.) and nullish coalescing (??) operators for safe property access
Let TypeScript infer obvious types to reduce verbosity
Useconst assertionswithas constfor literal types
Usesatisfiesoperator for type checking without widening types
Declare readonly arrays and objects for immutable data structures
Use spread operator and array spread for immutable updates instead of mutations
Use lazy loading for large types...
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use ESLint with custom configurations tailored for different package types
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.{js,ts,jsx,tsx,json,md,yml,yaml}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use Prettier for code formatting across all packages
Files:
integration/testUtils/waitlistService.tsintegration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxintegration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.tspackages/react/src/hooks/index.tspackages/localizations/README.mdpackages/shared/src/types/clerk.tspackages/shared/src/types/state.tsintegration/presets/envs.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tsintegration/testUtils/index.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/*.tsx
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.tsx: Use error boundaries in React components
Minimize re-renders in React components
**/*.tsx: Use proper type definitions for props and state in React components
Leverage TypeScript's type inference where possible in React components
Use proper event types for handlers in React components
Implement proper generic types for reusable React components
Use proper type guards for conditional rendering in React components
Files:
integration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx
**/*.{md,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Update documentation for API changes
Files:
integration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsxpackages/localizations/README.md
**/*.{jsx,tsx}
📄 CodeRabbit inference engine (.cursor/rules/react.mdc)
**/*.{jsx,tsx}: Always use functional components with hooks instead of class components
Follow PascalCase naming for components (e.g.,UserProfile,NavigationMenu)
Keep components focused on a single responsibility - split large components
Limit component size to 150-200 lines; extract logic into custom hooks
Use composition over inheritance - prefer smaller, composable components
Export components as named exports for better tree-shaking
One component per file with matching filename and component name
Separate UI components from business logic components
Use useState for simple state management in React components
Use useReducer for complex state logic in React components
Implement proper state initialization in React components
Use proper state updates with callbacks in React components
Implement proper state cleanup in React components
Use Context API for theme/authentication state management
Implement proper state persistence in React applications
Use React.memo for expensive components
Implement proper useCallback for handlers in React components
Use proper useMemo for expensive computations in React components
Implement proper virtualization for lists in React components
Use proper code splitting with React.lazy in React applications
Implement proper cleanup in useEffect hooks
Use proper refs for DOM access in React components
Implement proper event listener cleanup in React components
Use proper abort controllers for fetch in React components
Implement proper subscription cleanup in React components
Use proper HTML elements for semantic HTML in React components
Implement proper ARIA attributes for accessibility in React components
Use proper heading hierarchy in React components
Implement proper form labels in React components
Use proper button types in React components
Implement proper focus management for keyboard navigation in React components
Use proper keyboard shortcuts in React components
Implement proper tab order in React components
Use proper ...
Files:
integration/templates/custom-flows-react-vite/src/main.tsxintegration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx
**/*.{test,spec}.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{test,spec}.{ts,tsx,js,jsx}: Unit tests are required for all new functionality
Verify proper error handling and edge cases
Include tests for all new features
Files:
integration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.ts
**/*.{test,spec,e2e}.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use real Clerk instances for integration tests
Files:
integration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.ts
**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use React Testing Library for component testing
Files:
integration/tests/custom-flows/waitlist.test.tsintegration/tests/waitlist-mode.test.ts
packages/**/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
packages/**/src/**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
packages/**/src/**/*.{ts,tsx,js,jsx}: Maintain comprehensive JSDoc comments for public APIs
Use tree-shaking friendly exports
Validate all inputs and sanitize outputs
All public APIs must be documented with JSDoc
Use dynamic imports for optional features
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Implement proper logging with different levels
Files:
packages/react/src/hooks/index.tspackages/shared/src/types/clerk.tspackages/shared/src/types/state.tspackages/shared/src/types/waitlist.tspackages/react/src/stateProxy.tspackages/react/src/hooks/useClerkSignal.tspackages/clerk-js/src/core/state.tspackages/clerk-js/src/core/resources/Waitlist.tspackages/clerk-js/src/core/signals.ts
**/index.ts
📄 CodeRabbit inference engine (.cursor/rules/typescript.mdc)
Avoid barrel files (index.ts re-exports) as they can cause circular dependencies
Files:
packages/react/src/hooks/index.tsintegration/testUtils/index.ts
**/README.md
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Provide usage examples in documentation
Files:
packages/localizations/README.md
packages/*/README.md
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
packages/*/README.md: Maintain up-to-date README files for each package
Maintain compatibility matrices for supported versions
Files:
packages/localizations/README.md
packages/localizations/**/*
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Organize localization translations in
packages/localizations/with support for 30+ languages and RTL language support
Files:
packages/localizations/README.md
🧬 Code graph analysis (10)
integration/testUtils/waitlistService.ts (1)
packages/backend/src/index.ts (1)
ClerkClient(24-27)
integration/templates/custom-flows-react-vite/src/main.tsx (2)
integration/templates/tanstack-react-start/src/routes/__root.tsx (1)
Route(8-13)integration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx (1)
Waitlist(11-112)
integration/templates/custom-flows-react-vite/src/routes/Waitlist.tsx (5)
integration/templates/custom-flows-react-vite/src/lib/utils.ts (1)
cn(4-6)integration/templates/custom-flows-react-vite/src/components/ui/card.tsx (5)
Card(78-78)CardHeader(78-78)CardTitle(78-78)CardDescription(78-78)CardContent(78-78)integration/templates/custom-flows-react-vite/src/components/ui/label.tsx (1)
Label(19-19)integration/templates/custom-flows-react-vite/src/components/ui/input.tsx (1)
Input(21-21)integration/templates/custom-flows-react-vite/src/components/ui/button.tsx (1)
Button(56-56)
integration/tests/custom-flows/waitlist.test.ts (4)
integration/models/application.ts (1)
Application(10-10)integration/presets/index.ts (1)
appConfigs(14-30)packages/shared/src/keys.ts (1)
parsePublishableKey(87-136)integration/testUtils/index.ts (1)
createTestUtils(25-88)
integration/tests/waitlist-mode.test.ts (1)
integration/presets/index.ts (1)
appConfigs(14-30)
packages/shared/src/types/state.ts (1)
packages/shared/src/types/waitlist.ts (1)
WaitlistResource(4-24)
packages/react/src/stateProxy.ts (2)
packages/shared/src/types/state.ts (1)
WaitlistErrors(126-126)packages/shared/src/types/waitlist.ts (1)
WaitlistResource(4-24)
integration/testUtils/index.ts (1)
integration/testUtils/waitlistService.ts (1)
createWaitlistService(7-19)
packages/react/src/hooks/useClerkSignal.ts (2)
packages/shared/src/types/state.ts (1)
WaitlistSignalValue(173-186)packages/react/src/hooks/index.ts (1)
useWaitlist(3-3)
packages/clerk-js/src/core/signals.ts (2)
packages/clerk-js/src/core/resources/Waitlist.ts (1)
Waitlist(9-49)packages/shared/src/types/state.ts (2)
WaitlistSignal(190-192)WaitlistErrors(126-126)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (28)
- GitHub Check: Integration Tests (quickstart, chrome, 16)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (nextjs, chrome, 16)
- GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
- GitHub Check: Integration Tests (machine, chrome, RQ)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (quickstart, chrome, 15)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (billing, chrome, RQ)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (handshake, chrome)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (handshake:staging, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Build Packages
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (17)
integration/presets/envs.ts (1)
130-134: LGTM! Typo fix in environment preset naming.The rename from
withWaitlistdModetowithWaitlistModecorrectly fixes the typo throughout the file (variable name, ID, and export). This aligns with the corrected reference in integration/tests/waitlist-mode.test.ts.integration/testUtils/waitlistService.ts (1)
3-5: LGTM! Clean type definition.The
WaitlistServicetype is well-defined with a clear, single-responsibility method signature.integration/testUtils/index.ts (1)
11-11: LGTM! Waitlist service properly integrated.The
createWaitlistServiceimport and integration follows the established pattern for other test services (email, users, invitations, organizations), maintaining consistency with the existing codebase structure.Also applies to: 44-44
integration/tests/waitlist-mode.test.ts (1)
81-81: LGTM! Environment key corrected.The update from
withWaitlistdModetowithWaitlistModecorrectly aligns with the typo fix in integration/presets/envs.ts, ensuring the test uses the proper environment configuration.integration/templates/custom-flows-react-vite/src/main.tsx (1)
10-10: LGTM! Waitlist route properly added.The new Waitlist import and route follow the established pattern for other routes in this file (SignIn, SignUp, Protected). The route structure is consistent with React Router best practices.
Also applies to: 47-50
packages/react/src/hooks/index.ts (1)
3-3: LGTM! useWaitlist hook properly exported.The addition of
useWaitlistto the public API export follows the established pattern, grouping it appropriately with the relateduseSignInanduseSignUphooks. This maintains consistency with the existing signal-based hooks architecture.integration/tests/custom-flows/waitlist.test.ts (1)
44-95: Waitlist integration tests cover happy-path, validation, and loading stateThe three scenarios (successful join, invalid email error, and loading-state assertion) exercise the new waitlist flow end‑to‑end, including UI wiring and backend cleanup via
waitlist.clearWaitlistByEmail. Looks good.packages/shared/src/types/waitlist.ts (1)
1-28: Waitlist type surface looks consistent and well-typedReadonly fields and the
join(params: JoinWaitlistParams) => Promise<{ error: ClerkError | null }>signature align with the core resource and signal usage; JSDoc clearly documents unset states (''/null). No issues from a typing/API standpoint.packages/shared/src/types/state.ts (1)
103-232: Waitlist signal and error types are consistent with the resource and hooksThe new
WaitlistFields,WaitlistErrors,WaitlistSignalValue, andState.waitlistSignal/__internal_waitlistdeclarations mirror the existing signIn/signUp patterns and match the WaitlistResource surface. No changes needed here.packages/react/src/stateProxy.ts (2)
43-50: Waitlist proxy wiring is consistent with existing signIn/signUp proxies
defaultWaitlistErrorsandbuildWaitlistProxyfollow the established pattern: default error shape,gatePropertyfor fields, andgateMethodforjoin/reloadagainst__internal_waitlist. With core state keeping__internal_waitlistup to date, this should behave as expected.
371-377: State getter throwing when Clerk state is not ready is appropriateThe new
stategetter defensively throws when__internal_stateis unset, which matches howclientandcheckoutare guarded and avoids subtle null access bugs in the waitlist proxy.packages/react/src/hooks/useClerkSignal.ts (1)
106-121:useWaitlistpublic hook is well-documented and matches the signal typeThe new
useWaitlisthook mirrorsuseSignIn/useSignUpboth in implementation and JSDoc, returning{ waitlist, errors, fetchStatus }as expected from the waitlist signal. No issues here.packages/clerk-js/src/core/state.ts (1)
36-40: Waitlist signals added to State align with signIn/signUp patternsThe new
waitlistResourceSignal,waitlistErrorSignal,waitlistFetchSignal, andwaitlistSignalfields follow the same structure as the existing signIn/signUp signals and plug cleanly into the eventBus handlers. Aside from syncing_waitlistInstanceas noted separately, the signal wiring itself looks good.packages/clerk-js/src/core/signals.ts (4)
3-11: LGTM: Import additions follow established patterns.The new type imports for
WaitlistErrorsandWaitlistSignalfrom@clerk/shared/types, along with theWaitlistresource type, correctly mirror the existing structure for SignIn and SignUp features.Also applies to: 17-17
47-49: LGTM: Signal declarations are correctly structured.The three waitlist signals (
waitlistResourceSignal,waitlistErrorSignal,waitlistFetchSignal) correctly follow the established pattern used for SignIn and SignUp signals, with proper typing and initialization.
138-142: LGTM: Error transformation follows established pattern.The
errorsToWaitlistErrorsfunction correctly implements the error transformation pattern used byerrorsToSignInErrorsanderrorsToSignUpErrors. The use ofemailAddressas the only field is appropriate for waitlist functionality.
51-59: Clarify return pattern inconsistency:waitlistComputedSignaldiffers fromsignInComputedSignalandsignUpComputedSignal.The
waitlistComputedSignalreturns the rawwaitlistresource (Line 58), whilesignInComputedSignal(Line 30) andsignUpComputedSignal(Line 44) returnresource.__internal_future. However, the Waitlist class does not implement__internal_futureor a correspondingWaitlistFutureclass—these exist only for SignIn and SignUp.This pattern difference appears intentional given Waitlist's simpler structure (basic properties and a single async method), but confirm whether this inconsistency is deliberate or if Waitlist should follow the same reactive pattern as SignIn/SignUp.
| const publishableKey = appConfigs.envs.withWaitlistMode.publicVariables.get('CLERK_PUBLISHABLE_KEY'); | ||
| const secretKey = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_SECRET_KEY'); | ||
| const apiUrl = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_API_URL'); | ||
| const { frontendApi: frontendApiUrl } = parsePublishableKey(publishableKey); | ||
|
|
There was a problem hiding this comment.
Handle possibly null from parsePublishableKey before destructuring
parsePublishableKey can return null, so destructuring directly into { frontendApi: frontendApiUrl } is unsafe and will fail TypeScript checks.
Consider guarding or asserting non-null first, e.g.:
- const publishableKey = appConfigs.envs.withWaitlistMode.publicVariables.get('CLERK_PUBLISHABLE_KEY');
- const secretKey = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_SECRET_KEY');
- const apiUrl = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_API_URL');
- const { frontendApi: frontendApiUrl } = parsePublishableKey(publishableKey);
+ const publishableKey = appConfigs.envs.withWaitlistMode.publicVariables.get('CLERK_PUBLISHABLE_KEY');
+ const secretKey = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_SECRET_KEY');
+ const apiUrl = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_API_URL');
+
+ const parsedKey = parsePublishableKey(publishableKey, { fatal: true });
+ if (!parsedKey) {
+ throw new Error('Invalid CLERK_PUBLISHABLE_KEY for withWaitlistMode test environment');
+ }
+ const { frontendApi: frontendApiUrl } = parsedKey;This satisfies TS and avoids a potential runtime destructuring of null.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In integration/tests/custom-flows/waitlist.test.ts around lines 21 to 25, the
call to parsePublishableKey may return null so directly destructuring into {
frontendApi: frontendApiUrl } is unsafe; update the code to first assign the
result to a variable, check that it is not null (or throw a clear error/assert)
and only then extract frontendApi into frontendApiUrl (or handle the null case
explicitly), ensuring TypeScript and runtime safety.
| export const createWaitlistService = (clerkClient: ClerkClient) => { | ||
| const self: WaitlistService = { | ||
| clearWaitlistByEmail: async (email: string) => { | ||
| const { data: entries } = await clerkClient.waitlistEntries.list({ query: email, status: 'pending' }); | ||
|
|
||
| if (entries.length > 0) { | ||
| await clerkClient.waitlistEntries.delete(entries[0].id); | ||
| } | ||
| }, | ||
| }; | ||
|
|
||
| return self; | ||
| }; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for patterns where waitlist entries are created or cleared
rg -n -C3 --type=ts 'clearWaitlistByEmail|waitlist.*create|waitlist.*join' integration/Repository: clerk/javascript
Length of output: 3765
🏁 Script executed:
# Also check the WaitlistService interface definition
rg -n 'interface WaitlistService|type WaitlistService' --type=tsRepository: clerk/javascript
Length of output: 134
🏁 Script executed:
# Check if there are any scenarios with multiple entries per email
rg -n 'waitlistEntries.*list' --type=ts -A5 -B5Repository: clerk/javascript
Length of output: 1577
🏁 Script executed:
# Check JSDoc patterns in other testUtils services
rg -n '/\*\*' integration/testUtils/ -A5 -B1 --type=tsRepository: clerk/javascript
Length of output: 4789
🏁 Script executed:
# Check if there are other scenarios where the same email might create multiple entries
rg -n 'fakeEmail|fakeUser.email' integration/tests/custom-flows/waitlist.test.ts -B5 -A5Repository: clerk/javascript
Length of output: 1853
Add JSDoc documentation to the public WaitlistService API.
Per the project's TypeScript guidelines, public APIs require JSDoc comments. The createWaitlistService function and clearWaitlistByEmail method should include JSDoc blocks documenting their purpose, parameters, and return types:
+/**
+ * Creates a waitlist service for managing test waitlist entries.
+ * @param clerkClient - The Clerk client instance
+ * @returns A service for clearing waitlist entries by email
+ */
export const createWaitlistService = (clerkClient: ClerkClient) => {
const self: WaitlistService = {
+ /**
+ * Clears a pending waitlist entry by email address.
+ * @param email - The email address to clear from the waitlist
+ */
clearWaitlistByEmail: async (email: string) => {🤖 Prompt for AI Agents
In integration/testUtils/waitlistService.ts around lines 7 to 19, the public API
lacks JSDoc comments; add JSDoc above the exported createWaitlistService
function describing its purpose (creates a WaitlistService helper for tests),
document the clerkClient parameter and its type (ClerkClient), and the return
type (WaitlistService), and add a JSDoc block above the clearWaitlistByEmail
method describing what it does, its email parameter (string) and that it returns
a Promise<void>; ensure descriptions are concise and follow the project's JSDoc
style.
Ensures __internal_waitlist and proxies reflect the latest waitlist state by updating _waitlistInstance before emitting the signal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Each test now generates its own unique email to prevent race conditions when tests run in parallel. Emails are collected and cleaned up in afterAll. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @integration/tests/custom-flows/waitlist.test.ts:
- Line 24: Destructuring frontendApiUrl from parsePublishableKey(publishableKey)
is unsafe because parsePublishableKey can return null; update the call to either
pass { fatal: true } into parsePublishableKey so it throws a clear error on
invalid keys (e.g., parsePublishableKey(publishableKey, { fatal: true })) or
first assign the result to a variable and guard for null before destructuring
(e.g., const res = parsePublishableKey(publishableKey); if (!res) throw new
Error('invalid publishableKey'); const { frontendApi: frontendApiUrl } = res),
referencing parsePublishableKey, publishableKey, and frontendApiUrl.
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
integration/tests/custom-flows/waitlist.test.ts
🧰 Additional context used
📓 Path-based instructions (11)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
All code must pass ESLint checks with the project's configuration
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{js,jsx,ts,tsx,json,md,yml,yaml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Follow established naming conventions (PascalCase for components, camelCase for variables)
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{test,spec}.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{test,spec}.{ts,tsx,js,jsx}: Unit tests are required for all new functionality
Verify proper error handling and edge cases
Include tests for all new features
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.ts?(x)
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{test,spec,e2e}.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use real Clerk instances for integration tests
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/typescript.mdc)
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Implement type guards forunknowntypes using the patternfunction isType(value: unknown): value is Type
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details in classes
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Use mixins for shared behavior across unrelated classes in TypeScript
Use generic constraints with bounded type parameters like<T extends { id: string }>
Use utility types likeOmit,Partial, andPickfor data transformation instead of manual type construction
Use discriminated unions instead of boolean flags for state management and API responses
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation at the type level
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Document functions with JSDoc comments including @param, @returns, @throws, and @example tags
Create custom error classes that extend Error for specific error types
Use the Result pattern for error handling instead of throwing exceptions
Use optional chaining (?.) and nullish coalescing (??) operators for safe property access
Let TypeScript infer obvious types to reduce verbosity
Useconst assertionswithas constfor literal types
Usesatisfiesoperator for type checking without widening types
Declare readonly arrays and objects for immutable data structures
Use spread operator and array spread for immutable updates instead of mutations
Use lazy loading for large types...
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use React Testing Library for component testing
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use ESLint with custom configurations tailored for different package types
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*.{js,ts,jsx,tsx,json,md,yml,yaml}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use Prettier for code formatting across all packages
Files:
integration/tests/custom-flows/waitlist.test.ts
**/*
⚙️ CodeRabbit configuration file
If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.
**/*: Only comment on issues that would block merging, ignore minor or stylistic concerns.
Restrict feedback to errors, security risks, or functionality-breaking problems.
Do not post comments on code style, formatting, or non-critical improvements.
Keep reviews short: flag only issues that make the PR unsafe to merge.
Group similar issues into a single comment instead of posting multiple notes.
Skip repetition: if a pattern repeats, mention it once at a summary level only.
Do not add general suggestions, focus strictly on merge-blocking concerns.
If there are no critical problems, respond with minimal approval (e.g., 'Looks good'). Do not add additional review.
Avoid line-by-line commentary unless it highlights a critical bug or security hole.
Highlight only issues that could cause runtime errors, data loss, or severe maintainability issues.
Ignore minor optimization opportunities, focus solely on correctness and safety.
Provide a top-level summary of critical blockers rather than detailed per-line notes.
Comment only when the issue must be resolved before merge, otherwise remain silent.
When in doubt, err on the side of fewer comments, brevity and blocking issues only.
Avoid posting any refactoring issues.
Files:
integration/tests/custom-flows/waitlist.test.ts
🧬 Code graph analysis (1)
integration/tests/custom-flows/waitlist.test.ts (4)
integration/models/application.ts (1)
Application(10-10)integration/presets/index.ts (1)
appConfigs(14-30)packages/shared/src/keys.ts (1)
parsePublishableKey(87-136)integration/testUtils/index.ts (1)
createTestUtils(25-88)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (29)
- GitHub Check: Unit Tests (shared, clerk-js, RQ)
- GitHub Check: Unit Tests (**)
- GitHub Check: Publish with pkg-pr-new
- GitHub Check: Static analysis
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Integration Tests (quickstart, chrome, 15)
- GitHub Check: Integration Tests (handshake, chrome)
- GitHub Check: Integration Tests (quickstart, chrome, 16)
- GitHub Check: Integration Tests (nextjs, chrome, 16)
- GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
- GitHub Check: Integration Tests (machine, chrome, RQ)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (billing, chrome, RQ)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (handshake:staging, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
| const publishableKey = appConfigs.envs.withWaitlistMode.publicVariables.get('CLERK_PUBLISHABLE_KEY'); | ||
| const secretKey = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_SECRET_KEY'); | ||
| const apiUrl = appConfigs.envs.withWaitlistMode.privateVariables.get('CLERK_API_URL'); | ||
| const { frontendApi: frontendApiUrl } = parsePublishableKey(publishableKey); |
There was a problem hiding this comment.
Destructuring from potentially null return value will cause runtime TypeError
parsePublishableKey can return null (see its signature in @clerk/shared/keys). Destructuring directly without a null check will throw at runtime if the key is invalid or missing.
Use { fatal: true } to throw a descriptive error, or add a null guard:
- const { frontendApi: frontendApiUrl } = parsePublishableKey(publishableKey);
+ const parsedKey = parsePublishableKey(publishableKey, { fatal: true });
+ const { frontendApi: frontendApiUrl } = parsedKey;Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In @integration/tests/custom-flows/waitlist.test.ts at line 24, Destructuring
frontendApiUrl from parsePublishableKey(publishableKey) is unsafe because
parsePublishableKey can return null; update the call to either pass { fatal:
true } into parsePublishableKey so it throws a clear error on invalid keys
(e.g., parsePublishableKey(publishableKey, { fatal: true })) or first assign the
result to a variable and guard for null before destructuring (e.g., const res =
parsePublishableKey(publishableKey); if (!res) throw new Error('invalid
publishableKey'); const { frontendApi: frontendApiUrl } = res), referencing
parsePublishableKey, publishableKey, and frontendApiUrl.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.changeset/young-areas-divide.md (1)
7-7: Consider expanding the changeset description for clarity.The description "Introduce
useWaitlist()hook" is functional but minimal. Given the scope of changes (new Waitlist resource, signals integration, State class enhancements), consumers might benefit from a slightly more detailed changelog entry. Consider something like: "IntroduceuseWaitlist()hook for reactive waitlist state management in React applications" or similar.
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.changeset/young-areas-divide.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (29)
- GitHub Check: Unit Tests (shared, clerk-js, RQ)
- GitHub Check: Publish with pkg-pr-new
- GitHub Check: Unit Tests (**)
- GitHub Check: Static analysis
- GitHub Check: Integration Tests (handshake:staging, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 16)
- GitHub Check: Integration Tests (quickstart, chrome, 15)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (quickstart, chrome, 16)
- GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (machine, chrome, RQ)
- GitHub Check: Integration Tests (billing, chrome, RQ)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (handshake, chrome)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
Description
This PR introduces the
useWaitlist()hook, a new signal-backed hook in@clerk/reactthat enables developers to build custom waitlist UIs with reactive state management. It follows the pattern ofuseSignIn()anduseSignUp(), exposingwaitlist(resource),errors, andfetchStatus.The
Waitlistresource in@clerk/clerk-jshas been integrated with the signal system, providing aWaitlistFutureinstance for reactive updates. TheStateclass now manages a lazily initialized, singletonWaitlistinstance, ensuring its independence from theClientresource and proper signal propagation.An integration test has been added to validate the hook's functionality, including joining the waitlist, error handling, and loading states.
To test the changes, run the new integration test:
pnpm playwright test integration/tests/custom-flows/waitlist.test.tsChecklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
New Features
useWaitlist()hook for React components to manage waitlist state and actions/waitlistroute in the custom flows template with error handling and loading statesBug Fixes
Tests
Chores
✏️ Tip: You can customize this high-level summary in your review settings.