From 7eb6fec1004b71aba905e79df2439d4991c4e055 Mon Sep 17 00:00:00 2001
From: Taesu <166604494+bytaesu@users.noreply.github.com>
Date: Wed, 23 Sep 2026 04:26:48 +0900
Subject: [PATCH] docs(plugins): document plugin type registration (#11352)

---
 docs/content/docs/concepts/plugins.mdx        | 20 +++++++++++++++++++
 .../content/docs/guides/your-first-plugin.mdx |  4 ++++
 2 files changed, 24 insertions(+)

diff --git a/docs/content/docs/concepts/plugins.mdx b/docs/content/docs/concepts/plugins.mdx
index bae22dc573..252f8bf9e4 100644
--- a/docs/content/docs/concepts/plugins.mdx
+++ b/docs/content/docs/concepts/plugins.mdx
@@ -86,6 +86,26 @@ export const myPlugin = () => {
   You don't have to make the plugin a function, but it's recommended to do so. This way, you can pass options to the plugin and it's consistent with the built-in plugins.
 </Callout>
 
+### Register a plugin type
+
+Reusable plugins can augment `BetterAuthPluginRegistry` so `getPlugin()` returns their exact type. The registry key must match the plugin's `id`:
+
+```ts title="plugin.ts"
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<AuthOptions, Options> {
+    "my-plugin": {
+      creator: typeof myPlugin;
+    };
+  }
+}
+```
+
+This only affects TypeScript. Users must still add the plugin to their `plugins` array at runtime.
+
+<Callout type="info">
+  If you publish the plugin as a separate package, declare `@better-auth/core` as a peer dependency with the same supported version range as `better-auth`.
+</Callout>
+
 ### Endpoints
 
 To add endpoints to the server, you can pass `endpoints` which requires an object with the key being any `string` and the value being an `AuthEndpoint`.
diff --git a/docs/content/docs/guides/your-first-plugin.mdx b/docs/content/docs/guides/your-first-plugin.mdx
index 9b3422f93a..5fed704d7f 100644
--- a/docs/content/docs/guides/your-first-plugin.mdx
+++ b/docs/content/docs/guides/your-first-plugin.mdx
@@ -55,6 +55,10 @@ In this guide, we’ll walk you through the steps of creating your first Better
     ```
 
     Although this does nothing, you have technically just made yourself your first plugin, congratulations! 🎉
+
+    <Callout type="info">
+      Publishing a reusable plugin? <Link href="/docs/concepts/plugins#register-a-plugin-type">Register its server type</Link> so `getPlugin()` can infer its exact return type.
+    </Callout>
   </Step>
 
   <Step>