sessionize-auth

v2.0.0

Published

3 months ago

A flexible session management library for React, Next.js, Angular, and React Native

🚀 Sessionize Auth v2.0

A powerful, flexible session management library for modern web applications with support for React, Next.js, Angular, and more.

✨ Features

🔐 Multiple Storage Options: localStorage, sessionStorage, cookies, Redis, database
⚡ Return-to Functionality: Automatic redirection after login with smart session management
🎯 Framework Adapters: Dedicated adapters for React (ready), Next.js (structure), Angular (planned)
🔑 SSO Integration: Single Sign-On with Google, Microsoft, GitHub and custom providers
📱 TypeScript First: Full type safety and excellent developer experience
🔄 Pluggable Architecture: Modular design for maximum flexibility and extensibility
🚀 Lightweight: Minimal dependencies with Zustand for state management
🧪 Well Tested: Comprehensive test coverage with Jest
🎨 Demo Application: Complete working example with modern UI

🚀 Quick Start

Installation

npm install sessionize-auth
# or
yarn add sessionize-auth
# or
pnpm add sessionize-auth

Basic Usage (React)

import { AuthProvider, useAuth, withAuth } from 'sessionize-auth';

// 1. Wrap your app with AuthProvider
function App() {
  return (
    <AuthProvider
      config={{
        storageType: 'localStorage',
        redirectPath: '/login',
        returnToParam: 'returnTo'
      }}
    >
      <YourApp />
    </AuthProvider>
  );
}

