{"id":16736,"library":"ngx-better-auth","title":"Angular Better Auth Wrapper","description":"ngx-better-auth is an Angular 20+ wrapper library designed to integrate with the Better Auth authentication system. It provides a reactive approach to session management, leveraging Angular's signal primitives for real-time session status (`session`, `isLoggedIn`). The library offers a clean dependency injection setup using observables and includes modern Angular guards (`canActivate`, `hasRole`) for route protection, ensuring a streamlined development experience for authentication flows. Currently at version `0.10.3`, it maintains a regular release cadence with frequent bug fixes and feature enhancements, closely tracking Angular and better-auth major versions. Its key differentiator is the direct integration with Better Auth's plugin ecosystem and a focus on leveraging modern Angular features like signals for session state.","status":"active","version":"0.10.3","language":"javascript","source_language":"en","source_url":"https://github.com/thomasorgeval/ngx-better-auth","tags":["javascript","angular","authentication","auth","better-auth","ngx","typescript"],"install":[{"cmd":"npm install ngx-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add ngx-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add ngx-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Angular dependency for common services and directives.","package":"@angular/common","optional":false},{"reason":"Fundamental Angular dependency for component architecture and DI.","package":"@angular/core","optional":false},{"reason":"Required for forms functionality, potentially used in authentication UIs.","package":"@angular/forms","optional":false},{"reason":"Essential for route guards and navigation.","package":"@angular/router","optional":false},{"reason":"The core authentication client library that ngx-better-auth wraps.","package":"better-auth","optional":false},{"reason":"Reactive programming library used extensively by Angular and for observable-based patterns.","package":"rxjs","optional":false}],"imports":[{"note":"AuthService is the primary service for core authentication methods and session state.","wrong":"const AuthService = require('ngx-better-auth').AuthService","symbol":"AuthService","correct":"import { AuthService } from 'ngx-better-auth'"},{"note":"Used for setting up the Better Auth client in Angular's application config, typically in `app.config.ts`.","wrong":"import { provideAuth } from 'ngx-better-auth'","symbol":"provideBetterAuth","correct":"import { provideBetterAuth } from 'ngx-better-auth'"},{"note":"Modern Angular functional router guards are provided as utilities like `canActivate`, `redirectUnauthorizedTo`, `hasRole`.","wrong":"import { AuthGuard } from 'ngx-better-auth'","symbol":"canActivate","correct":"import { canActivate, redirectUnauthorizedTo } from 'ngx-better-auth'"},{"note":"Specific services for Better Auth plugins are available for injection, e.g., `UsernameService` for username-based auth.","symbol":"UsernameService","correct":"import { UsernameService } from 'ngx-better-auth'"}],"quickstart":{"code":"import { ApplicationConfig, importProvidersFrom } from '@angular/core';\nimport { provideRouter } from '@angular/router';\nimport { provideBetterAuth } from 'ngx-better-auth';\nimport { environment } from './environments/environment';\nimport { usernameClient, twoFactorClient, adminClient } from 'better-auth/client/plugins';\nimport { routes } from './app.routes';\nimport { AuthService } from 'ngx-better-auth';\nimport { Component, inject } from '@angular/core';\n\nconst accessControl = { /* ... your access control setup ... */ };\nconst admin = ['admin'];\nconst moderator = ['moderator'];\nconst user = ['user'];\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideRouter(routes),\n    provideBetterAuth({\n      baseURL: environment.apiUrl,\n      basePath: '/auth',\n      plugins: [\n        usernameClient(),\n        twoFactorClient({\n          onTwoFactorRedirect: () => {\n            window.location.href = '/two-factor-auth';\n          },\n        }),\n        adminClient({\n          ac: accessControl,\n          roles: {\n            admin,\n            moderator,\n            user\n          }\n        })\n      ]\n    })\n  ]\n};\n\n// Example component usage\n@Component({\n    selector: 'app-root',\n    standalone: true,\n    template: `\n        <h1>Welcome, {{ userName() ?? 'Guest' }}</h1>\n        <p>Logged In: {{ isLoggedIn() }}</p>\n        <button *ngIf=\"!isLoggedIn()\" (click)=\"signIn()\">Sign In</button>\n        <button *ngIf=\"isLoggedIn()\" (click)=\"signOut()\">Sign Out</button>\n    `\n})\nexport class AppComponent {\n    private readonly authService = inject(AuthService);\n\n    isLoggedIn = this.authService.isLoggedIn;\n    userName = () => this.authService.session()?.user?.name ?? 'Loading...';\n\n    signIn() { /* ... implementation for sign-in ... */ }\n    signOut() {\n      this.authService.signOut();\n    }\n}","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Update to `ngx-better-auth` v0.10.3 or higher to resolve the issue with comma-separated role strings in the `hasRole` guard.","message":"The `hasRole` guard in v0.10.2 and earlier had issues with comma-separated role strings, potentially leading to incorrect authorization decisions.","severity":"gotcha","affected_versions":"<=0.10.2"},{"fix":"Ensure you are on `ngx-better-auth` v0.8.3 or newer for robust social sign-in functionality and correct `callbackURL` handling.","message":"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.","severity":"gotcha","affected_versions":"<0.8.3"},{"fix":"Upgrade your Angular project to version 20.0.0 or higher to meet the peer dependency requirements.","message":"The library is specifically designed for Angular 20+. Using it with older Angular versions will result in peer dependency errors and runtime failures.","severity":"breaking","affected_versions":"<20.0.0 (Angular)"},{"fix":"Double-check `baseURL` and `basePath` in `provideBetterAuth` against your Better Auth backend configuration. Ensure `environment.apiUrl` resolves to the correct API endpoint.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to use `provideBetterAuth` with an Angular version older than 14 (when `ApplicationConfig` and functional providers were introduced) or with an incorrect import.","error":"NG0900: Error: NG0900: 'provideBetterAuth' is not a function"},{"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.","cause":"Attempting to inject `AuthService` in a non-DI context, or without `provideBetterAuth` being correctly configured in the application's providers.","error":"Error: Can't resolve all parameters for AuthService (?). This typically indicates that it's used in a context where dependency injection is not available."},{"fix":"Upgrade your Angular project to version 20 or higher using `ng update @angular/core @angular/cli --allow-dirty`.","cause":"The installed Angular version does not meet the `ngx-better-auth` peer dependency requirement, which is `>=20.0.0`.","error":"Error: Peer dependency '@angular/core@^16.0.0' not installed."},{"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).","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.","error":"Property 'session' does not exist on type 'AuthService'."}],"ecosystem":"npm"}