Skip to main content
Docs
Dashboard

Fastify Quickstart

You will learn the following:

  • Install @clerk/fastify
  • Set your Clerk API keys
  • Configure clerkPlugin for all routes
  • Use getAuth() to access the auth state and protect routes
  • Configure clerkPlugin for specific routes

Before you start

Example repository

Learn how to integrate Clerk into your Fastify backend for secure user authentication and management. This guide uses TypeScript and allows you to choose your frontend framework.

Important

Fastify is only compatible with Next.js versions 13.4 and below. If you're using a newer version of Next.js, consider using a different backend framework that supports the latest Next.js features.

This guide uses ECMAScript Modules (ESM). To use ESM in your project, you must include "type": "module" in your package.json.

Install @clerk/fastify

Clerk's Fastify SDK provides a range of backend utilities to simplify user authentication and management in your application.

Run the following command to install the SDK:

terminal
npm install @clerk/fastify
terminal
yarn add @clerk/fastify
terminal
pnpm add @clerk/fastify
terminal
bun add @clerk/fastify

Set your Clerk API keys

.env
CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Configure clerkPlugin() for all routes

The clerkPlugin() function is a Fastify plugin provided by Clerk to integrate authentication into your Fastify application. To ensure that Clerk's authentication and user management features are applied across your Fastify application, configure the clerkPlugin() to handle all routes or limit it to specific ones.

The following example registers the plugin for all routes. To register the plugin for specific routes, see the reference docs.

Important

The dotenv/config module must be imported before any Clerk modules. This order is important because Clerk instances are created during the import process and rely on environment variables, such as API keys, to be initialized correctly. For more information, refer to the Fastify docs.

index.ts
import 'dotenv/config'
import Fastify from 'fastify'
import { clerkPlugin } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin)

const start = async () => {
  try {
    await fastify.listen({ port: 8080 })
  } catch (error) {
    fastify.log.error(error)
    process.exit(1)
  }
}

start()

Protect your routes using getAuth()

The getAuth() helper retrieves the current user's authentication state from the request object. It returns the Auth object.

The following example uses getAuth() to protect a route and load the user's data. If the user is authenticated, their userId is passed to clerkClient.users.getUser() to get the current user's User object. If not authenticated, the request is rejected with a 401 status code.

// dotenv must be imported before @clerk/fastify
import 'dotenv/config'
import Fastify from 'fastify'
import { clerkClient, clerkPlugin, getAuth } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin)

// Use `getAuth()` to protect this route
fastify.get('/protected', async (request, reply) => {
  try {
    // Use `getAuth()` to get the user's ID
    const { userId } = getAuth(request)

    // If user isn't authenticated, return a 401 error
    if (!userId) {
      return reply.code(401).send({ error: 'User not authenticated' })
    }

    // Use `clerkClient` to access Clerk's Backend SDK methods
    // and get the user's User object
    const user = userId ? await clerkClient.users.getUser(userId) : null

    return reply.send({
      message: 'User retrieved successfully',
      user,
    })
  } catch (error) {
    fastify.log.error(error)
    return reply.code(500).send({ error: 'Failed to retrieve user' })
  }
})

const start = async () => {
  try {
    await fastify.listen({ port: 8080 })
  } catch (error) {
    fastify.log.error(error)
    process.exit(1)
  }
}

start()

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on