feat(vue): Introduce Vue SDK by wobsoriano · Pull Request #4461 · clerk/javascript

wobsoriano · 2024-11-02T02:14:10Z

Description

This PR introduces an experimental version of Vue SDK! It ports the original code of vue-clerk inside this monorepo as a new package called @clerk/vue.

These are the adjustments that happened while porting the original code:

Removed IsomorphicClerk as it's hard to keep in sync with @clerk/clerk-react's IsomorphicClerk and there's really no benefit of it in Vue.
Custom pages and menu items have been intentionally excluded from this PR to focus on the main components and functions. These features will be implemented in a separate PR to follow.
Added unit tests to unstyled components using Vitest
Dropped CJS support (nobody's using cjs in Vue since Vue 3)

Things to keep in mind when reviewing this PR:

All components (UI, Control, Unstyled) are using Render Functions - this allow us to use pure JavaScript to create Vue components. Another plus is that we dont have to create a separate .vue file for each component and keep all related components in the same file.
When you see the term "composables", it's like "hooks" in React for Vue.
All components and hooks from @clerk/clerk-react have an equivalent in @clerk/vue. They all use the same name.

We will introduce E2E tests and quickstart repo in a separate PR.

Resolves ECO-222

Checklist

npm test runs as expected.
npm run build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2024-11-02T02:14:13Z

🦋 Changeset detected

Latest commit: b443c40

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/vue	Patch

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

wobsoriano · 2024-11-04T22:07:03Z

This file contains all Clerk Control components that is a 1:1 equivalent of the React control components. They can be used like this

<script setup> import { SignedIn } from '@clerk/vue' </script> <template> <SignedIn>You are signed in</SignedIn> </template>

wobsoriano · 2024-11-04T22:09:44Z

This file contains all Clerk UI components that is a 1:1 equivalent of the React UI components. They can be used like this:

<script setup> import { UserProfile } from '@clerk/vue' </script> <template> <UserProfile /> </template>

wobsoriano · 2024-11-04T22:18:11Z

+      autoPropsPlugin({
+        include: ['**/*.ts'],
+      }) as EsbuildPlugin,


Instead of redeclaring all props for all of available components, this plugin will generate a runtime prop using the type prop.

So this component:

will turn into this when built:

So without this plugin, we will have to manually add runtime props to each component, and make sure they will always match.

wobsoriano · 2024-11-04T22:32:36Z

+
+import type { VueClerkInjectionKeyType } from './types';
+
+export const ClerkInjectionKey = Symbol('clerk') as InjectionKey<VueClerkInjectionKeyType>;


Read more here regarding Symbols as key

chore(vue): add initial setup, components and composables chore(vue): Update build config to add runtime props chore(vue): Add license and initial README chore(vue): Fix incorrect mounting chore(vue): Make sure Clerk is loaded for useAuth functions chore(vue): Fix imports chore(vue): add basic JSDoc chore(vue): add JSDoc to composables chore(vue): Add unstyled buttons chore(vue): Add reusable button handler for unstyled components chore(vue): Prevent hydration errors on UI component mount chore(vue): Improve clerk ref reactivity chore(vue): Add changeset test(vue): Add unstyled components unit tests chore(vue): Move auto prop generator to dev deps test(vue): Test sign out button props test(vue): Assert single child for unstyled components chore(vue): Use built-in error thrower for errors chore(vue): Add AuthenticateWithMetamaskButton unstyled component chore(vue): Add autoprops plugin comment chore(vue): Simplify autoprops comment chore(vue): Simplify autoprops comment chore(vue): use named export for user-event chore(vue): sync dependencies chore(vue): make unstyled component reusable functions close to react test(vue): Switch to vitest for unit tests chore(vue): consistent render functions ci(vue): Add vue test in workflow fix(vue): Try and fix rspack error fix(vue): Export conditions chore(vue): Drop cjs variant chore(vue): Use built-in in-browser function chore(vue): Throw an error on clerk-js load fail chore(vue): Move injection key to a separate file chore(vue): Reinstall deps chore(vue): Use Symbol as injection key chore(vue): type fixes chore(vue): Format composable JSDocs

octoper · 2024-11-06T15:46:26Z

+    h(Portal, {
+      mount: clerk.value?.mountUserProfile,
+      unmount: clerk.value?.unmountUserProfile,
+      updateProps: (clerk.value as any)?.__unstable__updateProps,


❓ Why are we using as any here?

__unstable__updateProps is an internal unstable property and we didn't add types yet, just like what we have in the React SDK

javascript/packages/react/src/components/uiComponents.tsx

Line 223 in b064f52

updateProps={(clerk as any).__unstable__updateProps}

brkalow · 2024-11-06T16:28:45Z

+    const hasActiveSessions = clientCtx.value?.activeSessions && clientCtx.value.activeSessions.length > 0;
+
+    if (sessionCtx.value === null && hasActiveSessions) {
+      void clerk.value.redirectToAfterSignOut();
+    } else {
+      void clerk.value.redirectToSignIn(props);
+    }


this seems like a good candidate to abstract into clerk-js 👀

Added a ticket that will address shared types and this 🫡

brkalow · 2024-11-06T16:33:31Z

+  watchEffect(() => {
+    if (!clerk.value) {
+      return;
+    }


Seeing lots of this, potentially something we could abstract. Not sure if this is allowed in vue land:

watchEffectWithClerk(clerk => { void clerk.value.redirectToSignUp(props); });

Good catch. That should be valid in Vue land and should be simpler to write and less boilerplate.

I was also thinking of having something like withClerk HOC:

export const RedirectToSignUp = withClerk( defineComponent(({ clerk, ...props }: WithClerkProp<SignUpRedirectOptions>) => { onMounted(() => { void props.clerk.redirectToSignUp(props); }); return () => null; }), )

this gives the same mental model as what we have in the React SDK but requires slightly more setup code 🤔

Yeah, watchEffectWithClerk is growing on me. Let's do it, less boilerplate 🫡

function onClerkLoaded(callback) { const clerk = useClerk(); watchEffect(() => { if (!clerk.value?.loaded) { return } callback(clerk.value) }) }

brkalow · 2024-11-06T16:48:48Z

+export type ProtectProps =
+  | {
+      condition?: never;
+      role: OrganizationCustomRoleKey;
+      permission?: never;
+    }
+  | {
+      condition?: never;
+      role?: never;
+      permission: OrganizationCustomPermissionKey;
+    }
+  | {
+      condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
+      role?: never;
+      permission?: never;
+    }
+  | {
+      condition?: never;
+      role?: never;
+      permission?: never;
+    };


Do we hae a shared type for this? Can we make it shared?

Replied here. Astro will benefit from it too.

brkalow · 2024-11-06T17:06:28Z

+  };
+}
+
+type UseAuthReturn =


This should be moved to a shared type so they don't drift

brkalow · 2024-11-06T17:31:10Z

+ *   </div>
+ * </template>
+ */
+export const useAuth: UseAuth = () => {


more candidates for shared helpers here to avoid drift 👀

brkalow · 2024-11-06T17:46:10Z

+import type { ToComputedRefs } from './utils';
+import { toComputedRefs } from './utils';
+
+type UseOrganizationReturn =


I think it's important we move these hook return types to some shared spot so we ensure consistent interfaces across our SDKs. It doesn't necessarily need to be done as part of this project, but something we should try and tackle soon 👍

Regarding the type suggestions, I agree and let's do it in a separate ticket. I can help with this after completing the Vue project 🫡. The Astro project will also benefit from these shared types.

Co-authored-by: Bryce Kalow <bryce@clerk.dev>

…aded

wobsoriano · 2024-11-06T20:53:19Z

+export const useClerkLoaded = (callback: (clerk: LoadedClerk) => void) => {
+  const clerk = useClerk();
+
+  watch(
+    clerk,
+    unwrappedClerk => {
+      if (!unwrappedClerk?.loaded) {
+        return;
+      }
+
+      callback(unwrappedClerk as LoadedClerk);
+    },
+    { immediate: true },
+  );
+};


This composable is used inside the control components where we want to execute a Clerk method when Clerk is loaded.

We're using a watch here instead of watchEffect to react to a specific state, instead of watching every reactivate state inside the callback

LekoArts · 2024-11-07T13:23:25Z

+import { useClerkContext } from '../composables/useClerkContext';
+import { useClerkLoaded } from '../utils/useClerkLoaded';
+
+export const SignedIn = defineComponent((_, { slots }) => {


Would users benefit from us adding JSDoc comments to these exports or wouldn't it be shown in ones IDE?

Good question! So the doc shows up in the import statement:

but not when used inside template:

I skipped it because of that but we can definitely add it 🤔

Why would it only show up on the import? I guess typically you'd expect this to exist during usage

Okay, looks like it is a limitation when using render functions. When doing normal Vue SFC, it appears when used inside template:

Let's tackle this in a separate ticket 🫡

LekoArts · 2024-11-07T13:33:39Z

+ * low-level access to Clerk's functionality, enabling custom authentication UI and flows.
+ *
+ * @example
+ * A simple example:


We can remove the "A simple example" from the @example blocks (also in other files of this PR) because the tag will already mark it as such + the word "simple" should probably be avoided as for some folks it might indeed not be simple (and thus discouraging)

Updated! thank you

LekoArts · 2024-11-07T13:34:26Z

+
+  if (!ctx) {
+    throw new Error(
+      'This component/composable can only be used when the Vue plugin is installed. Learn more: https://clerk.com/docs/components/clerk-provider',


Shouldn't this link to the installation docs of the Clerk Vue SDK instead?

Updated to add a quickstart link to Vue SDK (docs to follow)

anagstef

🚀 Amazing work! 🔥

Co-authored-by: Bryce Kalow <bryce@clerk.dev>

wobsoriano force-pushed the rob/eco-222-port-vue-clerk-to-clerkvue branch from c47245f to bbb3a0d Compare November 2, 2024 02:19

clerk-cookie added the actions label Nov 4, 2024

wobsoriano commented Nov 4, 2024

View reviewed changes

wobsoriano marked this pull request as ready for review November 4, 2024 22:23

wobsoriano requested review from LekoArts, octoper, panteliselef and tmilewski November 4, 2024 22:23

wobsoriano commented Nov 4, 2024

View reviewed changes

octoper approved these changes Nov 4, 2024

View reviewed changes

octoper reviewed Nov 4, 2024

View reviewed changes

Comment thread packages/vue/src/components/uiComponents.ts

wobsoriano requested a review from anagstef November 5, 2024 14:41

wobsoriano force-pushed the rob/eco-222-port-vue-clerk-to-clerkvue branch 4 times, most recently from 7a415dd to edb5a4e Compare November 5, 2024 15:31

wobsoriano added 4 commits November 5, 2024 12:07

chore(vue): Add Waitlist component

783c181

chore(vue): Update Portal props reactivity

67acf89

chore(vue): Remove one tap props reactivity

fead36b

wobsoriano force-pushed the rob/eco-222-port-vue-clerk-to-clerkvue branch from 53879bc to fead36b Compare November 5, 2024 20:08

Merge branch 'main' into rob/eco-222-port-vue-clerk-to-clerkvue

02a7159

octoper reviewed Nov 6, 2024

View reviewed changes

octoper approved these changes Nov 6, 2024

View reviewed changes

brkalow reviewed Nov 6, 2024

View reviewed changes

wobsoriano and others added 2 commits November 6, 2024 10:16

chore: apply suggested edits

99862b5

Co-authored-by: Bryce Kalow <bryce@clerk.dev>

chore: apply suggested edits

3045116

Co-authored-by: Bryce Kalow <bryce@clerk.dev>

wobsoriano added 3 commits November 6, 2024 12:44

chore(vue): Create reusable composable that executes when Clerk is lo…

ba2e3b3

…aded

chore(vue): Add helper JSDoc

dfb8362

chore(vue): Use unwrapped Clerk value inside callback

784af5e

wobsoriano commented Nov 6, 2024

View reviewed changes

wobsoriano added 3 commits November 6, 2024 13:34

chore(vue): Remove unused primitive

6631b8d

Merge branch 'main' into rob/eco-222-port-vue-clerk-to-clerkvue

1b0c199

chore(vue): Fix deps

6f5ca28

LekoArts reviewed Nov 7, 2024

View reviewed changes

anagstef approved these changes Nov 7, 2024

View reviewed changes

jacekradko reviewed Nov 7, 2024

View reviewed changes

Comment thread packages/vue/tsconfig.json Outdated

wobsoriano added 7 commits November 7, 2024 07:44

chore(vue): Remove extra comments in JSDoc

2b7563b

chore(vue): Update error message to link Vue installation docs

d634b5d

Merge branch 'main' into rob/eco-222-port-vue-clerk-to-clerkvue

ec33e8e

chore(vue): Set target to ES2020

306cca1

Merge branch 'main' into rob/eco-222-port-vue-clerk-to-clerkvue

01f492c

chore(vue): Remove dead links in readme

f8f6feb

chore(vue): Update readme imports

b443c40

wobsoriano merged commit fd30c21 into main Nov 8, 2024

wobsoriano deleted the rob/eco-222-port-vue-clerk-to-clerkvue branch November 8, 2024 17:15

clerk-cookie mentioned this pull request Nov 8, 2024

ci(repo): Version packages #4504

Merged

This was referenced Nov 12, 2024

feat(nuxt,vue): Introduce Nuxt SDK #4541

Merged

chore(shared,types,clerk-react,vue): Share hook return types #4583

Merged

wobsoriano mentioned this pull request Nov 25, 2024

feat(vue): Introduce Vue SDK Quickstart clerk/clerk-docs#1709

Merged

3 tasks

wobsoriano added a commit that referenced this pull request Feb 8, 2025

feat(vue): Introduce Vue SDK (#4461)

fe51f87

Co-authored-by: Bryce Kalow <bryce@clerk.dev>


		import type { VueClerkInjectionKeyType } from './types';

		export const ClerkInjectionKey = Symbol('clerk') as InjectionKey<VueClerkInjectionKeyType>;

Uh oh!

Conversation

wobsoriano commented Nov 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Nov 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

wobsoriano Nov 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wobsoriano Nov 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wobsoriano Nov 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wobsoriano Nov 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wobsoriano Nov 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anagstef left a comment

wobsoriano commented Nov 2, 2024 •

edited

Loading

changeset-bot Bot commented Nov 2, 2024 •

edited

Loading

wobsoriano Nov 4, 2024 •

edited

Loading

wobsoriano Nov 4, 2024 •

edited

Loading

wobsoriano Nov 4, 2024 •

edited

Loading

wobsoriano Nov 6, 2024 •

edited

Loading

wobsoriano Nov 8, 2024 •

edited

Loading