// 2. Use the useAuth hook
function Dashboard() {
  const { account, isAuthenticated, login, logout } = useAuth();
  
  if (!isAuthenticated) {
    return <div>Please log in</div>;
  }
  
  return (
    <div>
      <h1>Welcome, {account.name}!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

// 3. Or use the HOC
const ProtectedDashboard = withAuth()(Dashboard);

SSO Integration

import { AuthProvider, useAuth, SSOManager, SSOProviderList } from 'sessionize-auth';

// Configure SSO providers
const ssoManager = new SSOManager({
  providers: [
    {
      id: 'google',
      name: 'Google',
      clientId: 'your-google-client-id',
      redirectUri: 'http://localhost:3000/auth/callback',
      scopes: ['openid', 'email', 'profile']
    },
    {
      id: 'microsoft',
      name: 'Microsoft',
      clientId: 'your-microsoft-client-id',
      redirectUri: 'http://localhost:3000/auth/callback',
      scopes: ['openid', 'email', 'profile', 'User.Read']
    }
  ]
});

function App() {
  return (
    <AuthProvider config={{ storageType: 'localStorage' }}>
      <YourApp />
    </AuthProvider>
  );
}

// Use SSO in your login component
function LoginPage() {
  const { login } = useAuth();
  const { providers, loginWithProvider } = useSSO(ssoManager);

  const handleSSOLogin = async (providerId: string) => {
    const result = await loginWithProvider(providerId);
    if (result.success && result.user) {
      login(result.user);
    }
  };

  return (
    <div>
      <SSOProviderList 
        providers={providers}
        onProviderLogin={handleSSOLogin}
      />
    </div>
  );
}

Advanced Usage with Custom Stores

import { AuthProvider, useAuth, createMemoryStore } from 'sessionize-auth';

// Custom store for testing or SSR
const memoryStore = createMemoryStore();

function App() {
  return (
    <AuthProvider
      config={{
        storageType: 'localStorage',
        redirectPath: '/login',
        returnToParam: 'returnTo',
        storageKey: 'my_app_session'
      }}
    >
      <YourApp />
    </AuthProvider>
  );
}

📚 Documentation

Core Concepts

Session Store

The session store is responsible for persisting user data across browser sessions.

import { createSessionStore } from 'sessionize-auth';

const store = createSessionStore({
  storageType: 'localStorage', // 'localStorage' | 'sessionStorage' | 'cookies'
  storageKey: 'user_session'
});

// Access session data
const { account, startSession, closeSession } = store.getState();

Return-to Functionality

Automatically redirect users back to their intended destination after login.

// When accessing a protected route, the current URL is automatically saved
// After login, user is redirected back to the original location
const { login } = useAuth();

// Login with optional return-to parameter
login(userData, '/dashboard/settings');

// Or let the system handle it automatically
login(userData); // Will redirect to saved return-to URL

Advanced Configuration

Custom Storage Backend

import { createRedisStore, createMemoryStore } from 'sessionize-auth/stores';

// Redis store (for production)
const redisStore = createRedisStore({
  host: 'localhost',
  port: 6379,
  password: 'your-password',
  ttl: 7 * 24 * 60 * 60 // 7 days
});

// Memory store (for testing)
const memoryStore = createMemoryStore();

Protected Routes with HOC

import { withAuth } from 'sessionize-auth';

// Protect individual components
const ProtectedDashboard = withAuth({
  redirectPath: '/login',
  fallback: LoadingComponent
})(Dashboard);

// Use in your routing
<Route path="/dashboard" element={<ProtectedDashboard />} />

🎯 Framework Adapters

React ✅ Ready

useAuth() hook for state management
withAuth() HOC for component protection
AuthProvider for app-wide configuration
Full TypeScript support

Next.js 🚧 Structure Ready

Server-side rendering support (planned)
Middleware for route protection (planned)
Automatic cookie handling (planned)

Angular 📋 Planned

Service-based architecture
Route guards
Dependency injection support

🛠️ Pluggable Stores

localStorage ✅: Browser local storage with persistence
sessionStorage ✅: Browser session storage (cleared on tab close)
cookies ✅: HTTP cookies with security options (secure, sameSite)
Redis 🚧: Redis-based session store (structure ready)
Database 🚧: SQL/NoSQL database integration (structure ready)
Memory ✅: In-memory store for testing and SSR

🔑 SSO Providers

Google ✅: OAuth 2.0 with OpenID Connect
Microsoft ✅: Azure AD OAuth 2.0 integration
GitHub ✅: GitHub OAuth 2.0 authentication
Custom ✅: Extensible provider system for any OAuth 2.0 provider

🎨 Demo Application

Experience Sessionize Auth v2.0 with our complete demo application:

# Clone and setup
git clone https://github.com/Katumbela/sessionize-auth.git
cd sessionize-auth

# Install dependencies
npm install

# Run demo
npm run demo:dev

Demo Features:

✅ Complete authentication flow
✅ Protected routes with return-to functionality
✅ SSO integration with Google, Microsoft, GitHub
✅ Modern, responsive UI
✅ TypeScript integration
✅ Multiple storage options

Demo Credentials:

Email: [email protected]
Password: password

🚀 Getting Started with Demo

Quick Setup

# Option 1: Use the setup script (Windows)
./setup-demo.ps1

# Option 2: Use the setup script (Linux/Mac)
./setup-demo.sh

# Option 3: Manual setup
npm install
cd demo
npm install
npm run dev

Project Structure

sessionize-auth/
├── src/
│   ├── core/                    # Core session management
│   ├── adapters/react/          # React integration
│   ├── stores/                  # Pluggable storage backends
│   └── index.ts                 # Main exports
├── demo/                        # Complete demo application
│   ├── src/
│   │   ├── components/          # Reusable components
│   │   ├── pages/               # Application pages
│   │   └── App.tsx              # Main app component
│   └── README.md                # Demo documentation
└── README.md                    # This file

🤝 Contributing

Contributions are welcome! Here's how you can help:

Report Issues: Found a bug? Open an issue
Suggest Features: Have an idea? Start a discussion
Submit PRs: Want to contribute code? Fork and submit a pull request
Improve Docs: Help us make the documentation better

Development Setup

# Clone the repository
git clone https://github.com/Katumbela/sessionize-auth.git
cd sessionize-auth

# Install dependencies
npm install

# Run tests
npm test

# Build the library
npm run build

# Run demo
npm run demo:dev

📄 License

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

🙏 Acknowledgments

Built with Zustand for state management
Inspired by modern authentication patterns and best practices
Community feedback and contributions
Special thanks to all contributors and users

📞 Support

Documentation: README and Demo README
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]