Create a custom getUser() function

import { auth } from '@clerk/nextjs/server'

export const getUser = async () => {
  // I highly recommend taking some time to understand all the methods
  // and properties this function returns, `has()` is useful for permission
  // checks, and `getToken()` is great for authenticating external api calls
  // Alongside `userId`, you'll likely want `orgId` in a b2b setup
  const { isAuthenticated, userId } = await auth()

  if (!isAuthenticated) {
    // This is our first major option, and we have many choices

    // A common option is going to be to `throw new Error('Unauthorized')`
    // ensuring that we can only continue if the user is logged in.

    // But if we are using a framework we may want to `throw new TRPCError()`
    // or call `unauthorized()` (https://nextjs.org/docs/app/api-reference/functions/unauthorized)

    // A more advanced pattern is to throw a response
    // `throw new Response("Unauthorized", { status: 401 })`
    // Using a higher level function to catch and return the response object.

    // If we are using EffectTS we may want to return an Error object

    // Or simply we can just return null, signifying that user can't be
    // authenticated, letting the request handler do what it wants with
    // that information
    return null
  }

  return {
    // For now we simply want to return the user identifier.
    userId,
  }
}

{
  "email": "{{user.primary_email_address}}"
}

import { auth } from '@clerk/nextjs/server'

export const getUser = async () => {
  // Extract out `sessionClaims` from the `auth()` call for us to use
  const { isAuthenticated, userId, sessionClaims } = await auth()

  if (!isAuthenticated) return null

  return {
    userId,

    // for now let's just return it
    sessionClaims,
  }
}

{
  "userId": "user_2u823dCrAIzoQfgjnsimCYJvJaI",
  "sessionClaims": {
    "azp": "http://localhost:3001",
    // Here we have it, because we configured in the dashboard to include the
    // users email, it shows up here, no network request to clerks infra
    // needed, no rate limits.
    "email": "your-email@example.com",
    "exp": 1751214847,
    "fva": [137, -1],
    "iat": 1751214787,
    "iss": "https://awake-cobra-28.clerk.accounts.dev",
    "jti": "002332cec9e6fb9c9efd",
    "nbf": 1751214777,
    "sid": "sess_2zBZjlFCRMOq1LSDOcJwMBAzQSR",
    "sub": "user_2u823dCrAIzoQfgjnsimCYJvJaI",
    "v": 2
  }
}

import { auth } from '@clerk/nextjs/server'

export const getUser = async () => {
  const { isAuthenticated, userId, sessionClaims } = await auth()

  if (!isAuthenticated) return null

  // Now that sessionClaims is type safe, we are free to extract out our `email`
  // property, if you marked it as optional you may want to add in a if check.
  const { email } = sessionClaims

  return {
    userId,
    // Return the users email ready to be used.
    email,
  }
}

  {
    "email": "{{user.primary_email_address}}",
    // You can call this whatever you'd like,
    // I went with 'details' but it's completely up to you
+   "details": "{{user.public_metadata}}"
  }

import { auth } from '@clerk/nextjs/server'

export const getUser = async () => {
  const { isAuthenticated, userId, sessionClaims } = await auth()

  if (!isAuthenticated) return null

  // Just like the email property we added to the custom session, we now can
  // pull out the `details` property for our use. The magic here is we get
  // access to this data without any network request to Clerk's infra.
  // So your website stays fast.
  const { email, details } = sessionClaims

  // With the details property, we have a couple different options for
  // how we want to return it.

  // This is the safest option, as we have no risk that a property
  // inside `details` could conflict with a `userId` or `email`
  // but it means you'll need to access it one layer deeper
  // eg user.details.favoritePizza
  return {
    userId,
    email,
    details,
  }

  // I wouldn't recommend this option, in the future a developer
  // may add `email` to the custom metadata by accident
  // and this would overwrite the users email we are expecting
  // Clerk to manage for us
  return {
    userId,
    email,
    ...details,
  }

  // For me this is the happy middle ground, it keeps the data access
  // short (eg user.favoritePizza) but doesn't let us accidentally
  // overright the other properties we are expecting
  return {
    ...details,
    userId,
    email,
  }
}

{
  "favoritePizza": "Pepperoni",
  "favoriteSnack": "Oreos",
  "userId": "user_2u823dCrAIzoQfgjnsimCYJvJaI",
  "email": "your-email@example.com"
}

// We will start by bringing in the `clerkClient`, this can change between Clerk SDKs
import { auth, clerkClient } from '@clerk/nextjs/server'

