From 1e2bcf52233e6e1bd3babcb5a7b25979095703d1 Mon Sep 17 00:00:00 2001 From: onmax Date: Fri, 13 Mar 2026 08:18:05 +0100 Subject: [PATCH] feat(docs): add twoslash type hints --- .../1.getting-started/2.configuration.md | 85 +- .../1.getting-started/3.client-setup.md | 42 +- .../1.getting-started/4.type-augmentation.md | 13 +- docs/content/2.core-concepts/2.sessions.md | 31 +- .../2.core-concepts/3.route-protection.md | 75 +- docs/content/3.guides/1.role-based-access.md | 32 +- docs/content/5.api/1.composables.md | 31 +- docs/content/5.api/2.server-utils.md | 96 +- docs/layers/twoslash/nuxt.config.ts | 3 + docs/nuxt.config.ts | 2 +- docs/package.json | 3 +- pnpm-lock.yaml | 2213 ++++++++--------- pnpm-workspace.yaml | 2 + 13 files changed, 1454 insertions(+), 1174 deletions(-) create mode 100644 docs/layers/twoslash/nuxt.config.ts diff --git a/docs/content/1.getting-started/2.configuration.md b/docs/content/1.getting-started/2.configuration.md index 28a9e11d..4bacb2af 100644 --- a/docs/content/1.getting-started/2.configuration.md +++ b/docs/content/1.getting-started/2.configuration.md @@ -149,18 +149,35 @@ Define your authentication logic in `server/auth.config.ts`, including plugins, Use the `defineServerAuth` helper to ensure type safety and access context. It accepts an object or function syntax. -```ts [server/auth.config.ts] -import { defineServerAuth } from '@onmax/nuxt-better-auth/config' +```ts twoslash [server/auth.config.ts] +interface ServerAuthContext { + db: unknown + runtimeConfig: { + public: { + siteUrl?: string + } + } +} + +type ServerAuthConfig = { + emailAndPassword?: { + enabled: boolean + } +} + +declare function defineServerAuth( + config: T | ((ctx: ServerAuthContext) => T) +): (ctx: ServerAuthContext) => T -// Object syntax (simplest) -export default defineServerAuth({ +const objectSyntax = defineServerAuth({ emailAndPassword: { enabled: true } }) -// Function syntax (access context) -export default defineServerAuth((ctx) => ({ +const functionSyntax = defineServerAuth((ctx) => ({ emailAndPassword: { enabled: true } })) + +export default functionSyntax ``` ::note @@ -173,8 +190,26 @@ The module automatically injects `secret` and `baseURL`. You don't need to confi When using the function syntax, `defineServerAuth` callback receives a context object with useful properties: -```ts [server/auth.config.ts] -import { defineServerAuth } from '@onmax/nuxt-better-auth/config' +```ts twoslash [server/auth.config.ts] +interface ServerAuthContext { + db: unknown + runtimeConfig: { + public: { + siteUrl?: string + } + } +} + +type ServerAuthConfig = { + appName?: string + emailAndPassword?: { + enabled: boolean + } +} + +declare function defineServerAuth( + config: T | ((ctx: ServerAuthContext) => T) +): (ctx: ServerAuthContext) => T export default defineServerAuth((ctx) => ({ emailAndPassword: { enabled: true }, @@ -262,9 +297,37 @@ export default defineNuxtModule({ Access sessions from server handlers: -```ts -const { user, session } = await getUserSession(event) -if (!user) throw createError({ statusCode: 401 }) +```ts twoslash [server/api/session.get.ts] +interface H3Event { + headers: HeadersInit +} + +interface AuthUser { + email: string + id: string +} + +interface AuthSession { + id: string +} + +interface AppSession { + session: AuthSession + user: AuthUser +} + +declare function defineEventHandler( + handler: (event: H3Event) => T +): (event: H3Event) => T + +declare function getUserSession(event: H3Event): Promise + +export default defineEventHandler(async (event) => { + const { user, session } = await getUserSession(event) ?? {} + // ^? + + return { user, session } +}) ``` ::callout{icon="i-lucide-arrow-right" to="/getting-started/client-setup"} diff --git a/docs/content/1.getting-started/3.client-setup.md b/docs/content/1.getting-started/3.client-setup.md index fa08165b..3285f208 100644 --- a/docs/content/1.getting-started/3.client-setup.md +++ b/docs/content/1.getting-started/3.client-setup.md @@ -10,16 +10,27 @@ Create `app/auth.config.ts` with a default export using `defineClientAuth`. The `defineClientAuth` helper supports two syntaxes: an object for simple configurations, or a function when you need access to context like the resolved site URL. -```ts [app/auth.config.ts] -import { defineClientAuth } from '@onmax/nuxt-better-auth/config' +```ts twoslash [app/auth.config.ts] +interface ClientAuthContext { + siteUrl: string +} + +type ClientAuthConfig = Record -// Object syntax (simplest) -export default defineClientAuth({}) +declare function defineClientAuth( + config: T | ((ctx: ClientAuthContext) => T) +): (baseURL: string) => T -// Function syntax (access context) -export default defineClientAuth(({ siteUrl }) => ({ - // siteUrl contains the resolved base URL -})) +const objectSyntax = defineClientAuth({}) + +const functionSyntax = defineClientAuth(({ siteUrl }) => { + siteUrl + // ^? + + return {} +}) + +export default functionSyntax ``` ::note @@ -30,9 +41,18 @@ The helper creates a factory function that the module calls with the correct `ba If you added a plugin in your server config (`server/auth.config.ts`), make sure to add its client equivalent here. -```ts [app/auth.config.ts] -import { defineClientAuth } from '@onmax/nuxt-better-auth/config' -import { adminClient } from 'better-auth/client/plugins' +```ts twoslash [app/auth.config.ts] +type ClientAuthConfig = { + plugins?: unknown[] +} + +declare function defineClientAuth( + config: T +): (baseURL: string) => T + +declare function adminClient(): { + name: 'admin' +} export default defineClientAuth({ plugins: [ diff --git a/docs/content/1.getting-started/4.type-augmentation.md b/docs/content/1.getting-started/4.type-augmentation.md index 9e056e0d..4a71a8b4 100644 --- a/docs/content/1.getting-started/4.type-augmentation.md +++ b/docs/content/1.getting-started/4.type-augmentation.md @@ -29,8 +29,19 @@ export default defineServerAuth({ You can immediately access the `role` property in your Vue components: -```vue +```vue twoslash [pages/dashboard.vue]