Firebase Auth Plugin for API Buddy

A comprehensive authentication solution for Next.js applications using Firebase Authentication. This plugin provides everything you need to add secure authentication to your API Buddy projects with minimal configuration.

✨ Features

• Seamless Integration: Built specifically for the API Buddy ecosystem
• Full-Stack Ready: Includes both frontend components and API routes
• TypeScript First: Fully typed for a great developer experience
• Production Ready: Battle-tested patterns for security and reliability
• Customizable: Easy to extend and style to match your application

🚀 Quick Start

1. Create a new Next.js application (if you haven't already):

   npx create-next-app@latest my-app
   cd my-app

2. Install the plugin:

   pnpm add @api-buddy/plugin-auth-firebase

3. Initialize Firebase Auth:

   npx api-buddy firebase-auth init --project-id your-project-id --api-key your-api-key --auth-domain your-app.firebaseapp.com

   This will:

   • Set up Firebase configuration
   • Create necessary API routes
   • Generate authentication pages
   • Configure environment variables

🔧 Initialization

The init command sets up everything needed for Firebase Authentication:

npx api-buddy firebase-auth init [project-dir] [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | -f, --force | Overwrite existing files | false | | --skip-install | Skip installing dependencies | false | | --only-api | Only generate API routes | false | | --only-pages | Only generate pages | false | | --only-components | Only generate components | false | | --dry-run | Run without making changes | false | | --project-id <projectId> | Firebase project ID | - | | --api-key <apiKey> | Firebase API key | - | | --auth-domain <authDomain> | Firebase auth domain | - | | --use-emulator | Use Firebase emulator | false | | --emulator-host <host> | Firebase emulator host | localhost | | --emulator-port <port> | Firebase emulator port | 9099 | | --auth-providers <providers> | Comma-separated list of auth providers | email | | --no-email-verification | Disable email verification | true | | --no-password-reset | Disable password reset | true |

Examples:

1. Basic setup with email authentication:

   npx api-buddy firebase-auth init --project-id my-project --api-key abc123 --auth-domain my-app.firebaseapp.com

2. Setup with Google and GitHub auth:

   npx api-buddy firebase-auth init --project-id my-project --auth-providers "email,google,github"

3. Setup with emulator:

   npx api-buddy firebase-auth init --use-emulator --emulator-port 9099

What it does:

1. Configuration

   • Creates a Firebase configuration file
   • Sets up environment variables
   • Configures Firebase Admin SDK
   • Sets up authentication providers
   • Configures email verification and password reset

2. API Routes

   • /api/auth/signin - Handle user sign in
   • /api/auth/signup - Handle user registration
   • /api/auth/signout - Handle user sign out
   • /api/auth/session - Get current session

3. Frontend

   • Authentication provider
   • Custom hooks
   • Example pages

⚛️ Using Frontend Hooks

The plugin provides several React hooks for authentication:

useAuth Hook

'use client';

import { useAuth } from '@api-buddy/plugin-auth-firebase';

export default function Profile() {
  const {
    user,           // Current user object or null
    loading,        // Loading state
    error,         // Error object if any
    signIn,        // Sign in function
    signUp,        // Sign up function
    signOut,       // Sign out function
    updateProfile, // Update user profile
  } = useAuth();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {user ? (
        <div>
          <h1>Welcome, {user.displayName || user.email}!</h1>
          <button onClick={signOut}>Sign Out</button>
        </div>
      ) : (
        <div>
          <button onClick={() => signIn({ email: '[email protected]', password: 'password' })}>
            Sign In
          </button>
        </div>
      )}
    </div>
  );
}

useUser Hook

For simple user access:

'use client';

import { useUser } from '@api-buddy/plugin-auth-firebase';

export default function UserInfo() {
  const user = useUser();
  
  if (!user) return <div>Not signed in</div>;
  
  return (
    <div>
      <p>Email: {user.email}</p>
      <p>Name: {user.displayName || 'Not set'}</p>
    </div>
  );
}

🔄 API Buddy Ecosystem Integration

This plugin is designed to work seamlessly with the API Buddy ecosystem:

1. Unified Authentication

   • Single sign-on across all API Buddy services
   • Centralized user management
   • Consistent authentication patterns

2. API Protection

   • Automatic token validation
   • Role-based access control
   • Rate limiting and security headers

3. Development Experience

   • TypeScript support
   • Hot reloading
   • Development tools

🔒 Environment Variables

After initialization, you'll need to set these environment variables in your .env.local. Instructions for obtaining the api keys from Firebase are in /docs/FIREBASE-SETUP.md.

📚 Documentation

For more detailed information, please refer to:

• API Reference
• Customization Guide
• Migration Guide

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide to get started.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.