|
| 1 | +# Integration Guide: Better-Auth Plugin with ObjectOS Server |
| 2 | + |
| 3 | +This guide explains how to integrate the `@objectos/plugin-better-auth` plugin into an ObjectOS application. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The Better-Auth plugin provides authentication capabilities for ObjectOS applications using the [Better-Auth](https://www.better-auth.com/) library. It can be used as a standalone plugin or integrated with the existing `@objectos/server` package. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +The plugin is already part of the ObjectOS monorepo workspace. If you're using it in a separate project: |
| 12 | + |
| 13 | +```bash |
| 14 | +pnpm add @objectos/plugin-better-auth |
| 15 | +``` |
| 16 | + |
| 17 | +## Basic Integration |
| 18 | + |
| 19 | +### Option 1: Using with ObjectOS Kernel |
| 20 | + |
| 21 | +```typescript |
| 22 | +import { ObjectOS } from '@objectos/kernel'; |
| 23 | +import { BetterAuthPlugin } from '@objectos/plugin-better-auth'; |
| 24 | + |
| 25 | +const os = new ObjectOS({ |
| 26 | + plugins: [BetterAuthPlugin], |
| 27 | +}); |
| 28 | + |
| 29 | +await os.init(); |
| 30 | +``` |
| 31 | + |
| 32 | +### Option 2: Custom Configuration |
| 33 | + |
| 34 | +```typescript |
| 35 | +import { createBetterAuthPlugin } from '@objectos/plugin-better-auth'; |
| 36 | + |
| 37 | +const authPlugin = createBetterAuthPlugin({ |
| 38 | + databaseUrl: process.env.DATABASE_URL, |
| 39 | + baseURL: 'https://myapp.com/api/auth', |
| 40 | + trustedOrigins: ['https://myapp.com'] |
| 41 | +}); |
| 42 | + |
| 43 | +const os = new ObjectOS({ |
| 44 | + plugins: [authPlugin], |
| 45 | +}); |
| 46 | +``` |
| 47 | + |
| 48 | +## Integration with @objectos/server |
| 49 | + |
| 50 | +If you want to migrate from the existing auth implementation in `@objectos/server` to use this plugin: |
| 51 | + |
| 52 | +### Step 1: Install the plugin |
| 53 | + |
| 54 | +The plugin is already in the workspace, so just add it as a dependency: |
| 55 | + |
| 56 | +```json |
| 57 | +// packages/server/package.json |
| 58 | +{ |
| 59 | + "dependencies": { |
| 60 | + "@objectos/plugin-better-auth": "workspace:*" |
| 61 | + } |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +### Step 2: Replace auth imports |
| 66 | + |
| 67 | +**Before:** |
| 68 | +```typescript |
| 69 | +import { getAuth } from './auth/auth.client'; |
| 70 | +``` |
| 71 | + |
| 72 | +**After:** |
| 73 | +```typescript |
| 74 | +import { getBetterAuth } from '@objectos/plugin-better-auth'; |
| 75 | +``` |
| 76 | + |
| 77 | +### Step 3: Update auth controller |
| 78 | + |
| 79 | +The plugin automatically registers routes at `/api/auth/*` when enabled, so you can simplify your auth controller: |
| 80 | + |
| 81 | +**Before (auth.controller.ts):** |
| 82 | +```typescript |
| 83 | +@Controller('auth') |
| 84 | +export class AuthController { |
| 85 | + @All('*') |
| 86 | + async handler(@Req() req: Request, @Res() res: Response) { |
| 87 | + const auth = await getAuth(); |
| 88 | + const { toNodeHandler } = await import('better-auth/node'); |
| 89 | + return toNodeHandler(auth)(req, res); |
| 90 | + } |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +**After (using plugin):** |
| 95 | +The plugin handles this automatically via lifecycle hooks. You can remove the controller or keep it for additional custom endpoints. |
| 96 | + |
| 97 | +### Step 4: Load the plugin in your app module |
| 98 | + |
| 99 | +```typescript |
| 100 | +import { Module } from '@nestjs/common'; |
| 101 | +import { BetterAuthPlugin } from '@objectos/plugin-better-auth'; |
| 102 | + |
| 103 | +@Module({ |
| 104 | + // ... other config |
| 105 | +}) |
| 106 | +export class AppModule { |
| 107 | + async onModuleInit() { |
| 108 | + // The plugin will be loaded through the kernel |
| 109 | + // No additional setup needed |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +## API Endpoints |
| 115 | + |
| 116 | +Once the plugin is enabled, the following endpoints are available: |
| 117 | + |
| 118 | +- `POST /api/auth/sign-up` - User registration |
| 119 | +- `POST /api/auth/sign-in/email` - Email/password login |
| 120 | +- `POST /api/auth/sign-out` - Logout |
| 121 | +- `GET /api/auth/get-session` - Get current session |
| 122 | +- And all other Better-Auth endpoints |
| 123 | + |
| 124 | +See [Better-Auth API documentation](https://www.better-auth.com/docs/api-reference) for complete API reference. |
| 125 | + |
| 126 | +## Environment Variables |
| 127 | + |
| 128 | +The plugin uses the following environment variables: |
| 129 | + |
| 130 | +| Variable | Default | Description | |
| 131 | +|----------|---------|-------------| |
| 132 | +| `OBJECTQL_DATABASE_URL` | `sqlite:objectos.db` | Database connection string | |
| 133 | +| `BETTER_AUTH_URL` | `http://localhost:3000/api/auth` | Base URL for auth endpoints | |
| 134 | + |
| 135 | +## Plugin Lifecycle |
| 136 | + |
| 137 | +The plugin follows the ObjectOS plugin lifecycle: |
| 138 | + |
| 139 | +1. **onInstall**: Stores installation metadata |
| 140 | +2. **onEnable**: Initializes Better-Auth and registers routes at `/api/auth/*` |
| 141 | +3. **onDisable**: Gracefully disables (preserves user data) |
| 142 | +4. **onUninstall**: Cleans up plugin storage (preserves user data) |
| 143 | + |
| 144 | +## Events |
| 145 | + |
| 146 | +The plugin emits the following events that can be subscribed to: |
| 147 | + |
| 148 | +- `auth.user.created` - Fired when a new user is created |
| 149 | +- `auth.user.login` - Fired when a user logs in |
| 150 | +- `auth.user.logout` - Fired when a user logs out |
| 151 | +- `auth.session.created` - Fired when a new session is created |
| 152 | +- `auth.session.expired` - Fired when a session expires |
| 153 | + |
| 154 | +## Migration from Existing Implementation |
| 155 | + |
| 156 | +If you're migrating from the existing `@objectos/server/auth` implementation: |
| 157 | + |
| 158 | +1. The plugin provides the same functionality |
| 159 | +2. Database schema is compatible (uses the same Better-Auth tables) |
| 160 | +3. API endpoints remain the same (`/api/auth/*`) |
| 161 | +4. Configuration can be passed through the plugin factory |
| 162 | + |
| 163 | +## Standalone Usage |
| 164 | + |
| 165 | +The plugin can also be used outside of the ObjectOS kernel: |
| 166 | + |
| 167 | +```typescript |
| 168 | +import { getBetterAuth } from '@objectos/plugin-better-auth'; |
| 169 | + |
| 170 | +const auth = await getBetterAuth({ |
| 171 | + databaseUrl: 'postgres://...', |
| 172 | + baseURL: 'https://myapp.com/api/auth' |
| 173 | +}); |
| 174 | + |
| 175 | +// Use auth instance directly |
| 176 | +``` |
| 177 | + |
| 178 | +## Troubleshooting |
| 179 | + |
| 180 | +### Plugin not registering routes |
| 181 | + |
| 182 | +Make sure the plugin is loaded through the ObjectOS kernel and the `onEnable` hook is called: |
| 183 | + |
| 184 | +```typescript |
| 185 | +const os = new ObjectOS({ |
| 186 | + plugins: [BetterAuthPlugin] |
| 187 | +}); |
| 188 | +await os.init(); // This calls onEnable |
| 189 | +``` |
| 190 | + |
| 191 | +### Database connection issues |
| 192 | + |
| 193 | +Ensure `OBJECTQL_DATABASE_URL` is set correctly: |
| 194 | + |
| 195 | +```bash |
| 196 | +# PostgreSQL |
| 197 | +export OBJECTQL_DATABASE_URL="postgres://user:pass@localhost:5432/db" |
| 198 | + |
| 199 | +# MongoDB |
| 200 | +export OBJECTQL_DATABASE_URL="mongodb://localhost:27017/db" |
| 201 | + |
| 202 | +# SQLite (default) |
| 203 | +export OBJECTQL_DATABASE_URL="sqlite:auth.db" |
| 204 | +``` |
| 205 | + |
| 206 | +## Next Steps |
| 207 | + |
| 208 | +- See [README.md](./README.md) for complete plugin documentation |
| 209 | +- See [examples/usage.ts](./examples/usage.ts) for code examples |
| 210 | +- See [Better-Auth documentation](https://www.better-auth.com/docs) for auth features |
0 commit comments