LukeParke/better-auth
1
0
Fork 0
mirror of https://github.com/LukeHagar/better-auth.git synced 2025-12-10 20:37:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: minor improvements to the your-first-plugin guide (#827)

Browse Source
This commit is contained in:
Multinite
2024-12-09 15:33:15 +10:00
committed by GitHub
parent 8fb496f16e
commit 3b97c97e1e
1 changed files with 29 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/content/docs/guides/your-first-plugin.mdx
View File

@@ -15,21 +15,7 @@ This guide assumes you have <Link href="/docs/installation">setup the basics</Li
## Plan your idea
Before beginning, you must know what plugin you intend to create.
<div className="flex gap-2 items-center">
<span>In this guide, we’ll create a **birthday plugin**</span>
<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="lucide lucide-cake">
<path d="M20 21v-8a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8"/>
<path d="M4 16s.5-1 2-1 2.5 2 4 2 2.5-2 4-2 2.5 2 4 2 2-1 2-1"/>
<path d="M2 21h20"/>
<path d="M7 8v3"/>
<path d="M12 8v3"/>
<path d="M17 8v3"/>
<path d="M7 4h.01"/>
<path d="M12 4h.01"/>
<path d="M17 4h.01"/>
</svg>
<span> to keep track of user birth dates.</span>
</div>
In this guide, we’ll create a **birthday plugin** to keep track of user birth dates.
</Step>
<Step>
@@ -68,9 +54,9 @@ Although this does nothing, you have technically just made yourself your first p
<Step>
### Defining a schema
In order to save each user's birthday data, we must create a schema on top of the `user` model.
In order to save each user’s birthday data, we must create a schema on top of the `user` model.
By creating a schema here, this also allows <Link href="/docs/concepts/cli">Better-Auth's CLI</Link> to generate the schemas required to update your database.
By creating a schema here, this also allows <Link href="/docs/concepts/cli">Better-Auth’s CLI</Link> to generate the schemas required to update your database.
<Callout type="info">
You can learn more about <Link href="/docs/concepts/plugins#schema">plugin schemas here</Link>.
@@ -81,17 +67,17 @@ You can learn more about <Link href="/docs/concepts/plugins#schema">plugin schem
export const birthdayPlugin = () =>
({
id: "birthdayPlugin",
schema: {
user: {
fields: {
birthday: {
type: "date", // string, number, boolean, date
required: true, // if the field should be required on a new record. (default: false)
unique: false, // if the field should be unique. (default: false)
reference: null // if the field is a reference to another table. (default: null)
},
},
},
schema: {// [!code highlight]
user: {// [!code highlight]
fields: {// [!code highlight]
birthday: {// [!code highlight]
type: "date", // string, number, boolean, date // [!code highlight]
required: true, // if the field should be required on a new record. (default: false) // [!code highlight]
unique: false, // if the field should be unique. (default: false) // [!code highlight]
reference: null // if the field is a reference to another table. (default: null) // [!code highlight]
},// [!code highlight]
},// [!code highlight]
},// [!code highlight]
},
} satisfies BetterAuthPlugin);
```
@@ -100,10 +86,10 @@ export const birthdayPlugin = () =>
<Step>
### Authorization logic
For this example guide, we'll setup authentication logic to check and ensure that the user who signs-up is older than 5.
For this example guide, we’ll setup authentication logic to check and ensure that the user who signs-up is older than 5.
But the same concept could be applied for something like verifying users agreeing to the TOS or anything alike.
To do this, we'll utilize <Link href="/docs/concepts/plugins#hooks">Hooks</Link>, which allows us to run code `before` or `after` an action is performed.
To do this, we’ll utilize <Link href="/docs/concepts/plugins#hooks">Hooks</Link>, which allows us to run code `before` or `after` an action is performed.
```ts title="index.ts"
export const birthdayPlugin = () => ({
@@ -131,7 +117,7 @@ In our case we want to match any requests going to the signup path:
}
```
And for our logic, we'll write the following code to check the if user's birthday makes them above 5 years old.
And for our logic, we’ll write the following code to check the if user’s birthday makes them above 5 years old.
```ts title="Imports"
import { APIError } from "better-auth/api";
import { createAuthMiddleware } from "better-auth/plugins";
@@ -155,18 +141,18 @@ import { createAuthMiddleware } from "better-auth/plugins";
**Authorized!** 🔒
We've now successfully written code to ensure authorization for users above 5!
We’ve now successfully written code to ensure authorization for users above 5!
</Step>
<Step>
## Client Plugin
We're close to the finish line! 🏁
We’re close to the finish line! 🏁
Now that we have created our server plugin, the next step is to develop our client plugin.
Since there isn't much frontend APIs going on for this plugin, there isn't much to do!
Since there isn’t much frontend APIs going on for this plugin, there isn’t much to do!
First, let's create our `client.ts` file first:
First, let’s create our `client.ts` file first:
<Files>
<Folder name="birthday-plugin" defaultOpen>
<File name="index.ts" />
@@ -187,9 +173,9 @@ export const birthdayClientPlugin = () => {
} satisfies BetterAuthClientPlugin;
};
```
What we've done is allow the client plugin to infer the types defined by our schema from the server plugin.
What we’ve done is allow the client plugin to infer the types defined by our schema from the server plugin.
And that's it! This is all it takes for the birthday client plugin. 🎂
And that’s it! This is all it takes for the birthday client plugin. 🎂
</Step>
@@ -200,11 +186,11 @@ Both the `client` and `server` plugins are now ready, the last step is to import
### Server initiation
```ts title="server.ts"
import { betterAuth } from "better-auth";
import { birthdayPlugin } from "./birthday-plugin";
import { birthdayPlugin } from "./birthday-plugin";// [!code highlight]
export const auth = betterAuth({
plugins: [
birthdayPlugin(),
birthdayPlugin(),// [!code highlight]
]
});
```
@@ -212,17 +198,17 @@ export const auth = betterAuth({
### Client initiation
```ts title="auth-client.ts"
import { createAuthClient } from "better-auth/client";
import { birthdayClientPlugin } from "./birthday-plugin/client";
import { birthdayClientPlugin } from "./birthday-plugin/client";// [!code highlight]
const authClient = createAuthClient({
plugins: [
birthdayClientPlugin()
birthdayClientPlugin()// [!code highlight]
]
});
```
### Oh yeah, the schemas!
Don't forget to add your `birthday` field to your `user` table model!
Don’t forget to add your `birthday` field to your `user` table model!
Or, use the `generate` <Link href="/docs/concepts/cli#generate">CLI command</Link>:
```bash
@@ -237,7 +223,7 @@ npx @better-auth/cli@latest generate
Congratulations! You’ve successfully created your first ever Better Auth plugin.
We highly recommend you visit our <Link href="/docs/concepts/plugins">plugins documentation</Link> to learn more information.
If you have a plugin you'd like to share with the community, feel free to let us know through
If you have a plugin you’d like to share with the community, feel free to let us know through
our <Link href="https://discord.gg/6jHcdYMzyq">Discord server</Link>,
or through a <Link href="https://github.com/better-auth/better-auth/pulls">pull-request</Link>
and we may add it to the <Link href="/docs/plugins/community-plugins">community-plugins</Link> list!