diff --git a/docs/_partials/vue-nuxt/composables.mdx b/docs/_partials/vue-nuxt/composables.mdx new file mode 100644 index 0000000000..5b454d6c23 --- /dev/null +++ b/docs/_partials/vue-nuxt/composables.mdx @@ -0,0 +1,8 @@ +- [`useUser()`](/docs/references/vue/use-user) +- [`useClerk()`](/docs/references/vue/use-clerk) +- [`useAuth()`](/docs/references/vue/use-auth) +- [`useSignIn()`](/docs/references/vue/use-sign-in) +- [`useSignUp()`](/docs/references/vue/use-sign-up) +- [`useSession()`](/docs/references/vue/use-session) +- [`useSessionList()`](/docs/references/vue/use-session-list) +- [`useOrganization()`](/docs/references/vue/use-organization) diff --git a/docs/_partials/vue-nuxt/use-auth.mdx b/docs/_partials/vue-nuxt/use-auth.mdx new file mode 100644 index 0000000000..9201766300 --- /dev/null +++ b/docs/_partials/vue-nuxt/use-auth.mdx @@ -0,0 +1,15 @@ +The `useAuth()` composable provides access to the current user's authentication state and methods to manage the active session. You can use this composable to protect [pages](/docs/references/nuxt/protect-pages). + +In the following example, the `isLoaded` property checks if Clerk has finished initializing and the `userId` property checks if the user is signed in. + +```vue {{ filename: 'pages/protected-page.vue' }} + + + +``` diff --git a/docs/index.mdx b/docs/index.mdx index 554829ae3a..0645869ca2 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -84,6 +84,18 @@ Find all the guides and resources you need to develop with Clerk. - [React Router (Beta)](/docs/quickstarts/react-router) - Easily add secure, edge- and SSR-friendly authentication to React Router with Clerk. - {} + + --- + + - [Nuxt](/docs/quickstarts/nuxt) + - Easily add secure, beautiful, and fast authentication to Nuxt with Clerk. + - {} + + --- + + - [Vue](/docs/quickstarts/vue) + - Get started installing and initializing Clerk in a new Vue + Vite app. + - {} ## Explore by backend framework diff --git a/docs/manifest.json b/docs/manifest.json index 2d49a465e3..92fbb2622b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -51,6 +51,11 @@ "tag": "(Beta)", "href": "/docs/quickstarts/tanstack-start", "icon": "tanstack" + }, + { + "title": "Nuxt", + "href": "/docs/quickstarts/nuxt", + "icon": "nuxt" } ] ] @@ -81,7 +86,8 @@ { "title": "Chrome Extension", "href": "/docs/quickstarts/chrome-extension" - } + }, + { "title": "Vue", "href": "/docs/quickstarts/vue", "icon": "vue" } ] ] }, @@ -710,10 +716,6 @@ "title": "Organization workspaces", "href": "/docs/organizations/organization-workspaces" }, - { - "title": "Use organization slugs in URLs", - "href": "/docs/organizations/org-slugs-in-urls" - }, { "title": "Create organizations on behalf of users", "href": "/docs/organizations/create-orgs-for-users" @@ -1829,7 +1831,7 @@ ] }, { - "title": "General References", + "title": "General references", "items": [ [ { @@ -1915,7 +1917,7 @@ "href": "/docs/references/react/overview" }, { - "title": "Client-side Helpers", + "title": "Client-side helpers", "items": [ [ { @@ -2470,7 +2472,7 @@ ] }, { - "title": "General References", + "title": "General references", "items": [ [ { @@ -2631,7 +2633,7 @@ ] }, { - "title": "General Reference", + "title": "General references", "items": [ [ { @@ -2653,7 +2655,7 @@ ] }, { - "title": "Client-side Helpers", + "title": "Client-side helpers", "items": [ [ { @@ -2702,6 +2704,113 @@ ] ] }, + { + "title": "Nuxt", + "collapse": true, + "icon": "nuxt", + "items": [ + [ + { "title": "Overview", "href": "/docs/references/nuxt/overview" }, + { + "title": "Guides", + "items": [ + [ + { + "title": "Read session and user data", + "wrap": false, + "href": "/docs/references/nuxt/read-session-data" + }, + { + "title": "Protect pages", + "wrap": false, + "href": "/docs/references/nuxt/protect-pages" + } + ] + ] + }, + { + "title": "General references", + "items": [ + [ + { + "title": "`clerkMiddleware()`", + "wrap": false, + "href": "/docs/references/nuxt/clerk-middleware" + } + ] + ] + } + ] + ] + }, + { + "title": "Vue", + "collapse": true, + "icon": "vue", + "items": [ + [ + { "title": "Overview", "href": "/docs/references/vue/overview" }, + { + "title": "Guides", + "items": [ + [ + { + "title": "Migrating from community SDK", + "href": "/docs/references/vue/migrating-from-vue-community-sdk" + } + ] + ] + }, + { + "title": "Client-side helpers", + "items": [ + [ + { + "title": "`useUser()`", + "wrap": false, + "href": "/docs/references/vue/use-user" + }, + { + "title": "`useClerk()`", + "wrap": false, + "href": "/docs/references/vue/use-clerk" + }, + { + "title": "`useAuth()`", + "wrap": false, + "href": "/docs/references/vue/use-auth" + }, + { + "title": "`useSignIn()`", + "wrap": false, + "href": "/docs/references/vue/use-sign-in" + }, + { + "title": "`useSignUp`", + "wrap": false, + "href": "/docs/references/vue/use-sign-up" + }, + { + "title": "`useSession()`", + "wrap": false, + "href": "/docs/references/vue/use-session" + }, + { + "title": "`useSessionList()`", + "wrap": false, + "href": "/docs/references/vue/use-session-list" + }, + { + "title": "`useOrganization()`", + "wrap": false, + "href": "/docs/references/vue/use-organization" + } + ] + ] + } + ] + ] + }, { "title": "Ruby / Rails", "collapse": true, diff --git a/docs/manifest.schema.json b/docs/manifest.schema.json index 1909c9e4e3..3773be9eef 100644 --- a/docs/manifest.schema.json +++ b/docs/manifest.schema.json @@ -139,7 +139,8 @@ "user-dotted-circle", "vue", "x", - "expo" + "expo", + "nuxt" ] } } diff --git a/docs/quickstarts/nuxt.mdx b/docs/quickstarts/nuxt.mdx new file mode 100644 index 0000000000..452360020f --- /dev/null +++ b/docs/quickstarts/nuxt.mdx @@ -0,0 +1,162 @@ +--- +title: Nuxt Quickstart +description: Add authentication and user management to your Nuxt app with Clerk. +--- + + + - Install `@clerk/nuxt` + - Set your Clerk API keys + - Configure `nuxt.config.ts` + - Create a header with Clerk components + - Protect your API routes + + + + ## Install `@clerk/nuxt` + + Clerk's [Nuxt SDK](/docs/references/nuxt/overview) gives you access to prebuilt components, Vue composables, and helpers to make user authentication easier. + + Run the following command to install the SDK: + + + ```bash {{ filename: 'terminal' }} + npm install @clerk/nuxt + ``` + + ```bash {{ filename: 'terminal' }} + yarn add @clerk/nuxt + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/nuxt + ``` + + + ## Set your Clerk API keys + + + Add the following keys to your `.env` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in your Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. + 1. Paste your key into your `.env` file. + + The final result should resemble the following: + + + ```env {{ filename: '.env' }} + NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} + NUXT_CLERK_SECRET_KEY={{secret}} + ``` + + ## Configure `nuxt.config.ts` + + To enable Clerk in your Nuxt app, add `@clerk/nuxt` to your modules array in `nuxt.config.ts`. This automatically configures Clerk's middleware and plugins and imports Clerk's components. + + ```ts {{ filename: 'nuxt.config.ts', mark: [2] }} + export default defineNuxtConfig({ + modules: ['@clerk/nuxt'], + }) + ``` + + ## Create a header with Clerk components + + Nuxt 3 automatically imports and makes all components in the `components/` directory globally available without requiring explicit imports. See the [Nuxt docs](https://nuxt.com/docs/guide/concepts/auto-imports) for details. + + You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). + + The following example creates a header using the following components: + + - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. + - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. + - [``](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options. + - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page or displays the sign-in modal. In this example, since no props or [environment variables](/docs/deployments/clerk-environment-variables) are set for the sign-in URL, this component links to the [Account Portal sign-in page](/docs/customization/account-portal/overview#sign-in). + + ```vue {{ filename: 'app.vue', mark: [2, [6, 13]] }} + + + + ``` + + ## Create your first user + + Run your project with the following command: + + + ```bash {{ filename: 'terminal' }} + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + + Visit your app's homepage at [`http://localhost:3000`](http://localhost:3000). Sign up to create your first user. + + +## More resources + +Learn more about Clerk components, how to customize them, and how to use Clerk's client-side helpers using the following guides. + + + - [Protect API routes using `clerkMiddleware()`](/docs/references/nuxt/clerk-middleware) + - Learn how to protect specific API routes from unauthenticated users. + + --- + + - [Read session and user data](/docs/references/nuxt/read-session-data) + - Learn how to use Clerk's composables and helpers to access the active session and user data in your Nuxt app. + + --- + + - [Client-side helpers](/docs/references/nuxt/overview#client-side-helpers) + - Learn more about Nuxt client-side helpers and how to use them. + + --- + + - [Clerk + Nuxt Quickstart Repo](https://github.com/clerk/clerk-nuxt-quickstart) + - The official companion repo for Clerk's Nuxt Quickstart. + diff --git a/docs/quickstarts/overview.mdx b/docs/quickstarts/overview.mdx index 498b62fe6f..ae8326fb50 100644 --- a/docs/quickstarts/overview.mdx +++ b/docs/quickstarts/overview.mdx @@ -33,6 +33,12 @@ description: See the getting started guides and tutorials. - [TanStack Start (Beta)](/docs/quickstarts/tanstack-start) - Easily add secure and SSR-friendly authentication to your TanStack Start application with Clerk. - ![](data:image/webp;base64,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) + + --- + + - [Nuxt](/docs/quickstarts/nuxt) + - Easily add secure, beautiful, and fast authentication to Nuxt with Clerk. + - {} ## Frontend @@ -65,6 +71,12 @@ description: See the getting started guides and tutorials. - [Chrome Extension](/docs/quickstarts/chrome-extension) - Use the Chome Extension SDK to authenticate users in your Chrome extension. - {} + + --- + + - [Vue](/docs/quickstarts/vue) + - Easily add secure, beautiful, and fast authentication to your Vue application with Clerk. + - {} ## Backend diff --git a/docs/quickstarts/vue.mdx b/docs/quickstarts/vue.mdx new file mode 100644 index 0000000000..f80dbe23cb --- /dev/null +++ b/docs/quickstarts/vue.mdx @@ -0,0 +1,182 @@ +--- +title: Vue Quickstart +description: Add authentication and user management to your Vue app with Clerk. +--- + + + - Create a new Vue app using Vite + - Install `@clerk/vue` + - Set your Clerk API keys + - Add `clerkPlugin` + - Create a header with Clerk components + + +Clerk's [Vue SDK](/docs/references/vue/overview) provides prebuilt components and composables to make it easy to integrate authentication and user management in your Vue app. This guide assumes that you're using [Vue 3](https://vuejs.org/) with [TypeScript](https://www.typescriptlang.org/). + + + ### Create a Vue app using Vite + + Run the following commands to create a new Vue app using [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project): + + + ```bash {{ filename: 'terminal' }} + npm create vite@latest clerk-vue -- --template vue-ts + cd clerk-vue + npm install + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn create vite clerk-vue --template vue-ts + cd clerk-vue + yarn install + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm create vite clerk-vue --template vue-ts + cd clerk-vue + pnpm install + pnpm dev + ``` + + + ### Install `@clerk/vue` + + Clerk's [Vue SDK](/docs/references/vue/overview) gives you access to prebuilt components, composables, and helpers to make user authentication easier. + + Run the following command to install the SDK: + + + ```bash {{ filename: 'terminal' }} + npm install @clerk/vue + ``` + + ```bash {{ filename: 'terminal' }} + yarn add @clerk/vue + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add @clerk/vue + ``` + + + ### Set your Clerk API keys + + + Add your Clerk Publishable Key to your `.env.local` file. This key can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. + + + + 1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. + 1. In the **Quick Copy** section, copy your Clerk Publishable Key. + 1. Paste your key into your `.env.local` file. + + The final result should resemble the following: + + + ```env {{ filename: '.env.local' }} + VITE_CLERK_PUBLISHABLE_KEY={{pub_key}} + ``` + + ### Import the Clerk Publishable Key + + In your `main.ts` file, import your Clerk Publishable Key. You can add an `if` statement to check that the key is imported properly. This prevents the app from running without the Publishable Key and catches TypeScript errors. + + ```tsx {{ filename: 'src/main.ts', mark: [5, [7, 9]] }} + import { createApp } from 'vue' + import './style.css' + import App from './App.vue' + + const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + if (!PUBLISHABLE_KEY) { + throw new Error('Add your Clerk Publishable Key to the .env.local file') + } + + createApp(App).mount('#app') + ``` + + ### Add `clerkPlugin` to your app + + `clerkPlugin` provides active session and user context to Clerk's components and composables. It's required to pass your Publishable Key as an option. + + ```ts {{ filename: 'src/main.ts', mark: [4, [12, 14]] }} + import { createApp } from 'vue' + import './style.css' + import App from './App.vue' + import { clerkPlugin } from '@clerk/vue' + + const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + if (!PUBLISHABLE_KEY) { + throw new Error('Add your Clerk Publishable Key to the .env.local file') + } + + const app = createApp(App) + app.use(clerkPlugin, { publishableKey: PUBLISHABLE_KEY }) + app.mount('#app') + ``` + + ### Create a header with Clerk components + + You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). The following example creates a header using the following components: + + - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. + - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. + - [``](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options. + - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page or displays the sign-in modal. + + ```vue {{ filename: 'src/App.vue', mark: [2, [6, 13]] }} + + + + ``` + + ### Create your first user + + Run your project with the following command: + + + ```bash {{ filename: 'terminal' }} + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + + Visit your app's homepage at [`http://localhost:5173`](http://localhost:5173). Sign up to create your first user. + diff --git a/docs/references/backend/overview.mdx b/docs/references/backend/overview.mdx index 48a87d65a9..7ee2a7777c 100644 --- a/docs/references/backend/overview.mdx +++ b/docs/references/backend/overview.mdx @@ -60,7 +60,7 @@ To access a resource, you must first instantiate a `clerkClient` instance. To use the default `clerkClient` instance, set your `CLERK_SECRET_KEY` [environment variable](/docs/deployments/clerk-environment-variables#clerk-publishable-and-secret-keys) and then import the `clerkClient` instance from the SDK as shown in the following example: - + ```jsx import { clerkClient } from '@clerk/nextjs/server' @@ -88,13 +88,19 @@ To access a resource, you must first instantiate a `clerkClient` instance. import { clerkClient } from '@clerk/express' ``` + + + ```js + import { clerkClient } from '@clerk/nuxt/server' + ``` + ### Instantiate a custom `clerkClient` instance If you would like to customize the behavior of the JavaScript Backend SDK, you can instantiate a `clerkClient` instance yourself by calling `createClerkClient()` and passing in [`options`](#create-clerk-client-options). - + ```jsx import { createClerkClient } from '@clerk/nextjs/server' @@ -243,6 +249,20 @@ To access a resource, you must first instantiate a `clerkClient` instance. ``` + + + ```tsx {{ filename: 'server/api/users/index.ts' }} + import { createClerkClient } from '@clerk/nuxt/server' + + export default defineEventHandler(async () => { + const config = useRuntimeConfig() + const clerkClient = createClerkClient({ secretKey: config.clerk.secretKey }) + const userList = await clerkClient.users.getUserList() + + return { userList } + }) + ``` + diff --git a/docs/references/nuxt/clerk-middleware.mdx b/docs/references/nuxt/clerk-middleware.mdx new file mode 100644 index 0000000000..7a4570718b --- /dev/null +++ b/docs/references/nuxt/clerk-middleware.mdx @@ -0,0 +1,122 @@ +--- +title: clerkMiddleware() | Nuxt +description: The clerkMiddleware() helper allows you to protect your Nuxt application using middleware. +--- + +The `clerkMiddleware()` helper allows you to protect your Nuxt application **on the server-side**. It can be used to validate a user's authentication status or authorization status. + +> [!NOTE] +> To learn how to protect pages, see the [dedicated guide](/docs/references/nuxt/protect-pages). + +## Configure `clerkMiddleware()` + +By default, the Nuxt SDK **automatically** adds the `clerkMiddleware()` helper to your Nuxt application. + +To **manually** configure the middleware: + +1. In your `nuxt.config.ts` file, under the `clerk` property, set `skipServerMiddleware: true`. + + ```ts {{ filename: 'nuxt.config.ts', mark: [[3, 5]] }} + export default defineNuxtConfig({ + modules: ['@clerk/nuxt'], + clerk: { + skipServerMiddleware: true, + }, + }) + ``` +1. In your `server/middleware/` directory, create a file named `clerk.ts` with the following code: + + ```ts {{ filename: 'src/middleware/clerk.ts' }} + import { clerkMiddleware } from '@clerk/nuxt/server' + export default clerkMiddleware() + ``` + +## Protect API routes + +You can protect routes using either or both of the following: + +- [Authentication-based protection](#authentication-based-protection): Verify if the user is signed in. +- [Authorization-based protection](#authorization-based-protection): Verify if the user has the required organization roles or custom permissions. + +### Authentication-based protection + +To protect routes based on user authentication status, you can check if the user is signed in by checking the `userId` on the [`auth`](/docs/references/nuxt/overview#auth-object) object. + +In the following example, the `clerkMiddleware()` helper checks if the user is signed in and accessing a protected route. If they aren't signed in, an error is thrown using Nuxt's [`createError()`](https://nuxt.com/docs/api/utils/create-error) utility. + +```tsx {{ filename: 'server/middleware/clerk.ts' }} +import { clerkMiddleware } from '@clerk/nuxt/server' + +export default clerkMiddleware((event) => { + const { userId } = event.context.auth + const isAdminRoute = event.path.startsWith('/api/admin') + + if (!userId && isAdminRoute) { + throw createError({ + statusCode: 401, + statusMessage: 'Unauthorized: User not signed in', + }) + } +}) +``` + +### Authorization-based protection + +To protect routes based on user authorization status, you can use the `has()` helper to check if the user has the required [organization roles or custom permissions](/docs/organizations/roles-permissions). It is available on the [`auth`](/docs/references/nuxt/overview#auth-object) object. + +#### Protecting routes using custom permissions + +In the following example, the `clerkMiddleware()` helper checks if the user is accessing a protected route. If so, it checks if the user has the required custom permission. If they don't, an error is thrown using Nuxt's [`createError()`](https://nuxt.com/docs/api/utils/create-error) utility. + +```ts {{ filename: 'server/middleware/clerk.ts' }} +import { clerkMiddleware } from '@clerk/nuxt/server' + +export default clerkMiddleware((event) => { + const { has } = event.context.auth + const isInvoicesRoute = event.path.startsWith('/api/invoices') + const canCreateInvoices = has({ + permission: 'org:invoices:create', + }) + + // Check if user is accessing sensitive customer data + if (isInvoicesRoute) { + // Check if user has the required permission + if (!canCreateInvoices) { + throw createError({ + statusCode: 403, + statusMessage: 'Unauthorized: Missing permission to create invoices', + }) + } + } +}) +``` + +#### Protecting routes using default roles + +> [!WARNING] +> It's best practice to use permission-based authorization over role-based authorization, as it reduces complexity and increases security. Usually, complex role checks can be refactored with a single permission check. + +In the following example, the `clerkMiddleware()` helper checks if the user is accessing a protected route. If so, it checks if the user has the required admin role. If they don't, an error is thrown using Nuxt's [`createError()`](https://nuxt.com/docs/api/utils/create-error) utility. + +```ts {{ filename: 'server/middleware/clerk.ts' }} +import { clerkMiddleware } from '@clerk/nuxt/server' + +export default clerkMiddleware((event) => { + const { has } = event.context.auth + const isAdminRoute = event.path.startsWith('/api/admin') + const isAdmin = has({ + role: 'org:admin', + }) + + // Check if the user is trying to access a protected route + if (isAdminRoute) { + // Check if the user has the required admin role + if (!isAdmin) { + throw createError({ + statusCode: 403, + statusMessage: 'Unauthorized: Admin access required', + }) + } + } +}) +``` diff --git a/docs/references/nuxt/overview.mdx b/docs/references/nuxt/overview.mdx new file mode 100644 index 0000000000..ca2aa08f82 --- /dev/null +++ b/docs/references/nuxt/overview.mdx @@ -0,0 +1,29 @@ +--- +title: Clerk Nuxt SDK +description: Learn how to integrate Clerk into your Nuxt application using the Clerk Nuxt SDK. +--- + +The Nuxt SDK is built on top of the [Vue SDK](/docs/references/vue/overview), and is the recommended method for integrating Clerk into your Nuxt application. + +## Guides + +- [Read session and user data](/docs/references/nuxt/read-session-data) +- [Protect pages](/docs/references/nuxt/protect-pages) + +## Client-side helpers + +Because the Nuxt SDK is built on top of the Clerk Vue SDK, you can use the composables that the Vue SDK provides. These composables give you access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object and a set of useful helper methods for signing in and signing up. Learn more in the [Vue SDK reference](/docs/references/vue/overview). + + + +## `Auth` object + +The `Auth` object is available at `event.context.auth` in your [event handlers](https://h3.unjs.io/guide/event-handler). This JavaScript object contains important information like session data, your user's ID, as well as their organization ID. [Learn more](/docs/references/nextjs/auth-object). + +## `clerkMiddleware()` + +The `clerkMiddleware()` helper integrates Clerk authentication and authorization into your Nuxt application through middleware. [Learn more](/docs/references/nuxt/clerk-middleware). + +## `clerkClient()` + +The `clerkClient()` helper returns an instance of the [JavaScript Backend SDK](/docs/references/backend/overview). [Learn more](/docs/references/nuxt/read-session-data#clerk-client). diff --git a/docs/references/nuxt/protect-pages.mdx b/docs/references/nuxt/protect-pages.mdx new file mode 100644 index 0000000000..2fd167e218 --- /dev/null +++ b/docs/references/nuxt/protect-pages.mdx @@ -0,0 +1,54 @@ +--- +title: Protect pages in your Nuxt app with Clerk +description: Learn how to protect the pages in your Clerk + Nuxt application. +--- + +There are two ways to protect pages in your Nuxt application: + +- [Use the `useAuth()` composable](#use-use-auth) +- [Use `defineNuxtRouteMiddleware()`](#use-define-nuxt-route-middleware) + +> [!NOTE] +> To learn how to protect API routes, see the [dedicated guide](/docs/references/nuxt/clerk-middleware#protect-api-routes). + +## Use `useAuth()` + + + +## Use `defineNuxtRouteMiddleware()` + +The [`defineNuxtRouteMiddleware()`](https://nuxt.com/docs/api/utils/define-nuxt-route-middleware) utility function helps protect pages in your Nuxt application by validating authentication on the client-side. This middleware integrates seamlessly with Clerk authentication. + + + ### Configure `defineNuxtRouteMiddleware()` + + In your `middleware/` directory, create a file named `auth.ts` with the following code. This middleware uses the `useAuth()` composable to check if the user is signed in. If they aren't, the middleware redirects them to the sign-in page. + + ```ts {{ filename: 'middleware/auth.ts' }} + export default defineNuxtRouteMiddleware(() => { + const { userId } = useAuth() + + // If the user is not signed in, redirect to the sign-in page + if (!userId.value) { + return navigateTo('/sign-in') + } + }) + ``` + + ### Protect pages with `defineNuxtRouteMiddleware()` + + To protect a page, add the middleware to the `definePageMeta()` function. In the last step, you stored the middleware in the `auth.ts` file, so you would pass `auth` in the `middleware` array. + + ```vue {{ filename: 'pages/dashboard.vue' }} + + + + ``` + diff --git a/docs/references/nuxt/read-session-data.mdx b/docs/references/nuxt/read-session-data.mdx new file mode 100644 index 0000000000..c5240fb0ba --- /dev/null +++ b/docs/references/nuxt/read-session-data.mdx @@ -0,0 +1,58 @@ +--- +title: Read session and user data in your Nuxt app with Clerk +description: Learn how to use Clerk's composables to access the active session and user data in your Nuxt application. +--- + +Clerk provides [composables](/docs/references/nuxt/overview#client-side-helpers) to access the session and user data in your Nuxt application. + +## Client-side + +### `useAuth()` + + + +## `useUser()` + +The `useUser()` composable provides access to the current user's [`User`](/docs/references/javascript/user/user) object, which holds all of the data for a user of your application and provides a set of methods to manage their account. + +In the following example, the `isLoaded` property checks if Clerk has finished initializing and the `isSignedIn` property checks if a user is currently signed in. + +```vue {{ filename: 'pages/protected-page.vue' }} + + + +``` + +## Server-side + +### `clerkClient()` + +The `clerkClient()` helper returns an instance of the [JavaScript Backend SDK](/docs/references/backend/overview). + +In the following example, the [`auth`](/docs/references/nuxt/overview#auth-object) object is used to get the `userId` to check if the user is signed in. The `clerkClient()` helper retrieves the full [`User`](/docs/references/javascript/user/user) object. + +```ts {{ filename: 'server/api/auth/index.ts' }} +import { clerkClient } from '@clerk/nuxt/server' + +export default defineEventHandler(async (event) => { + const { userId } = event.context.auth + + // Check if the user is signed in + if (!userId) { + throw createError({ + statusCode: 401, + statusMessage: 'Unauthorized: No user ID provided', + }) + } + + // Retrieve the user data + const user = await clerkClient(event).users.getUser(userId) + return user +}) +``` diff --git a/docs/references/react/use-user.mdx b/docs/references/react/use-user.mdx index 4c3b635bf0..ca52c5b54e 100644 --- a/docs/references/react/use-user.mdx +++ b/docs/references/react/use-user.mdx @@ -89,7 +89,7 @@ export default function Home() { ### Reload user data -The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`reload()`](/docs/references/javascript/user/user#reload) method to get the latest user's information via an external API endpoint. +The following example uses the `useUser()` hook to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`reload()`](/docs/references/javascript/user/user#reload) method to get the latest user's information. ```tsx {{ filename: 'src/Home.tsx' }} import { useUser } from '@clerk/clerk-react' diff --git a/docs/references/vue/migrating-from-vue-community-sdk.mdx b/docs/references/vue/migrating-from-vue-community-sdk.mdx new file mode 100644 index 0000000000..177a613bfa --- /dev/null +++ b/docs/references/vue/migrating-from-vue-community-sdk.mdx @@ -0,0 +1,55 @@ +--- +title: Migrating from the Vue community SDK +description: Learn how to migrate from the Vue community SDK to the Clerk Vue SDK. +--- + +In December 2024, Clerk introduced official support for Vue. This migration guide covers converting from the [`vue-clerk`](https://vue-clerk.vercel.app) community SDK to Clerk's official SDK. It covers the breaking changes that were introduced and provides examples on how to resolve them. + +## Installation + +Uninstall the community SDK and install Clerk's new official SDK for Vue. + + + ```bash {{ filename: 'terminal' }} + npm uninstall vue-clerk + npm install @clerk/vue + ``` + + ```bash {{ filename: 'terminal' }} + yarn remove vue-clerk + yarn add @clerk/vue + ``` + + ```bash {{ filename: 'terminal' }} + pnpm remove vue-clerk + pnpm add @clerk/vue + ``` + + +## Breaking changes + +### The `useClerk()` composable + +The `useClerk()` composable has two important changes: + +1. Import path has changed from `vue-clerk` to `@clerk/vue`. +1. The return value is now a Vue [ref](https://vuejs.org/api/reactivity-core.html#ref) containing the Clerk instance. + +The key difference is that you now need to use `clerk.value` to access Clerk methods, since the composable returns a reactive ref. + +Update your code as follows: + +```vue {{ del: [2, 6], ins: [3, 7] }} + + +``` diff --git a/docs/references/vue/overview.mdx b/docs/references/vue/overview.mdx new file mode 100644 index 0000000000..4f6ff740aa --- /dev/null +++ b/docs/references/vue/overview.mdx @@ -0,0 +1,27 @@ +--- +title: Clerk Vue SDK +description: Learn how to integrate Clerk into your Vue application using the Clerk Vue SDK. +--- + +The Vue SDK is built on top of the [Clerk JavaScript SDK](/docs/references/javascript/overview), and is the recommended way to integrate Clerk into your Vue application. + +## Custom composables + +The Vue SDK provides access to custom composables that provide direct access to the [`Clerk` object](/docs/references/javascript/clerk/clerk), a user's [`User` object](/docs/references/javascript/user/user), and helper methods for authentication flows. + + + +## Framework-specific SDKs + +> [!IMPORTANT] +> If you're building a standard Vue application (client-side only), use `@clerk/vue`. If you're using Nuxt, use the dedicated `@clerk/nuxt` package which includes backend integration. + +Clerk offers framework-specific SDKs that are customized to provide the better developer experience and integration with each framework's features. Choose the appropriate SDK based on your framework: + +| Framework | Package | Docs | +| - | - | - | +| Nuxt | `@clerk/nuxt` | [Nuxt SDK](/docs/references/nuxt/overview) | + +## Set up Clerk Vue + +Before you can add Clerk to your Vue application, you must create a Clerk app in the Clerk Dashboard. To get started, follow the [setup guide](/docs/quickstarts/setup-clerk). Then, follow the [quickstart guide](/docs/quickstarts/vue) to set up the Vue SDK in your app. diff --git a/docs/references/vue/use-auth.mdx b/docs/references/vue/use-auth.mdx new file mode 100644 index 0000000000..78b2a4d850 --- /dev/null +++ b/docs/references/vue/use-auth.mdx @@ -0,0 +1,111 @@ +--- +title: useAuth() +description: Access and manage authentication state in your Vue application with Clerk's useAuth() composable. +--- + +The `useAuth()` composable provides access to the current user's authentication state and methods to manage the active session in your Vue application. + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `isSignedIn` + - `Ref` + + A boolean that indicates whether a user is currently signed in. + + --- + + - `userId` + - `Ref` + + The ID of the current user. + + --- + + - `sessionId` + - `Ref` + + The ID of the current session. + + --- + + - `orgId` + - `Ref` + + The ID of the user's active organization. + + --- + + - `orgRole` + - `Ref` + + The current user's role in their active organization. + + --- + + - `orgSlug` + - `Ref` + + The URL-friendly identifier of the user's active organization. + + --- + + - `signOut()` + - `Ref<(options?: SignOutOptions) => Promise>` + + A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](/docs/references/javascript/clerk/clerk#sign-out). + + --- + + - `getToken()` + - `Ref<(options?: GetTokenOptions) => Promise>` + + A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](/docs/references/javascript/session#get-token). + + --- + + - `has()` + - `Ref<(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean>` + + A function that checks if the user has specific permissions or roles. See the [reference doc](/docs/references/nextjs/auth-object#has). + + +## How to use the `useAuth()` composable + +The following example demonstrates how to use the `useAuth()` composable to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource. + +```vue {{ filename: 'App.vue' }} + + + +``` diff --git a/docs/references/vue/use-clerk.mdx b/docs/references/vue/use-clerk.mdx new file mode 100644 index 0000000000..dbe6b4cf5a --- /dev/null +++ b/docs/references/vue/use-clerk.mdx @@ -0,0 +1,29 @@ +--- +title: useClerk() +description: Access and manage the Clerk instance in your Vue application with Clerk's useClerk() composable. +--- + +> [!WARNING] +> This composable should only be used for advanced use cases, such as building a completely custom OAuth flow or as an escape hatch to access to the `Clerk` object. + +The `useClerk()` composable provides access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, giving you the ability to build alternatives to any [Clerk component](/docs/components/overview). + +## Returns + +The `useClerk()` composable returns the `Clerk` object, which includes all the methods and properties listed in the [`Clerk` reference](/docs/references/javascript/clerk/clerk). + +## How to use the `useClerk()` composable + +The following example uses the `useClerk()` composable to access the `clerk` object. The `clerk` object is used to call the [`openSignIn()`](/docs/references/javascript/clerk/clerk#sign-in) method to open the sign-in modal. + +```vue + + + +``` diff --git a/docs/references/vue/use-organization.mdx b/docs/references/vue/use-organization.mdx new file mode 100644 index 0000000000..bb391f436e --- /dev/null +++ b/docs/references/vue/use-organization.mdx @@ -0,0 +1,124 @@ +--- +title: useOrganization() +description: Access and manage the currently active organization in your Vue application with Clerk's useOrganization() composable. +--- + +The `useOrganization()` composable retrieves attributes of the currently active organization. + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `organization` + - Ref\<[Organization](/docs/references/javascript/organization/organization)> + + The currently active organization. + + --- + + - `membership` + - Ref\<[OrganizationMembership](/docs/references/javascript/organization-membership)> + + The current organization membership. + + +## How to use the `useOrganization()` composable + +### Retrieve the current active organization + +Use `useOrganization()` to access the current active [`Organization`](/docs/references/javascript/organization/organization) object. + +```vue {{ filename: 'OrganizationStatus.vue' }} + + + +``` + +### Paginate organization memberships + +The following example demonstrates how to use `useOrganization()` to access the organization's memberships. Pagination is implemented by fetching pages of memberships when the "Previous page" or "Next page" buttons are clicked. + +```vue {{ filename: 'MembershipList.vue', collapsible: true }} + + + +``` diff --git a/docs/references/vue/use-session-list.mdx b/docs/references/vue/use-session-list.mdx new file mode 100644 index 0000000000..d7e9292806 --- /dev/null +++ b/docs/references/vue/use-session-list.mdx @@ -0,0 +1,76 @@ +--- +title: useSessionList() +description: Access and manage a list of sessions registered on the client device in your Vue application with Clerk's useSessionList() composable. +--- + +The `useSessionList()` composable returns an array of [`Session`](/docs/references/javascript/session) objects that have been registered on the client device. + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `setActive()` + - Ref\<(params: [SetActiveParams](#set-active-params)) => Promise\> + + A function that sets the active session and/or organization. + + --- + + - `sessions` + - Ref\<[Session](/docs/references/javascript/session)> + + A list of sessions that have been registered on the client device. + + +### `SetActiveParams` + + + - `session` + - [Session](/docs/references/javascript/session) | string | null + + The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted. + + --- + + - `organization` + - [Organization](/docs/references/javascript/organization/organization) | string | null + + The organization resource or organization ID/slug (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active. + + --- + + - `beforeEmit?` + - `(session?: Session | null) => void | Promise` + + Callback run just before the active session and/or organization is set to the passed object. Can be used to set up for pre-navigation actions. + + +## How to use the `useSessionList()` composable + +### Get a list of sessions + +The following example uses `useSessionList()` to get a list of sessions that have been registered on the client device. The `sessions` property is used to show the number of times the user has visited the page. + +```vue {{ filename: 'SessionList.vue' }} + + + +``` diff --git a/docs/references/vue/use-session.mdx b/docs/references/vue/use-session.mdx new file mode 100644 index 0000000000..ff0bf2a28f --- /dev/null +++ b/docs/references/vue/use-session.mdx @@ -0,0 +1,57 @@ +--- +title: useSession() +description: Access and manage the current user's session in your Vue application with Clerk's useSession() composable. +--- + +The `useSession()` composable provides access to the current user's [`Session`](/docs/references/javascript/session) object, as well as helpers for setting the active session. + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has finished loading and initializing. Returns `false` during initialization. + + --- + + - `isSignedIn` + - `Ref` + + A boolean that indicates whether a user is currently signed in. + + --- + + - `session` + - Ref\<[Session](/docs/references/javascript/session)> + + Holds the current active session for the user. + + +## How to use the `useSession()` composable + +### Access the `Session` object + +The following example uses `useSession()` to access the `Session` object, which has the `lastActiveAt` property. The `lastActiveAt` property is a `Date` object used to show the time the session was last active. + +```vue {{ filename: 'SessionStatus.vue' }} + + + +``` diff --git a/docs/references/vue/use-sign-in.mdx b/docs/references/vue/use-sign-in.mdx new file mode 100644 index 0000000000..056a42932a --- /dev/null +++ b/docs/references/vue/use-sign-in.mdx @@ -0,0 +1,72 @@ +--- +title: useSignIn() +description: Access and manage sign-in state in your Vue application with Clerk's useSignIn() composable. +--- + +The `useSignIn()` composable provides access to the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in attempt and manage the sign-in flow. You can use this to create a [custom sign-in flow](/docs/custom-flows/overview#sign-in-flow). + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `setActive()` + - Ref\<(params: [SetActiveParams](#set-active-params)) => Promise\> + + A function that sets the active session. + + --- + + - `signIn` + - Ref\<[SignIn](/docs/references/javascript/sign-in/sign-in)> + + An object that contains the current sign-in attempt status and methods to create a new sign-in attempt. + + +### `SetActiveParams` + + + - `session` + - [Session](/docs/references/javascript/session) | string | null + + The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted. + + --- + + - `organization` + - [Organization](/docs/references/javascript/organization/organization) | string | null + + The organization resource or organization ID/slug (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active. + + --- + + - `beforeEmit?` + - `(session?: Session | null) => void | Promise` + + Callback run just before the active session and/or organization is set to the passed object. Can be used to set up for pre-navigation actions. + + +## How to use the `useSignIn()` composable + +The following example uses `useSignIn()` to access the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state. + +```vue {{ filename: 'SignInPage.vue' }} + + + +``` diff --git a/docs/references/vue/use-sign-up.mdx b/docs/references/vue/use-sign-up.mdx new file mode 100644 index 0000000000..aa99db1ee2 --- /dev/null +++ b/docs/references/vue/use-sign-up.mdx @@ -0,0 +1,74 @@ +--- +title: useSignUp() +description: Access and manage sign-up state in your Vue application with Clerk's useSignUp() composable. +--- + +The `useSignUp()` composable provides access to the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up attempt and manage the sign-up flow. You can use this to create a [custom sign-up flow](/docs/custom-flows/overview#sign-up-flow). + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `setActive()` + - Ref\<(params: [SetActiveParams](#set-active-params)) => Promise\> + + A function that sets the active session. + + --- + + - `signUp` + - Ref\<[SignUp](/docs/references/javascript/sign-up/sign-up)> + + An object that contains the current sign-up attempt status and methods to create a new sign-up attempt. + + +### `SetActiveParams` + + + - `session` + - [Session](/docs/references/javascript/session) | string | null + + The session resource or session ID (string version) to be set as active. If `null`, the current session is deleted. + + --- + + - `organization` + - [Organization](/docs/references/javascript/organization/organization) | string | null + + The organization resource or organization ID/slug (string version) to be set as active in the current session. If `null`, the currently active organization is removed as active. + + --- + + - `beforeEmit?` + - `(session?: Session | null) => void | Promise` + + Callback run just before the active session and/or organization is set to the passed object. Can be used to set up for pre-navigation actions. + + +## How to use the `useSignUp()` composable + +### Check the current state of a sign-up + +The following example uses the `useSignUp()` hook to access the [`SignUp`](/docs/references/javascript/sign-up/sign-up) object, which contains the current sign-up attempt status and methods to create a new sign-up attempt. The `isLoaded` property is used to handle the loading state. + +```vue {{ filename: 'SignUpStep.vue' }} + + + +``` diff --git a/docs/references/vue/use-user.mdx b/docs/references/vue/use-user.mdx new file mode 100644 index 0000000000..7cc6a1e396 --- /dev/null +++ b/docs/references/vue/use-user.mdx @@ -0,0 +1,120 @@ +--- +title: useUser() +description: Access and manage the current user's data in your Vue application with Clerk's useUser() composable. +--- + +The `useUser()` composable provides access to the current user's [`User`](/docs/references/javascript/user/user) object, which contains all the data for a single user in your application and provides methods to manage their account. This composable also allows you to check if the user is signed in and if Clerk has loaded and initialized. + +## Returns + + + - `isLoaded` + - `Ref` + + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. + + --- + + - `user` + - Ref\<[User](/docs/references/javascript/user/user)> + + The `User` object for the current active user. If the user isn't signed in, `user` will be `null`. + + --- + + - `isSignedIn` + - `Ref` + + Indicates whether a user is currently signed in. + + +## How to use the `useUser()` composable + +### Get the current user + +The following example uses the `useUser()` composable to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively. + +```vue {{ filename: 'GetCurrentUser.vue' }} + + + +``` + +### Update user data + +The following example uses the `useUser()` composable to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`update()`](/docs/references/javascript/user/user#update) method to update the current user's information. + +```vue {{ filename: 'UpdateUser.vue' }} + + + +``` + +### Reload user data + +The following example uses the `useUser()` composable to access the [`User`](/docs/references/javascript/user/user) object, which calls the [`reload()`](/docs/references/javascript/user/user#reload) method to get the latest user's information. + +```vue {{ filename: 'ReloadUser.vue' }} + + + +```