Getting Started

Type Augmentation

Learn how the module automatically infers types from your configuration.

Prompt

Set up type augmentation for @onmax/nuxt-better-auth plugins.

- Types are automatically inferred from plugins in `server/auth.config.ts` — no extra config needed
- For manual augmentation, create `nuxt-better-auth.d.ts` next to `nuxt.config.ts`
- Import `#nuxt-better-auth` and declare module to extend `AuthUser` or `AuthSession` interfaces
- If types don't update: restart TS server, run `npx nuxi prepare`, check config for syntax errors
- Ensure `.d.ts` files are included by TypeScript (`tsconfig.json` include or `/// <reference>`)

Read more: https://better-auth.nuxt.dev/raw/getting-started/type-augmentation.md
Source: https://github.com/nuxt-modules/better-auth

When you add Better Auth plugins that extend the user or session objects, TypeScript needs to know about these new fields. The module automatically infers types from your configuration, but you can also augment types manually.

Automatic Type Inference

Types are automatically inferred when you:

Add plugins to server/auth.config.ts
Use the module's type exports

No additional configuration is needed for most cases.

Example:

If you add the admin plugin:

server/auth.config.ts

import { admin } from 'better-auth/plugins'
import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth({
  plugins: [admin()]
})

You can immediately access the role property in your Vue components:

<script setup lang="ts">
const { user } = useUserSession()

// user.value.role is fully typed!
if (user.value?.role === 'admin') {
  // ...
}
</script>

Manual Type Augmentation

Manually extend types when automatic inference doesn't work:

Create a file next to nuxt.config.ts, for example nuxt-better-auth.d.ts (or nuxt.d.ts):

nuxt-better-auth.d.ts

import '#nuxt-better-auth'

declare module '#nuxt-better-auth' {
  interface AuthUser {
    customField?: string
  }
}

The #nuxt-better-auth virtual module exports AuthUser and AuthSession interfaces that reflect your current configuration.

If you prefer putting declaration files under types/, make sure they are included by TypeScript in your project:

Add them to tsconfig.json include, or
Reference them from a root nuxt.d.ts file (e.g. /// <reference path="./types/auth.d.ts" />).

Otherwise, Nuxt/TypeScript may not pick them up and your augmentation will have no effect.

Troubleshooting

Types not updating?

Restart your IDE's TypeScript server
Run npx nuxi prepare to regenerate types
Check that your server/auth.config.ts has no syntax errors
Ensure your augmentation .d.ts file is included by TypeScript (see note above)