Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AuthService
✓ import { AuthService } from 'ngx-better-auth'
✗ const AuthService = require('ngx-better-auth').AuthService
AuthService is the primary service for core authentication methods and session state.
provideBetterAuth
✓ import { provideBetterAuth } from 'ngx-better-auth'
✗ import { provideAuth } from 'ngx-better-auth'
Used for setting up the Better Auth client in Angular's application config, typically in `app.config.ts`.
canActivate
✓ import { canActivate, redirectUnauthorizedTo } from 'ngx-better-auth'
✗ import { AuthGuard } 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.
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();
}
}
Debug
Known issues
breakingStarting 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.fixEnsure `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`.
affects: >=0.8.0
gotchaThe `hasRole` guard in v0.10.2 and earlier had issues with comma-separated role strings, potentially leading to incorrect authorization decisions.fixUpdate to `ngx-better-auth` v0.10.3 or higher to resolve the issue with comma-separated role strings in the `hasRole` guard.
affects: <=0.10.2
gotchaSocial 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.fixEnsure you are on `ngx-better-auth` v0.8.3 or newer for robust social sign-in functionality and correct `callbackURL` handling.
affects: <0.8.3
breakingThe library is specifically designed for Angular 20+. Using it with older Angular versions will result in peer dependency errors and runtime failures.fixUpgrade your Angular project to version 20.0.0 or higher to meet the peer dependency requirements.
affects: <20.0.0 (Angular)
gotchaIncorrect 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.fixDouble-check `baseURL` and `basePath` in `provideBetterAuth` against your Better Auth backend configuration. Ensure `environment.apiUrl` resolves to the correct API endpoint.
affects: >=0.1.0
Errors
Common errors & fixes
NG0900: Error: NG0900: 'provideBetterAuth' is not a function
Attempting to use `provideBetterAuth` with an Angular version older than 14 (when `ApplicationConfig` and functional providers were introduced) or with an incorrect import.
fixEnsure 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.
Attempting to inject `AuthService` in a non-DI context, or without `provideBetterAuth` being correctly configured in the application's providers.
fixEnsure `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.
The installed Angular version does not meet the `ngx-better-auth` peer dependency requirement, which is `>=20.0.0`.
fixUpgrade 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'.
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.
fixAccess `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).
Audit
Dependencies
@angular/commonrequiredCore Angular dependency for common services and directives.
@angular/corerequiredFundamental Angular dependency for component architecture and DI.
@angular/formsrequiredRequired for forms functionality, potentially used in authentication UIs.
@angular/routerrequiredEssential for route guards and navigation.
better-authrequiredThe core authentication client library that ngx-better-auth wraps.
rxjsrequiredReactive programming library used extensively by Angular and for observable-based patterns.