@dial8/auther

A powerful, flexible React onboarding and authentication library with swappable templates and backend adapters.

Features

• 🔧 Pluggable Architecture - Swap templates and auth adapters easily
• 🎨 Customizable UI - Built-in themes and brand customization
• 🚀 Smart Routing - Auto-redirect users after completion with redirectUrl prop
• 🔄 Completion Callbacks - Custom logic with onComplete for analytics, CRM, etc.
• 🔐 Multiple Auth Providers - Firebase, custom backends, and more
• 📧 Email Verification - Automatic verification email sending
• 📱 Responsive Design - Works on all devices
• 🎯 TypeScript Ready - Full TypeScript support
• ⚡ React 18 & 19 - Compatible with latest React versions

Installation

npm install @dial8/auther

Quick Start

import { OnboardingFlow } from "@dial8/auther";
import { MinimalTemplate } from "@dial8/auther-template-minimal";
import { firebaseAdapter } from "@dial8/auther-adapter-firebase";

function App() {
  return (
    <OnboardingFlow
      template={MinimalTemplate}
      adapter={firebaseAdapter({
        apiKey: "your-api-key",
        authDomain: "your-project.firebaseapp.com",
        projectId: "your-project-id",
      })}
      steps={["signInOrUp", "verifyEmail", "profile", "success"]}
      theme={{ brandColor: "#0ea5e9", darkMode: false }}
      brand={{ 
        title: "Welcome to MyApp", 
        subtitle: "Get started in seconds",
        logo: "/logo.png" 
      }}
      redirectUrl="/dashboard"  // 🎯 NEW: Auto-redirect after completion
      onComplete={(user) => {   // 🎯 NEW: Custom completion logic
        console.log('Welcome!', user.email);
        // Track analytics, send emails, etc.
      }}
    />
  );
}

Components

OnboardingFlow

The main component that orchestrates the entire onboarding experience.

<OnboardingFlow
  template={YourTemplate}
  adapter={yourAdapter}
  steps={["signInOrUp", "profile", "success"]}
  theme={{ brandColor: "#0ea5e9" }}
  brand={{ title: "Welcome" }}
  redirectUrl="/dashboard"
  onComplete={(user) => console.log('User completed onboarding:', user)}
/>

Props

• template - Template component for rendering UI
• adapter - Authentication adapter
• steps - Array of onboarding steps
• theme - Theme configuration
• brand - Brand/logo configuration
• redirectUrl? - URL to redirect to after completion
• onComplete? - Callback when onboarding completes (receives user object)

Built-in Steps

• signInOrUp - Email/password authentication
• verifyEmail - Email verification step (automatically sends verification email after signup)
• profile - Profile completion
• success - Success/completion page

Email Verification

Email verification is handled automatically:

• Verification emails are sent after successful user signup
• The template receives the user's email for display in the verification step
• Different adapters handle email sending differently:
  • Mock adapter: Logs to console for development
  • Firebase adapter: Uses Firebase's built-in email verification
  • Custom adapters: Must implement sendVerificationEmail() method

Post-Completion Handling

Control what happens after users complete onboarding:

Redirect to Dashboard

<OnboardingFlow
  // ... other props
  redirectUrl="/dashboard"
/>

Custom Completion Logic

<OnboardingFlow
  // ... other props
  onComplete={(user) => {
    // Track analytics
    analytics.track('onboarding_completed', { userId: user.uid });
    
    // Send welcome email
    sendWelcomeEmail(user.email);
    
    // Custom navigation (for SPAs with React Router)
    navigate('/welcome');
  }}
/>

Combined Approach

<OnboardingFlow
  // ... other props
  onComplete={(user) => {
    console.log('Onboarding completed for:', user.email);
    // Custom logic runs first
  }}
  redirectUrl="/dashboard"  // Then redirect happens
/>

Framework-Specific Examples

Next.js App Router

// app/auth/page.tsx
'use client';

