Angular Better Auth Wrapper

Common errors

• NG0900: Error: NG0900: 'provideBetterAuth' is not a function

  cause Attempting to use `provideBetterAuth` with an Angular version older than 14 (when `ApplicationConfig` and functional providers were introduced) or with an incorrect import.
  fix Ensure your Angular project is at least version 14 (preferably 20+ for full compatibility) and that `provideBetterAuth` is imported correctly from `ngx-better-auth` in `app.config.ts`.

• Error: Can't resolve all parameters for AuthService (?). This typically indicates that it's used in a context where dependency injection is not available.

  cause Attempting to inject `AuthService` in a non-DI context, or without `provideBetterAuth` being correctly configured in the application's providers.
  fix Ensure `AuthService` is injected within an Angular component, service, or directive constructor. Verify that `provideBetterAuth` is included in the `providers` array of your `ApplicationConfig` or module.

• Error: Peer dependency '@angular/core@^16.0.0' not installed.

  cause The installed Angular version does not meet the `ngx-better-auth` peer dependency requirement, which is `>=20.0.0`.
  fix Upgrade your Angular project to version 20 or higher using `ng update @angular/core @angular/cli --allow-dirty`.

• Property 'session' does not exist on type 'AuthService'.

  cause Attempting to access `session` as an observable or direct property instead of a signal, or using an outdated version of `ngx-better-auth` that did not yet use signals.
  fix Access `session` as a signal: `this.authService.session()`. Ensure you are on a version of `ngx-better-auth` that supports signals (e.g., v0.1.0+ for initial signal integration, later versions for expanded use).

Warnings

• breaking Starting from v0.8.0, the library explicitly removed its own type definitions and now relies on types directly from the `better-auth` package. This requires ensuring `better-auth` is correctly installed and its types are available.
  Fix: Ensure `better-auth` is installed (`npm install better-auth`) and its version is compatible (>=1.3.7). Update any manual type imports to reference `better-auth` directly if they were previously coming from `ngx-better-auth`.
• gotcha The `hasRole` guard in v0.10.2 and earlier had issues with comma-separated role strings, potentially leading to incorrect authorization decisions.
  Fix: Update to `ngx-better-auth` v0.10.3 or higher to resolve the issue with comma-separated role strings in the `hasRole` guard.
• gotcha Social sign-in parameters and default `callbackURL` have seen fixes in versions prior to v0.8.3 and v0.8.2 respectively. Older versions might experience issues with social login flows.
  Fix: Ensure you are on `ngx-better-auth` v0.8.3 or newer for robust social sign-in functionality and correct `callbackURL` handling.
• breaking The library is specifically designed for Angular 20+. Using it with older Angular versions will result in peer dependency errors and runtime failures.
  Fix: Upgrade your Angular project to version 20.0.0 or higher to meet the peer dependency requirements.
• gotcha Incorrect configuration of the `baseURL` or `basePath` in `provideBetterAuth` can lead to authentication requests failing with network errors or 404s, as the client won't know where to send requests.
  Fix: Double-check `baseURL` and `basePath` in `provideBetterAuth` against your Better Auth backend configuration. Ensure `environment.apiUrl` resolves to the correct API endpoint.

Install

• npm install ngx-better-auth npm
• yarn add ngx-better-auth yarn
• pnpm add ngx-better-auth pnpm

Imports

• AuthService
  wrong:

  const AuthService = require('ngx-better-auth').AuthService

  correct:

  import { AuthService } from 'ngx-better-auth'

  AuthService is the primary service for core authentication methods and session state.
• provideBetterAuth
  wrong:

  import { provideAuth } from 'ngx-better-auth'

  correct:

  import { provideBetterAuth } from 'ngx-better-auth'

  Used for setting up the Better Auth client in Angular's application config, typically in `app.config.ts`.
• canActivate
  wrong:

  import { AuthGuard } from 'ngx-better-auth'

  correct:

  import { canActivate, redirectUnauthorizedTo } from 'ngx-better-auth'

  Modern Angular functional router guards are provided as utilities like `canActivate`, `redirectUnauthorizedTo`, `hasRole`.
• UsernameService

  import { UsernameService } from 'ngx-better-auth'

  Specific services for Better Auth plugins are available for injection, e.g., `UsernameService` for username-based auth.

Quickstart

This quickstart demonstrates how to configure `ngx-better-auth` using `provideBetterAuth` in an Angular 20+ application's `app.config.ts`, including Better Auth client plugins. It also shows basic usage of `AuthService` within a component to access session status and user information reactively via signals.

import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideBetterAuth } from 'ngx-better-auth';
import { environment } from './environments/environment';
import { usernameClient, twoFactorClient, adminClient } from 'better-auth/client/plugins';
import { routes } from './app.routes';
import { AuthService } from 'ngx-better-auth';
import { Component, inject } from '@angular/core';

const accessControl = { /* ... your access control setup ... */ };
const admin = ['admin'];
const moderator = ['moderator'];
const user = ['user'];

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideBetterAuth({
      baseURL: environment.apiUrl,
      basePath: '/auth',
      plugins: [
        usernameClient(),
        twoFactorClient({
          onTwoFactorRedirect: () => {
            window.location.href = '/two-factor-auth';
          },
        }),
        adminClient({
          ac: accessControl,
          roles: {
            admin,
            moderator,
            user
          }
        })
      ]
    })
  ]
};

// Example component usage
@Component({
    selector: 'app-root',
    standalone: true,
    template: `
        <h1>Welcome, {{ userName() ?? 'Guest' }}</h1>
        <p>Logged In: {{ isLoggedIn() }}</p>
        <button *ngIf="!isLoggedIn()" (click)="signIn()">Sign In</button>
        <button *ngIf="isLoggedIn()" (click)="signOut()">Sign Out</button>
    `
})
export class AppComponent {
    private readonly authService = inject(AuthService);

    isLoggedIn = this.authService.isLoggedIn;
    userName = () => this.authService.session()?.user?.name ?? 'Loading...';

    signIn() { /* ... implementation for sign-in ... */ }
    signOut() {
      this.authService.signOut();
    }
}