diff --git a/docs/_partials/nuxt/use-auth.mdx b/docs/_partials/nuxt/use-auth.mdx new file mode 100644 index 0000000000..10be5d3743 --- /dev/null +++ b/docs/_partials/nuxt/use-auth.mdx @@ -0,0 +1,15 @@ +The `useAuth()` composable provides access to the current 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 8684adb8c7..0645869ca2 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -87,6 +87,12 @@ Find all the guides and resources you need to develop 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. - {} diff --git a/docs/manifest.json b/docs/manifest.json index 01ed1c237e..4e10710e15 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" } ] ] @@ -2691,6 +2696,45 @@ ] ] }, + { + "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 Reference", + "items": [ + [ + { + "title": "`clerkMiddleware()`", + "wrap": false, + "href": "/docs/references/nuxt/clerk-middleware" + } + ] + ] + } + ] + ] + }, { "title": "Vue", "collapse": true, @@ -2755,6 +2799,18 @@ } ] ] + }, + { + "title": "General Reference", + "items": [ + [ + { + "title": "`clerkMiddleware()`", + "wrap": false, + "href": "/docs/references/nuxt/clerk-middleware" + } + ] + ] } ] ] 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 a1c1dce056..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 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..7e7a6624df --- /dev/null +++ b/docs/references/nuxt/overview.mdx @@ -0,0 +1,36 @@ +--- +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). + +- [`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) + +## `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..711d2c1dc5 --- /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..f01f0939ec --- /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 +}) +```