From a845dcc3b7647c5ac4a8214d66f913a3b2e37022 Mon Sep 17 00:00:00 2001 From: miguelrk Date: Wed, 23 Apr 2025 13:33:01 +0200 Subject: [PATCH 1/2] Update README.md Update the `README.md` with an overview of the module, a quick setup guide and some documentation (API reference). --- README.md | 227 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 212 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index cd699f8..f164f2c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href] -My new Nuxt module for doing amazing things. +A Nuxt module for simple, flexible authentication in your Nuxt 3 applications. - [✨  Release Notes](/CHANGELOG.md) @@ -13,47 +13,244 @@ My new Nuxt module for doing amazing things. ## Features - -- ⛰  Foo -- 🚠  Bar -- 🌲  Baz +- 🔒  Simple authentication for Nuxt 3 applications +- 🚀  Built-in authentication middleware +- 🔑  Multiple authentication strategies (username, email) +- 🛡️  Role-based access control +- 🔄  Session management +- 📱  Redirect handling for authenticated/unauthenticated users ## Quick Setup -Install the module to your Nuxt application with one command: +1. Install the module: ```bash -npx nuxi module add my-module +# Using npm +npm install better-auth-nuxt + +# Using yarn +yarn add better-auth-nuxt + +# Using pnpm +pnpm add better-auth-nuxt +``` + +2. Add the module to your `nuxt.config.ts`: + +```ts +export default defineNuxtConfig({ + modules: ['better-auth-nuxt'], + + betterAuth: { + // Configure auth endpoints (default: '/api/auth/**') + endpoint: '/api/auth/**', + + // Configure redirect paths + redirectOptions: { + redirectGuestTo: '/auth/login', + redirectUserTo: '/', + redirectUnauthorizedTo: '/401', + }, + + // Configure client and server options + options: { + client: { + basePath: '/api/auth', + // Optional: baseURL, disableDefaultFetchPlugins + }, + server: { + appName: 'My Nuxt App', + // Optional: baseURL, basePath, secret + }, + }, + } +}) +``` + +3. Use the module in your pages: + +```vue + + + +``` + +## Module Options + +### Auth Configuration + +```ts +interface ModuleOptions { + // Auth endpoint + endpoint: string + + // Patterns to match auth configuration files + serverConfigs?: string[] + clientConfigs?: string[] + + // Client and server options + options: { + client?: ModuleClientOptions + server?: ModuleServerOptions + } + + // Redirect options + redirectOptions: { + redirectUserTo?: string + redirectGuestTo?: string + redirectUnauthorizedTo?: string + } +} +``` + +### Server Options + +```ts +interface ModuleServerOptions { + appName?: string // Application name + baseURL?: string // Base URL for the auth API + basePath?: string // Base path for the auth API + secret?: string // Secret for JWT/session encryption +} ``` -That's it! You can now use My Module in your Nuxt app ✨ +### Client Options + +```ts +interface ModuleClientOptions { + baseURL?: string // Base URL for the auth API + basePath?: string // Base path for the auth API + disableDefaultFetchPlugins?: boolean // Disable default fetch plugins +} +``` + +## API Reference + +### Client-side Composables + +#### `useUserSession()` + +Provides access to the authenticated user session and auth methods. + +```ts +const { + // State + loggedIn, // Ref - Is the user logged in + user, // Ref - Current user data + session, // Ref - Current session data + // Methods + fetchSession, // () => Promise - Fetch current session + signIn: { + username, // (credentials) => Promise - Sign in with username + email, // (credentials) => Promise - Sign in with email + }, + signUp: { + username, // (userData) => Promise - Register with username + email, // (userData) => Promise - Register with email + }, + signOut, // (options?) => Promise - Sign out the user + + // Configuration + options, // Auth configuration options +} = useUserSession() +``` + +### Server-side Utilities + +#### `useAuth()` + +Access the auth instance on the server. + +```ts +// In API route handlers: +const auth = useAuth() +``` + +### Route Protection + +Use the `auth` meta property to protect routes: + +```ts +definePageMeta({ + auth: { + // Only allow specific roles + only: 'user' | 'admin' | 'guest' | ['user', 'admin'], + + // Custom redirect paths (override global config) + redirectUserTo: '/dashboard', + redirectGuestTo: '/login', + redirectUnauthorizedTo: '/unauthorized', + } +}) +``` + +## Configuration Files + +You can create configuration files to customize authentication: + +### Server Configuration + +Create a `*.better-auth.ts` file to configure server-side auth: + +```ts +// app/my-auth.better-auth.ts +export default { + // Custom server-side auth configuration +} +``` + +### Client Configuration + +Create a `*.better-auth-client.ts` file to configure client-side auth: + +```ts +// app/my-auth.better-auth-client.ts +export default { + // Custom client-side auth configuration +} +``` ## Contribution
Local development - + ```bash # Install dependencies npm install - + # Generate type stubs npm run dev:prepare - + # Develop with the playground npm run dev - + # Build the playground npm run dev:build - + # Run ESLint npm run lint - + # Run Vitest npm run test npm run test:watch - + # Release new version npm run release ``` From e5385b17683fc27272fe0959fde3b923afc34190 Mon Sep 17 00:00:00 2001 From: miguelrk Date: Wed, 23 Apr 2025 14:28:23 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f164f2c..b91215e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href] -A Nuxt module for simple, flexible authentication in your Nuxt 3 applications. +A Nuxt module for simple, flexible authentication in your Nuxt applications. - [✨  Release Notes](/CHANGELOG.md) @@ -13,12 +13,12 @@ A Nuxt module for simple, flexible authentication in your Nuxt 3 applications. ## Features -- 🔒  Simple authentication for Nuxt 3 applications +- ⚙️  Auto-scanning of client and server configs for end-to-end TS support - 🚀  Built-in authentication middleware -- 🔑  Multiple authentication strategies (username, email) +- 🔑  Multiple authentication strategies (username, email, ...) - 🛡️  Role-based access control - 🔄  Session management -- 📱  Redirect handling for authenticated/unauthenticated users +- 🔒  Redirect handling for authenticated/unauthenticated users ## Quick Setup