nuxthub-better-auth Template

When building with this template, follow these Nuxt-specific patterns:

• Session Management: Use useUserSession() to access the shared, SSR-hydrated session. Do not copy the session into another store or a module-level ref.
• Data Fetching: The linked-account useFetch automatically forwards cookies during SSR and uses a user-specific key.
• Server-side Access Control: When creating private API handlers, use requireUserSession(event) to enforce access on the server.
• UI State: Use local ref state for form inputs. Use action composables to manage pending and error states.

To run the project on your local machine using Node 22.19+, 24.11+, or 26+ and Corepack:

1. Setup Environment Variables: Copy .env.example to .env.
2. Generate Auth Secret: Generate a 32-byte hex string and assign it to NUXT_BETTER_AUTH_SECRET in your .env file.

   node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

3. Configure Local URL: Ensure NUXT_PUBLIC_SITE_URL=http://localhost:3000 is set.
4. Initialize Database: Use local SQLite by leaving Cloudflare and Turso variables empty.
5. Start Development:

   corepack enable
   pnpm install
   pnpm db:migrate
   pnpm dev

Local database is stored in .data/db/sqlite.db.

cp .env.example .env
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
corepack enable
pnpm install
pnpm db:migrate
pnpm dev

To provide quick-login buttons for a disposable hosted demo:

1. Create Demo Users: Manually create user@nuxthub.demo and admin@nuxthub.demo via the sign-up form using the password nuxthub-demo.
2. Set Admin Role: Update the role field to admin for the admin account in the database.
3. Enable Flag: Set NUXT_PUBLIC_DEMO_ACCOUNTS_ENABLED=true in your runtime environment.

Warning: This flag only shows the buttons; it does not create the accounts. Do not use this for real applications.

To run the application in a Node environment using a local SQLite file:

1. Migrate: pnpm db:migrate
2. Build: pnpm build:node
3. Run: node --env-file=.env .output/server/index.mjs

Requirements:

• Set NUXT_PUBLIC_SITE_URL to your HTTPS origin.
• Persist the .data/db/sqlite.db file across releases.
• Run behind a trusted reverse proxy that forwards a reliable client IP for rate limiting.

To enable GitHub authentication:

1. Create GitHub OAuth App: Set the local callback URL to http://localhost:3000/api/auth/callback/github (or your production HTTPS equivalent).
2. Configure Environment Variables:
   • NUXT_GITHUB_CLIENT_ID
   • NUXT_GITHUB_CLIENT_SECRET
   • NUXT_PUBLIC_GITHUB_AUTH_ENABLED=true

Security Note: Store the client secret as a Worker secret or a private Vercel environment variable. Never include it in public runtime config. If migrating from a previous deployment, rename GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to the NUXT_ prefixed versions.

Use defineClientAuth from @nuxtjs/better-auth/config to configure the client-side authentication instance. This function accepts an options object where you can register plugins to extend the client's capabilities, such as handling anonymous users or managing role-based access control (RBAC).

import { defineClientAuth } from '@nuxtjs/better-auth/config'
import { adminClient, anonymousClient } from 'better-auth/client/plugins'
import { demoAccess, demoAdminRole, demoUserRole } from '#shared/auth-access'

export default defineClientAuth({
  plugins: [
    anonymousClient(),
    adminClient({
      ac: demoAccess,
      roles: {
        user: demoUserRole,
        admin: demoAdminRole,
      },
    }),
  ],
})

Use the following commands to verify the project integrity during development:

pnpm lint
pnpm typecheck
pnpm test
pnpm build:node

The admin plugin from better-auth/plugins can be added to the plugins array in your defineServerAuth configuration. It allows you to manage administrative privileges and roles.

Key options for the admin plugin:

• ac: Access control configuration (e.g., demoAccess).
• roles: An object mapping role names (like user or admin) to their respective role definitions (e.g., demoUserRole, demoAdminRole).

import { admin } from 'better-auth/plugins'

// Inside defineServerAuth plugins array:
admin({
  ac: demoAccess,
  roles: {
    user: demoUserRole,
    admin: demoAdminRole,
  },
})

The adminClient plugin allows for administrative capabilities on the client side. It requires an options object with the following keys:

• ac: An access control configuration (e.g., demoAccess).
• roles: An object mapping role names to their respective role definitions (e.g., { user: demoUserRole, admin: demoAdminRole }).

adminClient({
  ac: demoAccess,
  roles: {
    user: demoUserRole,
    admin: demoAdminRole,
  },
})