@akson/cortex-supabase

Comprehensive Supabase package with Auth, Storage, Database, and Realtime functionality for React applications.

Features

• 🔐 Authentication - Complete auth system with SSR support, guards, and session management
• 💾 Storage - File upload/download with progress tracking and validation
• 🗄️ Database - Type-safe database operations with React hooks
• ⚡ Realtime - Real-time subscriptions and live updates
• 🎯 TypeScript First - Fully typed with comprehensive type definitions
• ⚛️ React Components - Pre-built UI components for common patterns
• 🛡️ Route Guards - Protect routes with authentication and role-based access
• 🌐 SSR Ready - Server-side rendering support for Next.js
• 🔧 Multiple Clients - Browser, server, and middleware clients

Installation

npm install @akson/cortex-supabase

Dependencies

This package requires @supabase/supabase-js and react as peer dependencies:

npm install @supabase/supabase-js react

Quick Start

Authentication

import { AuthProvider, useAuth, LoginPage } from '@akson/cortex-supabase';
import { createBrowserClient } from '@akson/cortex-supabase/clients';

// Setup client
const supabase = createBrowserClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// Wrap your app
function App() {
  return (
    <AuthProvider client={supabase}>
      <MyApp />
    </AuthProvider>
  );
}

// Use authentication in components
function MyComponent() {
  const { user, signOut, loading } = useAuth();

  if (loading) return <div>Loading...</div>;

  if (!user) {
    return <LoginPage />;
  }

  return (
    <div>
      <p>Welcome, {user.email}!</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

File Storage

import { useDocumentUpload, useDocumentManager } from '@akson/cortex-supabase';

function FileUploadComponent() {
  const { upload, isUploading, progress, error } = useDocumentUpload({
    bucketName: 'documents',
    maxFileSize: 10 * 1024 * 1024, // 10MB
    allowedTypes: ['image/jpeg', 'image/png', 'application/pdf'],
  });

  const handleFileUpload = async (file: File) => {
    const result = await upload(file, {
      path: 'uploads/',
      metadata: { category: 'documents' },
    });

    if (result.success) {
      console.log('File uploaded:', result.url);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={(e) => e.target.files?.[0] && handleFileUpload(e.target.files[0])}
        disabled={isUploading}
      />
      {isUploading && <p>Uploading... {progress?.percentage}%</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

Route Guards

import { AuthGuard, RoleGuard } from '@akson/cortex-supabase';

// Protect entire routes
function ProtectedPage() {
  return (
    <AuthGuard fallback={<LoginPage />}>
      <RoleGuard roles={['admin']} fallback={<Unauthorized />}>
        <AdminDashboard />
      </RoleGuard>
    </AuthGuard>
  );
}

Package Exports

The package provides modular exports for different functionality:

// Main package - includes everything
import { useAuth, AuthProvider, LoginPage } from '@akson/cortex-supabase';

// Specific modules
import { createBrowserClient } from '@akson/cortex-supabase/clients';
import { useDocumentUpload } from '@akson/cortex-supabase/hooks';
import { isAdmin, hasRole } from '@akson/cortex-supabase/auth';
import { SupabaseStorageService } from '@akson/cortex-supabase/storage';

Available Exports

• /clients - Browser, server, and middleware clients
• /auth - Authentication utilities and helpers
• /hooks - React hooks for storage, auth, and data fetching
• /storage - Storage service and utilities
• /components - Pre-built UI components
• /guards - Route protection components
• /pages - Complete auth pages (login, signup, etc.)
• /utils - Utility functions and helpers
• /types - TypeScript type definitions

Server-Side Rendering (Next.js)

Middleware Setup

// middleware.ts
import { createMiddleware } from '@akson/cortex-supabase/middleware';

export default createMiddleware({
  redirects: {
    protected: ['/dashboard', '/admin'],
    public: ['/login', '/signup'],
  },
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Server Components

// app/dashboard/page.tsx
import { createServerClient } from '@akson/cortex-supabase/clients';
import { getCurrentUser, requireAuth } from '@akson/cortex-supabase/auth';

export default async function DashboardPage() {
  // Require authentication
  const user = await requireAuth();

  // Or check without redirect
  const currentUser = await getCurrentUser();
  if (!currentUser) {
    return <LoginRequired />;
  }

  return (
    <div>
      <h1>Welcome, {user.email}!</h1>
      <UserProfile user={user} />
    </div>
  );
}

Pre-built Components

import {
  LoginPage,
  SignupPage,
  ResetPasswordPage,
  UserProfile,
  AuthGuard,
  RoleGuard,
} from '@akson/cortex-supabase';

// Complete auth pages with styling
function AuthRoutes() {
  return (
    <Routes>
      <Route path="/login" element={<LoginPage />} />
      <Route path="/signup" element={<SignupPage />} />
      <Route path="/reset" element={<ResetPasswordPage />} />
    </Routes>
  );
}

// Protected routes with role-based access
function AdminPanel() {
  return (
    <RoleGuard roles={['admin', 'moderator']}>
      <AdminDashboard />
    </RoleGuard>
  );
}

Advanced Usage

Custom Clients Configuration

import { createBrowserClient, createServerClient } from '@akson/cortex-supabase/clients';

// Browser client with custom config
const browserClient = createBrowserClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  {
    auth: {
      autoRefreshToken: true,
      persistSession: true,
      detectSessionInUrl: true,
    },
  }
);

// Server client for API routes
const serverClient = createServerClient();

Storage Service Integration

import { createStorageService, SupabaseStorageService } from '@akson/cortex-supabase/storage';

const storageService = createStorageService({
  bucketName: 'documents',
  maxFileSize: 100 * 1024 * 1024, // 100MB
  allowedTypes: ['*'],
  pathPrefix: 'uploads',
  generateUniqueNames: true,
});

// Direct service usage
const result = await storageService.uploadFile(file, 'custom/path/');
const url = await storageService.getSignedUrl('path/file.pdf', 3600);

Custom Authentication Logic

import { isAdmin, hasRole, getCurrentUser } from '@akson/cortex-supabase/auth';

// Check user permissions
async function checkPermissions() {
  const user = await getCurrentUser();

  if (isAdmin(user)) {
    return 'full_access';
  }

  if (hasRole(user, ['editor', 'moderator'])) {
    return 'limited_access';
  }

  return 'read_only';
}

Configuration

Environment Variables

# Required
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

# Optional
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret

Auth Configuration

interface AuthConfig {
  redirectTo?: string;              // Post-auth redirect URL
  autoRefresh?: boolean;           // Auto-refresh tokens
  persistSession?: boolean;        // Persist sessions
  detectSessionInUrl?: boolean;    // Detect session from URL
  roles?: string[];               // Available user roles
}

Storage Configuration

interface StorageConfig {
  bucketName: string;              // Supabase bucket name
  maxFileSize?: number;           // Max file size in bytes
  allowedTypes?: string[];        // Allowed MIME types
  pathPrefix?: string;            // Path prefix for uploads
  generateUniqueNames?: boolean;  // Generate unique filenames
}

TypeScript Support

The package is fully typed with comprehensive TypeScript definitions:

import type {
  User,
  AuthSession,
  AuthConfig,
  StorageConfig,
  UploadResult,
  UploadProgress,
  AuthResponse,
} from '@akson/cortex-supabase';

// Extend types for your application
interface AppUser extends User {
  role: 'admin' | 'editor' | 'viewer';
  department?: string;
}

Error Handling

The package provides consistent error handling across all operations:

import { AuthError, StorageError } from '@akson/cortex-supabase';

// Auth operations
try {
  const user = await signIn(email, password);
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Auth error:', error.message);
    // Handle specific auth errors
  }
}

// Storage operations
try {
  const result = await uploadFile(file);
  if (!result.success) {
    console.error('Upload failed:', result.error);
  }
} catch (error) {
  if (error instanceof StorageError) {
    console.error('Storage error:', error.message);
  }
}

Hooks Reference

Authentication Hooks

• useAuth() - Current user and auth state
• useSession() - Session management
• usePermissions() - Role-based permissions

Storage Hooks

• useDocumentUpload() - File upload with progress
• useDocumentManager() - Document CRUD operations
• useBatchUpload() - Multiple file uploads
• useFileValidation() - File validation utilities

Utility Hooks

• useSupabase() - Access Supabase client
• useRealtime() - Real-time subscriptions (coming soon)

Example Usage

const { user, loading, signOut } = useAuth();
const { upload, isUploading, progress } = useDocumentUpload();
const { hasPermission } = usePermissions(['admin']);

Version History

• 3.1.2 - Current version with full auth, storage, and component support
• 3.0.x - Major rewrite with modular architecture
• 2.x.x - Legacy storage-focused package

Contributing

This is part of the Cortex packages ecosystem. Contributions are welcome!

License

MIT

Support

For support, please open an issue in the Cortex Packages repository.