Skip to content

Commit 9c75f76

Browse files
CrawlerCodeCrawlerCode
committed
docs: Improved docs
1 parent 9866498 commit 9c75f76

File tree

1 file changed

+159
-148
lines changed

1 file changed

+159
-148
lines changed

‎README.md‎

Lines changed: 159 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,160 @@
1-
# Payload CMS plugin for Auth.js
2-
3-
<a href="https://github.com/CrawlerCode/payload-authjs/actions/workflows/ci.yml"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/CrawlerCode/payload-authjs/ci.yml?style=flat-square&logo=github"></a>
4-
<a href="https://www.npmjs.com/package/payload-authjs"><img alt="NPM Version" src="https://img.shields.io/npm/v/payload-authjs?style=flat-square"></a>
5-
<a href="https://github.com/CrawlerCode/payload-authjs/blob/main/LICENSE"><img alt="NPM License" src="https://img.shields.io/npm/l/payload-authjs?style=flat-square"></a>
6-
<a href="https://www.npmjs.com/package/payload-authjs"><img alt="NPM Downloads" src="https://img.shields.io/npm/dm/payload-authjs?style=flat-square"></a>
7-
8-
9-
A [Payload CMS 3 (beta)](https://payloadcms.com) plugin for integrating [Auth.js 5 (beta)](https://authjs.dev).
10-
11-
> ⚠ This plugin is in beta and under construction.
12-
> Payload CMS 3 and Auth.js 5 are also in beta. Use at your own risk.
13-
14-
## Installation
15-
16-
Install the plugin using any JavaScript package manager like PNPM, NPM, or Yarn:
17-
18-
19-
```bash
20-
pnpm i payload-authjs
21-
```
22-
23-
Add the `authjsPlugin` in your Payload configuration file:
24-
25-
```ts
26-
// payload.config.ts
27-
import { authjsPlugin } from "payload-authjs";
28-
import { authConfig } from "./auth.config";
29-
30-
export const config = buildConfig({
31-
plugins: [
32-
authjsPlugin({
33-
authjsConfig: authConfig,
34-
}),
35-
]
36-
});
37-
```
38-
39-
Wrap your Auth.js configuration with the `withPayload` function before creating the NextAuth instance:
40-
41-
```ts
42-
// auth.ts
43-
import payloadConfig from "@payload-config";
44-
import NextAuth from "next-auth";
45-
import { withPayload } from "payload-authjs";
46-
import { authConfig } from "./auth.config";
47-
48-
export const { handlers, signIn, signOut, auth } = NextAuth(
49-
withPayload(authConfig, {
50-
payloadConfig,
51-
}),
52-
);
53-
```
54-
55-
> ⚠ Make sure you define your `authConfig` in a separate file than where you use the `withPayload` function to avoid circular dependencies.
56-
57-
**And that's it! Now you can sign-in via Auth.js and you are automatically authenticated in Payload CMS. Nice 🎉**
58-
59-
---
60-
61-
## Customizing
62-
63-
You don't need to create a collection for users. This plugin automatically creates a collection with the slug `users`.
64-
65-
But if you want to customize the users collection, you can create a collection with the slug `users` and add the fields you need.
66-
67-
```ts
68-
// users.ts
69-
import type { CollectionConfig } from "payload";
70-
71-
const Users: CollectionConfig = {
72-
slug: "users",
73-
fields: [
74-
{
75-
name: "roles",
76-
type: "json",
77-
},
78-
],
79-
};
80-
81-
export default Users;
82-
```
83-
84-
Next, you need to extend the user object returned by your Auth.js provider. You can do this like this example:
85-
86-
```ts
87-
const authConfig: NextAuthConfig = {
88-
providers: [
89-
github({
90-
profile(profile) {
91-
return {
92-
id: profile.id.toString(),
93-
name: profile.name,
94-
email: profile.email,
95-
image: profile.avatar_url,
96-
roles: ["user"], // <-- Extend the user object with a custom field
97-
};
98-
},
99-
}),
100-
],
101-
...
102-
};
103-
```
104-
105-
⚠ 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 `updateUserOnSignIn` option in the `withPayload` function:
106-
107-
```ts
108-
// auth.ts
109-
export const { handlers, signIn, signOut, auth } = NextAuth(
110-
withPayload(authConfig, {
111-
payloadConfig,
112-
updateUserOnSignIn: true, // <-- Update the user on every sign-in
113-
}),
114-
);
115-
```
116-
117-
Now you could access your custom field, e.g. in the access control operations:
118-
119-
```ts
120-
const Examples: CollectionConfig = {
121-
slug: "examples",
122-
access: {
123-
read: ({ req: { user } }) => {
124-
return user?.roles?.includes("user") ?? false; // <-- Check if the user has the role "user"
125-
},
126-
},
127-
fields: [
128-
...
129-
],
130-
};
131-
```
132-
133-
### Utility functions
134-
135-
This plugin also export a utility function to get the current payload user
136-
137-
```tsx
138-
// ServerComponentExample.tsx
139-
const ServerComponentExample = async () => {
140-
const payloadUser = await getPayloadUser();
141-
142-
return (
143-
<div>
144-
<h3>Payload CMS User</h3>
145-
<div>{JSON.stringify(payloadUser)}</div>
146-
</div>
147-
);
148-
};
1+
# Payload CMS plugin for Auth.js
2+
3+
<a href="https://github.com/CrawlerCode/payload-authjs/actions/workflows/ci.yml"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/CrawlerCode/payload-authjs/ci.yml?style=flat-square&logo=github"></a>
4+
<a href="https://www.npmjs.com/package/payload-authjs"><img alt="NPM Version" src="https://img.shields.io/npm/v/payload-authjs?style=flat-square"></a>
5+
<a href="https://github.com/CrawlerCode/payload-authjs/blob/main/LICENSE"><img alt="NPM License" src="https://img.shields.io/npm/l/payload-authjs?style=flat-square"></a>
6+
<a href="https://www.npmjs.com/package/payload-authjs"><img alt="NPM Downloads" src="https://img.shields.io/npm/dm/payload-authjs?style=flat-square"></a>
7+
8+
A [Payload CMS 3 (beta)](https://payloadcms.com) plugin for integrating [Auth.js 5 (beta)](https://authjs.dev).
9+
10+
> ⚠ This plugin is in beta and under construction.
11+
> Payload CMS 3 and Auth.js 5 are also in beta.
12+
13+
## Installation
14+
15+
Install the plugin using any JavaScript package manager like PNPM, NPM, or Yarn:
16+
17+
```bash
18+
pnpm i payload-authjs
19+
```
20+
21+
Fist of all, setup Auth.js like you would do in a Next.js application. You can follow the [Auth.js documentation](https://authjs.dev/getting-started/installation?framework=Next.js).
22+
23+
> ⚠ 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. ⚠
24+
25+
```ts
26+
// auth.config.ts
27+
import github from "next-auth/providers/github";
28+
29+
export const authConfig: NextAuthConfig = {
30+
providers: [
31+
github, // <-- Add your provider here
32+
],
33+
};
34+
```
35+
36+
Wrap your Auth.js configuration with the `withPayload` function before creating the NextAuth instance:
37+
38+
```ts
39+
// auth.ts
40+
import payloadConfig from "@payload-config";
41+
import NextAuth from "next-auth";
42+
import { withPayload } from "payload-authjs";
43+
import { authConfig } from "./auth.config"; // ⚠ Import the config from a separate file
44+
45+
export const { handlers, signIn, signOut, auth } = NextAuth(
46+
withPayload(authConfig, {
47+
payloadConfig,
48+
}),
49+
);
50+
```
51+
52+
Add the `authjsPlugin` in your Payload configuration file:
53+
54+
```ts
55+
// payload.config.ts
56+
import { authjsPlugin } from "payload-authjs";
57+
import { authConfig } from "./auth.config";
58+
59+
export const config = buildConfig({
60+
plugins: [
61+
authjsPlugin({
62+
authjsConfig: authConfig,
63+
}),
64+
],
65+
});
66+
```
67+
68+
**And that's it! Now you can sign-in via Auth.js and you are automatically authenticated in Payload CMS. Nice 🎉**
69+
70+
---
71+
72+
## Customizing
73+
74+
You don't need to create a collection for users. This plugin automatically creates a collection with the slug `users`.
75+
76+
But if you want to customize the users collection, you can create a collection with the slug `users` and add the fields you need.
77+
78+
```ts
79+
// users.ts
80+
import type { CollectionConfig } from "payload";
81+
82+
const Users: CollectionConfig = {
83+
slug: "users",
84+
fields: [
85+
{
86+
name: "roles",
87+
type: "json",
88+
},
89+
],
90+
};
91+
92+
export default Users;
93+
```
94+
95+
Next, you need to extend the user object returned by your Auth.js provider. You can do this like this example:
96+
97+
```ts
98+
const authConfig: NextAuthConfig = {
99+
providers: [
100+
github({
101+
profile(profile) {
102+
return {
103+
id: profile.id.toString(),
104+
name: profile.name,
105+
email: profile.email,
106+
image: profile.avatar_url,
107+
roles: ["user"], // <-- Extend the user object with a custom field
108+
};
109+
},
110+
}),
111+
],
112+
...
113+
};
114+
```
115+
116+
⚠ 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 `updateUserOnSignIn` option in the `withPayload` function:
117+
118+
```ts
119+
// auth.ts
120+
export const { handlers, signIn, signOut, auth } = NextAuth(
121+
withPayload(authConfig, {
122+
payloadConfig,
123+
updateUserOnSignIn: true, // <-- Update the user on every sign-in
124+
}),
125+
);
126+
```
127+
128+
Now you could access your custom field, e.g. in the access control operations:
129+
130+
```ts
131+
const Examples: CollectionConfig = {
132+
slug: "examples",
133+
access: {
134+
read: ({ req: { user } }) => {
135+
return user?.roles?.includes("user") ?? false; // <-- Check if the user has the role "user"
136+
},
137+
},
138+
fields: [
139+
...
140+
],
141+
};
142+
```
143+
144+
### Utility functions
145+
146+
This plugin also export a utility function to get the current payload user
147+
148+
```tsx
149+
// ServerComponentExample.tsx
150+
const ServerComponentExample = async () => {
151+
const payloadUser = await getPayloadUser();
152+
153+
return (
154+
<div>
155+
<h3>Payload CMS User</h3>
156+
<div>{JSON.stringify(payloadUser)}</div>
157+
</div>
158+
);
159+
};
149160
```

0 commit comments

Comments
 (0)