export const getUser = async () => {
  const { isAuthenticated, userId, sessionClaims } = await auth()

  if (!isAuthenticated) return null

  const { email, details } = sessionClaims

  // Bit of function inception here, we are defining our own update function
  // inside the getUser function, but trust me, this is perfectly natural

  // One cool typescript trick, We can simply use the typescript tool `typeof`
  // to extract out our custom type from the types.d.ts, instead of having to
  // re-define the type here.
  const update = async (newDetails: Partial<typeof details>) => {
    // We are going to need to call the clerk backend api, so we will start by
    // instantiating it ready for our use. Despite the await here, this is
    // simply for a dynamic import, no network fetch yet.
    // `clerkClient()` will pick up our clerk environment variables automatically
    // no need to pass them in here.
    const clerk = await clerkClient()

    // Finally we update the metadata, This function actually returns the full
    // user object (same as calling currentUser()) so we can use that if we want
    await clerk.users.updateUserMetadata(userId, {
      // Since we picked public metadata earlier at the start we want to update that
      publicMetadata: {
        // Here I am spreading in the existing details first, so any values not
        // getting updated, won't get deleted
        ...details,
        // And second I am spreading in the new details, overwriting or adding
        // as need be.
        ...newDetails,
      },
    })
  }

  return {
    ...details,
    userId,
    email,

    // And lets just return our `update()` function ready to be used.
    update,
  }
}

import { getUser } from '~/lib/get-user'

