docs: Add "Getting the payload session" section & improved some other wordings

CrawlerCode · CrawlerCode · commit f911249fd8bd · 2025-02-09T21:13:59.000+01:00
diff --git a/packages/payload-authjs/README.md b/packages/payload-authjs/README.md
@@ -9,17 +9,25 @@
 
 A [Payload CMS 3](https://payloadcms.com) plugin for integrating [Auth.js 5 (beta)](https://authjs.dev).
 
-> ⚠ This plugin and Auth.js is in beta and may have some bugs. Please report any issues you find.
+> ⚠ This plugin and Auth.js 5 is in beta and may have some bugs. Please report any issues you find.
+
+# ⚡ How it works
+
+This plugin
+
+- creates a `users` collection in Payload CMS.
+- use an custom [Database Adapter](https://authjs.dev/getting-started/database) for Auth.js to store the users in the Payload CMS database.
+- use a custom [Auth Strategy](https://payloadcms.com/docs/authentication/custom-strategies) for Payload CMS to retrieve the session from Auth.js.
 
 # ⚙️ Installation / Setup
 
-Install the plugin using any JavaScript package manager like PNPM, NPM, or Yarn:
+Install the plugin using any JavaScript package manager such as PNPM, NPM, or Yarn:
 
 ```bash
 pnpm i payload-authjs
 ```
 
-Fist of all, setup Auth.js like you would do in a Next.js application. You can follow the [Auth.js guide](https://authjs.dev/getting-started/installation?framework=Next.js).
+First of all, this plugin only integrates Auth.js into Payload CMS by getting the user session from Auth.js. It doesn't handle the Auth.js stuff. First, you need to setup Auth.js before you can use this plugin. You can follow the [Auth.js guide](https://authjs.dev/getting-started/installation?framework=Next.js).
 
 > ⚠ Make sure you define your config in a separate file (e.g. `auth.config.ts`) than where you create the NextAuth instance (e.g. `auth.ts`) to avoid circular dependencies. ⚠
 
@@ -34,7 +42,9 @@ export const authConfig: NextAuthConfig = {
 };
 ```
 
-Wrap your Auth.js configuration with the `withPayload` function before creating the NextAuth instance:
+Once you have configured Auth.js, you can integrate it with Payload CMS.
+
+To do this, wrap your Auth.js configuration with the `withPayload` function before creating the NextAuth instance:
 
 ```ts
 // auth.ts
@@ -50,7 +60,7 @@ export const { handlers, signIn, signOut, auth } = NextAuth(
 );
 ```
 
-Add the `authjsPlugin` in your Payload configuration file:
+And add the `authjsPlugin` to your Payload configuration file:
 
 ```ts
 // payload.config.ts
@@ -68,10 +78,145 @@ export const config = buildConfig({
 
 **And that's it! Now you can sign-in via Auth.js and you are automatically authenticated in Payload CMS. Nice 🎉**
 
-> You don't need to create a collection for users. This plugin automatically creates a collection with the slug `users`.
+> _You don't need to create a users collection. This plugin automatically creates a collection with the slug `users`._
 
 ---
 
+# 🪄 Getting the payload session
+
+This plugin also provides some utility functions to get the current payload session/user within your Next.js application.
+
+## Server side (`getPayloadSession`)
+
+Instead of using the [`auth`](https://authjs.dev/getting-started/session-management/get-session?framework=next-js) function of Auth.js, you can use the `getPayloadSession` function to get the current session in the server-side code (e.g. in RSC or API routes):
+
+```tsx
+// ServerComponentExample.tsx
+import { getPayloadSession } from "payload-authjs";
+
+const ServerComponentExample = async () => {
+  const session = await getPayloadSession();
+
+  return (
+    <>
+      <h3>Payload CMS User:</h3>
+      <pre>{JSON.stringify(session?.user)}</pre>
+    </>
+  );
+};
+```
+
+## Client side (`usePayloadSession`)
+
+Instead of using the [`useSession`](https://authjs.dev/getting-started/session-management/get-session?framework=next-js-client) hook of Auth.js, you can use the `usePayloadSession` hook to get the current session in the client-side code:
+
+Before you can use the `usePayloadSession` hook, you need to wrap your app with the `PayloadSessionProvider` on the server-side:
+
+```tsx
+// layout.tsx
+import { PayloadSessionProvider } from "payload-authjs";
+
+const Layout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  return (
+    <html lang="en">
+      <body>
+        <PayloadSessionProvider>{children}</PayloadSessionProvider>
+      </body>
+    </html>
+  );
+};
+
+export default Layout;
+```
+
+You are now ready to use the `usePayloadSession` hook in your client-side code:
+
+```tsx
+// ClientComponentExample.tsx
+"use client";
+
+import { usePayloadSession } from "payload-authjs/client";
+
+export const ClientComponentExample = () => {
+  const { session } = usePayloadSession();
+
+  return (
+    <>
+      <h3>Payload CMS User:</h3>
+      <pre>{JSON.stringify(session?.user)}</pre>
+    </>
+  );
+};
+```
+
+## Within Payload CMS
+
+<details>
+  <summary>Click to expand</summary>
+
+### Within the Payload admin panel (`useAuth`)
+
+If you want to access the current user in the Payload admin panel e.g. in a custom component. You can use the [`useAuth`](https://payloadcms.com/docs/admin/hooks#useauth) hook from Payload CMS:
+
+```tsx
+"use client";
+
+import { Banner, useAuth } from "@payloadcms/ui";
+import { type User } from "payload/generated-types";
+
+export const CustomAdminComponent = () => {
+  const { user } = useAuth<User>();
+
+  if (!user) {
+    return null;
+  }
+
+  return <Banner type="success">Hi, {user.name}</Banner>;
+};
+```
+
+### Inside access control operations (`req.user`)
+
+Simply use the [`req.user`](https://payloadcms.com/docs/access-control/overview) object to determine the current user:
+
+```ts
+const Examples: CollectionConfig = {
+  slug: "examples",
+  access: {
+    read: ({ req: { user } }) => {
+      return Boolean(user) // <-- Check if the user is authenticated
+    },
+  },
+  fields: [
+    ...
+  ],
+};
+```
+
+### Inside custom endpoints (`req.user`)
+
+Simply use the [`req.user`](https://payloadcms.com/docs/rest-api/overview#custom-endpoints) object to determine the current user:
+
+```ts
+const Examples: CollectionConfig = {
+  slug: "examples",
+  fields: [
+    ...
+  ],
+  endpoints: [
+    {
+      method: "get",
+      path: "/example",
+      handler: (req) => {
+        return Response.json(req.user); // <-- Return the user object
+      },
+    },
+  ],
+};
+```
+
+</details>
+
 # 🛠️ Advanced usage / Customization
 
 If you want to customize the users collection, you can create a collection with the slug `users` and add your customizations there.
@@ -89,7 +234,7 @@ const Users: CollectionConfig = {
 <details>
   <summary>Click to expand</summary>
 
-You can customize the existing fields in the users collection by adding the field to the collection and modifying the field. The fields will be merged together.
+You can customize the existing fields in the users collection by adding the field to the collection and modifying the field. The fields are merged together.
 
 ```ts
 // users.ts
@@ -177,12 +322,12 @@ const authConfig: NextAuthConfig = {
 };
 ```
 
-> ⚠ Keep in mind that Auth.js doesn't update the user after the first sign-in. If you want to update the user on every sign-in, you can use the `signIn` event. (See [Events](#events))
+> ⚠ Note that Auth.js doesn't update the user after the first sign-in. If you want to update the user on every sign-in, you can use the `signIn` event. (See [Events](#events))
 
 ### 2. Virtual fields (jwt session only)
 
 If you are using the Auth.js `jwt` session strategy (it's the default), you can use a [virtual field](https://payloadcms.com/docs/fields/overview#virtual-fields) to add additional data that should not be stored in the database.
-This plugin extracts the virtual fields from your Auth.js jwt session and adds them to the user object.
+This plugin extracts the virtual fields from your Auth.js jwt session (if available) and adds them to the user object.
 
 For example, you could add a `roles` field to the users collection:
 
@@ -204,13 +349,16 @@ const Users: CollectionConfig = {
 };
 ```
 
-Next, you need to extend your Auth.js session with your field. You can do this as shown in this example:
+This plugin can only get the virtual fields, if **they are included in the Auth.js session**. So you need to extend your Auth.js token and session with your field.
+
+You can do this as shown in this example:
 
 ```ts
 // auth.config.ts
 const authConfig: NextAuthConfig = {
   callbacks: {
     jwt: ({ token, trigger }) => {
+      // Add the virtual field to the token only on signIn/signUp (jwt callback will be called multiple times)
       if (trigger === "signIn" || trigger === "signUp") {
         token.roles = ["example-role"]; // <-- Add your virtual field to the token
       }
@@ -227,13 +375,13 @@ const authConfig: NextAuthConfig = {
 };
 ```
 
-At this point, you can implement your own logic to extend the session. E.g. extract from profile, fetch from a server, or something else.
+At this point, you can implement your own logic to extend the session. For example extract from profile, fetch from a server, or something else.
 
 _More information about extending your session can be found in the [Auth.js documentation](https://authjs.dev/guides/extending-the-session)._
 
-### Use custom fields
+### Using custom fields
 
-Now you could access your custom field, e.g. in the access control operations or somewhere else:
+Now you can access your custom field, e.g. in the access control operations or elsewhere:
 
 ```ts
 const Examples: CollectionConfig = {
@@ -269,7 +417,7 @@ _More information about typescript can be found in the [Auth.js documentation](h
 
 ## 🎉 Events
 
-Auth.js emits some [events](https://authjs.dev/reference/nextjs#events) that you can listen to. This plugin extends the events with additional parameters like the `adapter` and `payload` instance.
+Auth.js emits some [events](https://authjs.dev/reference/nextjs#events) that you can listen to. This plugin extends the events with additional parameters such as the `adapter` and `payload` instance.
 
 _More information about the events can be found in the [Auth.js documentation](https://authjs.dev/reference/nextjs#events)._
 
@@ -284,7 +432,7 @@ The following events are available:
 
 ### `signIn` Event
 
-The `signIn` event is emitted when a user successfully signs in. For example, you could use this event to update the user's name on every sign-in:
+The `signIn` event is fired when a user successfully signs in. For example, you could use this event to update the user's name on every sign-in:
 
 ```ts
 // auth.ts
@@ -308,21 +456,3 @@ export const { handlers, signIn, signOut, auth } = NextAuth(
   }),
 );
 ```
-
-## 📐 Utility functions
-
-This plugin also exports a utility function to get the current payload user in the server-side:
-
-```tsx
-// ServerComponentExample.tsx
-const ServerComponentExample = async () => {
-  const payloadUser = await getPayloadUser();
-
-  return (
-    <div>
-      <h3>Payload CMS User</h3>
-      <div>{JSON.stringify(payloadUser)}</div>
-    </div>
-  );
-};
-```
