From 4e964fa233a6189ed9ece670d37b52f61d768914 Mon Sep 17 00:00:00 2001 From: LekoArts Date: Wed, 4 Sep 2024 09:38:49 +0200 Subject: [PATCH 1/6] add jsdocs comments --- packages/react/src/types.ts | 17 ++++++++-- packages/types/src/clerk.ts | 55 +++++++++++++++++++++++++++++-- packages/types/src/multiDomain.ts | 9 ++--- 3 files changed, 72 insertions(+), 9 deletions(-) diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts index 25b1fbd671f..66397efaf26 100644 --- a/packages/react/src/types.ts +++ b/packages/react/src/types.ts @@ -7,7 +7,6 @@ import type { LoadedClerk, MultiDomainAndOrProxy, RedirectUrlProp, - SDKMetadata, SignInProps, SignInRedirectOptions, SignUpProps, @@ -26,11 +25,25 @@ declare global { export type IsomorphicClerkOptions = Without & { Clerk?: ClerkProp; + /** + * Define the URL that `@clerk/clerk-js` should be hot-loaded from + */ clerkJSUrl?: string; + /** + * If your web application only uses Control components, you can set this value to `'headless'` and load a minimal ClerkJS bundle for optimal page performance. + */ clerkJSVariant?: 'headless' | ''; + /** + * Define the npm version for `@clerk/clerk-js` + */ clerkJSVersion?: string; - sdkMetadata?: SDKMetadata; + /** + * The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + */ publishableKey: string; + /** + * This nonce value will be passed through to the `@clerk/clerk-js` script tag. You can use this to implement [strict-dynamic CSP](https://clerk.com/docs/security/clerk-csp#implementing-a-strict-dynamic-csp). + */ nonce?: string; } & MultiDomainAndOrProxy; diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts index a5bb23b5c22..57e8f31bda1 100644 --- a/packages/types/src/clerk.ts +++ b/packages/types/src/clerk.ts @@ -40,9 +40,22 @@ import type { Web3Strategy } from './strategies'; import type { UserResource } from './user'; import type { Autocomplete, DeepPartial, DeepSnakeToCamel } from './utils'; +/** + * Contains information about the SDK that the host application is using. + * For example, if Clerk is loaded through `@clerk/nextjs`, this would be `{ name: '@clerk/nextjs', version: '1.0.0' }` + */ export type SDKMetadata = { + /** + * The npm package name of the SDK + */ name: string; + /** + * The npm package version of the SDK + */ version: string; + /** + * Typically this will be the NODE_ENV that the SDK is currently running in + */ environment?: string; }; @@ -608,12 +621,24 @@ export type ClerkThemeOptions = DeepSnakeToCamel>; */ type ClerkOptionsNavigation = | { + /** + * A function which takes the destination path as an argument and performs a "push" navigation. + */ routerPush?: never; - routerDebug?: boolean; + /** + * A function which takes the destination path as an argument and performs a "replace" navigation. + */ routerReplace?: never; + routerDebug?: boolean; } | { + /** + * A function which takes the destination path as an argument and performs a "push" navigation. + */ routerPush: RouterFn; + /** + * A function which takes the destination path as an argument and performs a "replace" navigation. + */ routerReplace: RouterFn; routerDebug?: boolean; }; @@ -626,29 +651,53 @@ export type ClerkOptions = ClerkOptionsNavigation & LegacyRedirectProps & AfterSignOutUrl & AfterMultiSessionSingleSignOutUrl & { + /** + * Optional object to style your components. Will only affect [Clerk Components](https://clerk.com/docs/components/overview) and not [Account Portal](https://clerk.com/docs/customization/account-portal/overview) pages. + */ appearance?: Appearance; + /** + * Optional object to localize your components. Will only affect [Clerk Components](https://clerk.com/docs/components/overview) and not [Account Portal](https://clerk.com/docs/customization/account-portal/overview) pages. + */ localization?: LocalizationResource; polling?: boolean; selectInitialSession?: (client: ClientResource) => ActiveSessionResource | null; /** Controls if ClerkJS will load with the standard browser setup using Clerk cookies */ standardBrowser?: boolean; - /** Optional support email for display in authentication screens */ + /** + * Optional support email for display in authentication screens. Will only affect [Clerk Components](https://clerk.com/docs/components/overview) and not [Account Portal](https://clerk.com/docs/customization/account-portal/overview) pages. + */ supportEmail?: string; touchSession?: boolean; + /** + * This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances. + */ signInUrl?: string; + /**This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances */ signUpUrl?: string; + /** + * Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. + */ allowedRedirectOrigins?: Array; + /** + * This option defines that the application is a satellite application. + */ isSatellite?: boolean | ((url: URL) => boolean); /** - * Telemetry options + * Controls whether or not Clerk will collect [telemetry data](https://clerk.com/docs/telemetry) */ telemetry?: | false | { disabled?: boolean; + /** + * Telemetry events are only logged to the console and not sent to Clerk + */ debug?: boolean; }; + /** + * Contains information about the SDK that the host application is using. You don't need to set this value yourself unless you're [developing an SDK](https://clerk.com/docs/references/sdk/overview). + */ sdkMetadata?: SDKMetadata; /** diff --git a/packages/types/src/multiDomain.ts b/packages/types/src/multiDomain.ts index a03685d9bbe..88c5f1a474d 100644 --- a/packages/types/src/multiDomain.ts +++ b/packages/types/src/multiDomain.ts @@ -3,11 +3,12 @@ import type { ClerkOptions } from './clerk'; type StringOrURLFnToString = string | ((url: URL) => string); /** - * DomainOrProxyUrl supports the following cases + * You can configure proxy and satellite domains in a few ways: + * * 1) none of them are set - * 2) only proxyUrl is set - * 3) isSatellite and proxy is set - * 4) isSatellite and domain is set + * 2) only `proxyUrl` is set + * 3) `isSatellite` and `proxyUrl` are set + * 4) `isSatellite` and `domain` are set */ export type MultiDomainAndOrProxy = | { From 477ce29c891d6414e548f033a3474b5abb6cc5d0 Mon Sep 17 00:00:00 2001 From: LekoArts Date: Wed, 4 Sep 2024 09:44:36 +0200 Subject: [PATCH 2/6] add changeset --- .changeset/few-schools-invent.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/few-schools-invent.md diff --git a/.changeset/few-schools-invent.md b/.changeset/few-schools-invent.md new file mode 100644 index 00000000000..10757a713b4 --- /dev/null +++ b/.changeset/few-schools-invent.md @@ -0,0 +1,6 @@ +--- +"@clerk/clerk-react": patch +"@clerk/types": patch +--- + +Add JSDoc comments to ClerkProvider properties From ac4555f5a5aaf81474be2620fcbcd1741ec3d816 Mon Sep 17 00:00:00 2001 From: Lennart Date: Wed, 4 Sep 2024 09:45:45 +0200 Subject: [PATCH 3/6] Update few-schools-invent.md --- .changeset/few-schools-invent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/few-schools-invent.md b/.changeset/few-schools-invent.md index 10757a713b4..bcb0aa25cb3 100644 --- a/.changeset/few-schools-invent.md +++ b/.changeset/few-schools-invent.md @@ -3,4 +3,4 @@ "@clerk/types": patch --- -Add JSDoc comments to ClerkProvider properties +Improve JSDoc comments coverage on `` properties From 87bfe24d96c2269457219976af984c9fa29f114b Mon Sep 17 00:00:00 2001 From: LekoArts Date: Wed, 4 Sep 2024 11:14:46 +0200 Subject: [PATCH 4/6] correction --- packages/types/src/clerk.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts index 57e8f31bda1..f5ea037ff8a 100644 --- a/packages/types/src/clerk.ts +++ b/packages/types/src/clerk.ts @@ -669,10 +669,10 @@ export type ClerkOptions = ClerkOptionsNavigation & supportEmail?: string; touchSession?: boolean; /** - * This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances. + * This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It's required for development instances if you a use satellite application. */ signInUrl?: string; - /**This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances */ + /**This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances. */ signUpUrl?: string; /** * Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. From fea3f8198a5064387f78d31f0af45354c945d3c6 Mon Sep 17 00:00:00 2001 From: Lennart Date: Wed, 4 Sep 2024 12:24:29 +0200 Subject: [PATCH 5/6] Update packages/types/src/clerk.ts Co-authored-by: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> --- packages/types/src/clerk.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts index f5ea037ff8a..d0696ebc3d2 100644 --- a/packages/types/src/clerk.ts +++ b/packages/types/src/clerk.ts @@ -672,7 +672,7 @@ export type ClerkOptions = ClerkOptionsNavigation & * This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It's required for development instances if you a use satellite application. */ signInUrl?: string; - /**This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances. */ + /** This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances and required for development instances. */ signUpUrl?: string; /** * Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console. From 41fc4ddbf287ae93786c1e51394f3a92845ee7ec Mon Sep 17 00:00:00 2001 From: LekoArts Date: Wed, 4 Sep 2024 14:20:20 +0200 Subject: [PATCH 6/6] use note tag --- packages/react/src/types.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts index 66397efaf26..63b92c48d90 100644 --- a/packages/react/src/types.ts +++ b/packages/react/src/types.ts @@ -38,11 +38,13 @@ export type IsomorphicClerkOptions = Without & { */ clerkJSVersion?: string; /** - * The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page. + * The Clerk publishable key for your instance + * @note This can be found in your Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page */ publishableKey: string; /** - * This nonce value will be passed through to the `@clerk/clerk-js` script tag. You can use this to implement [strict-dynamic CSP](https://clerk.com/docs/security/clerk-csp#implementing-a-strict-dynamic-csp). + * This nonce value will be passed through to the `@clerk/clerk-js` script tag. + * @note You can use this to implement [strict-dynamic CSP](https://clerk.com/docs/security/clerk-csp#implementing-a-strict-dynamic-csp) */ nonce?: string; } & MultiDomainAndOrProxy;