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>`)

Use this page when Better Auth plugins or custom fields add properties such as role, plan, or teamRole and you want those fields available everywhere the module exposes auth types.

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

If your custom fields are missing:

restart the Nuxt dev server
restart the TypeScript server in your editor
confirm server/auth.config.ts exports defineServerAuth(...)
confirm your plugin or custom field actually changes the Better Auth user or session shape

For the public type surface, see API types.

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)