@dopomogai/supabase-client

Unified Supabase auth layer for DopomogAI apps: typed service, React provider + hooks, and prebuilt pages with a polished UX.

What you get

• Prebuilt UI pages for login, sign-up, magic links, password recovery, and password updates.
• A structured AuthService with consistent error mapping and typed responses.
• React hooks for auth state, flow state, and UI text resolution.
• UI configuration for text overrides, routing, branding, OAuth providers, and redirects.
• Modular entry points so you can import only the core, React hooks, or full pages.

Installation

Core only

npm install @dopomogai/supabase-client
# or
pnpm add @dopomogai/supabase-client

Full UI (recommended)

npm install @dopomogai/supabase-client @dopomogai/ui react-router-dom react-i18next framer-motion lucide-react
# or
pnpm add @dopomogai/supabase-client @dopomogai/ui react-router-dom react-i18next framer-motion lucide-react

Quick start (UI pages)

1) Initialize Supabase once

import { initSupabase } from '@dopomogai/supabase-client';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;

if (!supabaseUrl || !supabaseAnonKey) {
  throw new Error('Supabase URL and anon key are required.');
}

export const supabase = initSupabase(supabaseUrl, supabaseAnonKey);

2) Add Tailwind content paths

These pages rely on Tailwind classes from this package and @dopomogai/ui.

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@dopomogai/supabase-client/dist/**/*.mjs',
    './node_modules/@dopomogai/ui/dist/**/*.mjs',
  ],
};

3) Add provider and routes

import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { SupabaseAuthProvider } from '@dopomogai/supabase-client/react';
import {
  LoginPage,
  RegisterPage,
  ForgotPasswordPage,
  UpdatePasswordPage,
} from '@dopomogai/supabase-client/pages';
import { supabase } from './supabase';

export function App() {
  return (
    <BrowserRouter>
      <SupabaseAuthProvider supabaseClient={supabase}>
        <Routes>
          <Route path="/auth/login" element={<LoginPage />} />
          <Route path="/auth/register" element={<RegisterPage />} />
          <Route path="/auth/forgot-password" element={<ForgotPasswordPage />} />
          <Route path="/auth/update-password" element={<UpdatePasswordPage />} />
        </Routes>
      </SupabaseAuthProvider>
    </BrowserRouter>
  );
}

UI configuration

Use the ui prop on SupabaseAuthProvider to override text, routes, branding, layout, OAuth providers, and redirects.

import type { AuthUIConfig } from '@dopomogai/supabase-client/react';

const authUI: AuthUIConfig = {
  text: {
    signInTitle: 'Welcome back',
    emailPlaceholder: '[email protected]',
    brandingSubtitle: 'Your hiring OS',
    errors: {
      invalidCredentials: 'Check your email and password and try again.',
    },
  },
  routes: {
    login: '/login',
    register: '/sign-up',
    forgotPassword: '/forgot',
    updatePassword: '/reset',
    appHome: '/app',
  },
  branding: {
    showBrandPanel: false,
  },
  providers: [
    { id: 'google' },
    { id: 'github', label: 'Continue with GitHub' },
  ],
  redirects: {
    passwordResetRedirectTo: 'https://app.example.com/auth/update-password',
  },
  layout: {
    variant: 'stacked',
    cardClassName: 'shadow-xl',
  },
};

<SupabaseAuthProvider supabaseClient={supabase} ui={authUI}>
  {/* routes */}
</SupabaseAuthProvider>

Text overrides and i18n

• Every text override accepts a ReactNode so you can supply rich content.
• When no override exists, the package falls back to react-i18next using the auth and common namespaces.
• Use useAuthText() to resolve overrides or i18n keys in custom components.

Redirects and password recovery

• redirects.passwordResetRedirectTo is used for reset emails.
• redirects.magicLinkRedirectTo is used for magic link sign-in.
• redirects.oauthRedirectTo is used for OAuth providers.

Make sure the URLs are allowed in your Supabase project settings.

Layout variants

Use layout.variant to switch between layouts:

• split (default): brand panel on the left (desktop).
• stacked: brand panel on top, form below.
• embedded: minimal padding and lighter card for modals/embeds.

Error handling and flow state

• mapAuthError normalizes Supabase errors into a small set of codes.
• useAuthErrorMessage turns errors into UX-safe messages (with overrides).
• AuthAlert displays standardized alerts.
• useAuthFlow gives you status, isPending, and isSuccess for button and success states.

import type { AuthError } from '@supabase/supabase-js';
import { AuthAlert, useAuthErrorMessage, useAuthFlow } from '@dopomogai/supabase-client/react';

const flow = useAuthFlow();
const { resolveErrorMessage } = useAuthErrorMessage();

const handleError = (error: AuthError | null) => {
  flow.fail(resolveErrorMessage(error));
};

{flow.isError ? <AuthAlert message={flow.error} /> : null}

Organizations and account status (foundations)

Use these optional helpers to start modeling orgs and account states without custom glue code.

import type { AccountStatusConfig, OrgServiceConfig } from '@dopomogai/supabase-client';
import { AccountStatusProvider, OrgProvider } from '@dopomogai/supabase-client/react';

const accountStatusConfig: AccountStatusConfig = {
  statusField: 'account_status',
  profile: { table: 'profiles', statusColumn: 'account_status' },
};

const orgConfig: OrgServiceConfig = {
  organizationsTable: 'organizations',
  membershipsTable: 'memberships',
  invitesTable: 'invites',
};

<SupabaseAuthProvider supabaseClient={supabase}>
  <AccountStatusProvider config={accountStatusConfig}>
    <OrgProvider config={orgConfig}>{/* app */}</OrgProvider>
  </AccountStatusProvider>
</SupabaseAuthProvider>

SSR helpers

For server-side auth, use the SSR entrypoint (requires @supabase/ssr).

import { createServerSupabaseClient } from '@dopomogai/supabase-client/ssr';

const supabase = createServerSupabaseClient({
  supabaseUrl,
  supabaseKey,
  cookies: {
    getAll: () => cookieStore.getAll(),
    setAll: (cookies) => cookies.forEach(({ name, value, options }) => cookieStore.set(name, value, options)),
  },
});

Core usage (non-React)

import { initSupabase, AuthService } from '@dopomogai/supabase-client';

const supabase = initSupabase('url', 'key');
const authService = new AuthService(supabase);

await authService.signInWithEmailPassword('[email protected]', 'password');

API exports

Core (@dopomogai/supabase-client)

• initSupabase(url, key)
• AuthService
• AccountStatusService
• OrgService
• AuthOperationResponse, LogoutResponse, and related types
• AuthErrorCode, mapAuthError, defaultAuthErrorMessages

React (@dopomogai/supabase-client/react)

• SupabaseAuthProvider
• useSupabaseClient, useSession, useUser, useIsLoading
• useAuthService, useAuth, useAuthFlow
• useAuthText, useAuthErrorMessage, useAuthUI
• AuthLayout, AuthAlert, OAuthProviders, OrgSwitcher
• AccountStatusProvider, RequireAccountStatus, useAccountStatus
• OrgProvider, useOrganization, useOrganizations, useOrgSwitcher
• AuthUIConfig and related types

Pages (@dopomogai/supabase-client/pages)

• LoginPage, RegisterPage, ForgotPasswordPage, UpdatePasswordPage, InviteAcceptPage

SSR (@dopomogai/supabase-client/ssr)

• createServerSupabaseClient
• getServerSession, getServerUser, requireServerSession, requireServerUser

Package docs

Internal project docs live in docs/ (findings, improvement plan, tasks, QA checklist).