export default async function UserPage() {
  const user = await getUser()

  if (!user) return <span>Unauthenticated :(</span>

  return (
    <div>
      <h1>Welcome {user.email}</h1>
      {user.favoritePizza ? <span>I hear your favorite pizza is {user.favoritePizza}</span> : null}
    </div>
  )
}

'use server'

import { getUser } from '~/lib/get-user'

export const processPizzaOrder = async (pizzaChoice: 'pepperoni' | 'barbecue' | 'chicken') => {
  const user = await getUser()

  if (user === null) {
    return {
      error: 'Unauthenticated',
    }
  }

  user.update({
    favoritePizza: pizzaChoice,
  })
}

// I am using zod for validation here, but you can use whatever you want
import { z } from 'zod'
import { getUser } from '~/lib/get-user'

// In Get requests, you typically don't want to modify any data,
// so we aren't going to use the `update()` function here.
export const GET = async (request: Request) => {
  const user = await getUser()

  if (user === null) {
    // You may want to fail more gracefully here,
    // for example redirecting to a login page.
    // or returning `We don't know your favorite snack`
    return new Response('Unauthenticated', { status: 401 })
  }

  return new Response(`${user.email}'s favorite snack is ${user.favoriteSnack}`)
}

const bodySchema = z.object({
  snack: z
    .string()
    .min(1, {
      message: 'Snack is required',
    })
    .max(20, {
      message: 'Snack must be less than 20 characters',
    }),
})

export const POST = async (request: Request) => {
  // We don't even bother validating the request body yet
  // If the users not authenticated, don't waste the compute
  // validating the request body.
  const user = await getUser()

  if (user === null) {
    return new Response('Unauthenticated', { status: 401 })
  }

  const body = bodySchema.safeParse(await request.json())

  if (!body.success) {
    return new Response(body.error.message, { status: 400 })
  }

  // With the new data, we can update the users metadata.
  await user.update({
    favoriteSnack: body.data.snack,
  })

  // We may want to also send an email notification here
  // Or duel save the data to our own database.
  // Possibly we want to log the change to monitoring server

  return new Response(`${user.email}'s favorite snack is ${body.data.snack}`)
}

// I am using postgres, but none of what I am doing is particularly specific to postgres, so feel free to use whatever dialect you want.
import { index, pgEnum, pgTable } from 'drizzle-orm/pg-core'

export const orderStatus = pgEnum('order_status', ['pending', 'shipped', 'delivered'])

export const orders = pgTable(
  'orders',
  (t) => ({
    orderId: t.integer().primaryKey().generatedAlwaysAsIdentity(),

    // It's possible you will want to call this something more specific, eg `clerkUserId`
    userId: t.varchar().notNull(),
    status: orderStatus().notNull().default('pending'),
    createdAt: t.timestamp().defaultNow(),
    updatedAt: t.timestamp().defaultNow(),
  }),

  // Because this is an external id, we need to index it to tell the database we will be querying by it
  (table) => [index().on(table.userId)],
)

export const items = pgTable('items', (t) => ({
  itemId: t.integer().primaryKey().generatedAlwaysAsIdentity(),
  name: t.varchar().notNull(),
  price: t.integer().notNull(),
  discount: t.integer(),
}))

export const orderItems = pgTable('order_items', (t) => ({
  orderId: t.integer().references(() => orders.orderId),
  itemId: t.integer().references(() => items.itemId),
  quantity: t.integer().notNull(),
}))

'use server'

import { db } from '~/db'
import { orderItems, orders } from '~/db/schema'
import { getUser } from '~/lib/get-user'

export const addItemToOrder = async (itemId: number, quantity: number) => {
  const user = await getUser()

  if (user === null) {
    return { error: 'Unauthenticated' }
  }

  // Here we are handling the situation that no order exists yet
  // We start by updating the database to create a new order for the user
  // We use our user.update function to get the important details on the user
  // And we finish off with inserting the item into the order
  if (user.currentOrder === null) {
    const [newOrder] = await db
      .insert(orders)
      .values({
        userId: user.userId,
      })
      .returning({
        orderId: orders.orderId,
        status: orders.status,
      })

    await user.update({
      currentOrder: {
        orderId: newOrder.orderId,
        orderStatus: newOrder.status,
      },
    })

    await db.insert(orderItems).values({
      orderId: newOrder.orderId,
      itemId,
      quantity,
    })

    return {
      message: 'Order created and item added',
    }
  }

  // But once the order is created, we can simply add the item
  // We don't even need to verify that the order belongs
  // to the user, as we are using public metadata so it can only be
  // set server side, as we do above
  await db.insert(orderItems).values({
    orderId: user.currentOrder.orderId,
    itemId,
    quantity,
  })

  return {
    message: 'Item added to existing order',
  }
}

  import { auth, clerkClient } from '@clerk/nextjs/server'
  import { eq } from 'drizzle-orm'
  import { db } from '~/db'
  import { users } from '~/db/schema'
  import { setupStripeCustomer } from '~/app/onboarding/payments/actions'
  
  export const getUser = async () => {
    const { isAuthenticated, userId, sessionClaims } = await auth()
  
    if (!isAuthenticated) return null
  
    const { email, details } = sessionClaims
  
    const update = async (newDetails: Partial<typeof details>) => {
      const clerk = await clerkClient()
  
      await clerk.users.updateUserMetadata(userId, {
        publicMetadata: {
          ...details,
          ...newDetails,
        },
      })
    }
  
+   let stripeCustomerId = details.stripeCustomerId
  
    // So now anytime this function is called we are going to check if the user doesn't have a stripeCustomerId set
    // This check alone has no cost, as it's information stored in the users session
+   if (details.stripeCustomerId === undefined) {
+     const [user_db] = await db
+       .select({
+         stripeCustomerId: users.stripeCustomerId,
+       })
+       .from(users)
+       .where(eq(users.clerkUserId, userId))
  
+     if (user_db.stripeCustomerId === null) {
+       stripeCustomerId = await setupStripeCustomer()
+     } else {
+       await update({
+         stripeCustomerId: user_db.stripeCustomerId,
+       })
  
+       stripeCustomerId = user_db.stripeCustomerId
+     }
+   }
  
    return {
      ...details,
+     stripeCustomerId,
      userId,
      email,
      update,
    }
  }

import { getUser } from '~/lib/get-user'
import { db } from '~/db'
import { userDetails } from '~/db/schema'

// Call this function whenever we are adding or updating a resource that is tied to a user, for example a user video upload, or a comment in a comment section, or a document getting shared.
export const syncUserData = async (user: Awaited<ReturnType<typeof getUser>>) => {
  // Use our existing getUser() user object to get the user data, whether that is clerk provided information, or custom metadata we are storing.
  // For this example you would need to update the Session Token to include the users full name, primary email, and profile image.

  // Do a database upsert, essentially saying add the user details to the database if they don't exist, or update their details if they do.
  await db
    .insert(userDetails)
    .values({
      clerkUserId: user.userId,
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
      imageUrl: user.imageUrl,

      // We want to know when this data was last synced, so we don't accidentally overwrite newer details with older details if update requests come in out of order.
      lastClerkSync: new Date(),
    })
    .onConflictDoUpdate({
      target: userDetails.clerkUserId,
      set: {
        firstName: user.firstName,
        lastName: user.lastName,
        email: user.email,
        imageUrl: user.imageUrl,
        lastClerkSync: new Date(),
      },
    })
}

'use client'

import { useAuth } from '@clerk/nextjs'

export const useUser = () => {
  const { isSignedIn, userId, sessionClaims } = useAuth()

  // Like the `getUser()` function, feel free to customize how you want to handle the user not being signed in. If you are expecting this hook to only be used in authenticated components, you could throw an Error() here.
  if (!isSignedIn) return null

  // Extract out the session claims, when we set the custom token details in the types.d.ts above, those types will work here too, so we keep the type safety.
  const { email, details } = sessionClaims

  return {
    ...details,
    userId,
    email,
  }
}

import { useUser } from '@clerk/nextjs'

const { user } = useUser()

user.reload()

import { useSession } from '@clerk/nextjs'

const { session } = useSession()

session.reload()

import { useAuth } from '@clerk/nextjs'

const { getToken } = useAuth()

await getToken({ skipCache: true })

'use client'

import { useAuth } from '@clerk/nextjs'

export const useUser = () => {
  const { isSignedIn, userId, sessionClaims, getToken } = useAuth()

  if (!isSignedIn) return null

  const { email, details } = sessionClaims

  return {
    ...details,
    userId,
    email,
    refresh: async () => {
      await getToken({ skipCache: true })
    },
  }
}