export default function AuthPage() {
  return (
    <OnboardingFlow
      template={MinimalTemplate}
      adapter={firebaseAdapter(config)}
      steps={["signInOrUp", "verifyEmail", "profile", "success"]}
      redirectUrl="/dashboard"  // Navigate to /dashboard route
    />
  );
}

Next.js Pages Router

// pages/auth.tsx
import { useRouter } from 'next/router';

export default function AuthPage() {
  const router = useRouter();
  
  return (
    <OnboardingFlow
      template={MinimalTemplate}
      adapter={firebaseAdapter(config)}
      steps={["signInOrUp", "verifyEmail", "profile", "success"]}
      onComplete={(user) => {
        router.push('/dashboard');
      }}
    />
  );
}

React Router (Vite/CRA)

import { useNavigate } from 'react-router-dom';

function OnboardingPage() {
  const navigate = useNavigate();
  
  return (
    <OnboardingFlow
      template={MinimalTemplate}
      adapter={firebaseAdapter(config)}
      steps={["signInOrUp", "verifyEmail", "profile", "success"]}
      onComplete={(user) => {
        navigate('/dashboard', { state: { user } });
      }}
    />
  );
}

Analytics Integration

<OnboardingFlow
  template={MinimalTemplate}
  adapter={firebaseAdapter(config)}
  steps={["signInOrUp", "verifyEmail", "profile", "success"]}
  onComplete={(user) => {
    // Track conversion
    gtag('event', 'sign_up', {
      method: 'email',
      user_id: user.uid
    });
    
    // Mixpanel tracking
    mixpanel.track('Onboarding Completed', {
      userId: user.uid,
      email: user.email,
      timestamp: new Date().toISOString()
    });
    
    // Send to CRM
    createCustomerRecord({
      id: user.uid,
      email: user.email,
      source: 'onboarding_flow'
    });
  }}
  redirectUrl="/welcome"
/>

Theming

const theme = {
  brandColor: "#0ea5e9",
  darkMode: true,
  // Add more theme options as needed
};

Branding

const brand = {
  title: "Welcome to MyApp",
  subtitle: "Get started with your account",
  logo: "/path/to/logo.png"
};

Auth Context

Use the auth context to access user state throughout your app:

import { AuthProvider, useAuth } from "@dial8/auther";

function App() {
  return (
    <AuthProvider adapter={yourAdapter}>
      <YourAppContent />
    </AuthProvider>
  );
}

function YourAppContent() {
  const { user, signOut, isLoading } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  if (!user) return <OnboardingFlow ... />;
  
  return (
    <div>
      Welcome {user.email}!
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

TypeScript

Full TypeScript support with exported types:

import type { 
  User, 
  AuthAdapter, 
  TemplateProps, 
  OnboardingStep 
} from "@dial8/auther";

Related Packages

• @dial8/auther-template-minimal - Clean, minimal template
• @dial8/auther-adapter-firebase - Firebase authentication adapter

Creating Custom Adapters

import { AuthAdapter, User } from '@dial8/auther';

export function myAdapter(config): AuthAdapter {
  return {
    async getSession(): Promise<User | null> {
      // Return current user or null
    },
    async signInEmailPassword(email, password): Promise<User> {
      // Implement sign in
    },
    async signUpEmailPassword(email, password): Promise<User> {
      // Implement sign up  
    },
    async sendVerificationEmail(email): Promise<void> {
      // Send verification email to user
    },
    async signOut(): Promise<void> {
      // Implement sign out
    },
    onAuthStateChanged(callback): () => void {
      // Set up auth state listener
      // Return unsubscribe function
    }
  };
}

Creating Custom Templates

import { TemplateProps } from '@dial8/auther';

export function MyTemplate({ 
  step, ui, brand, theme, onNext, onSubmit 
}: TemplateProps) {
  switch (step) {
    case 'signInOrUp':
      return <MySignInForm onSubmit={onSubmit} />;
    case 'profile':
      return <MyProfileForm onSubmit={onSubmit} />;
    default:
      return <div>Step: {step}</div>;
  }
}

License

MIT

Support

• GitHub Issues
• Documentation