npm package: @simplifyid/auth-module
Description: Reusable Supabase Auth package for Refine applications
Author: Screaming Kids
Latest version: 0.1.4

# @simplifyid/auth-module

> **Plug‑and‑play Supabase authentication for Refine + React Router v6**

Drop the `<AuthModule />` component into your app and instantly get fully‑featured **Login / Signup / Forgot Password / Reset Password** pages – powered by Supabase Auth, themed with Tailwind & shadcn/ui, and 100 % TypeScript.

---

## ✨ Features

* **Supabase Auth** integration out‑of‑the‑box – just pass your project URL & `anon` key.
* **4 ready‑made routes** (`/login`, `/signup`, `/forgot-password`, `/reset-password`).
* **Social providers** (Google, GitHub, Apple, Azure) toggle‑able per config.
* **Theming & white‑label** – swap logo, colours, wording, or even load remote JSON.
* **Tailwind / shadcn** design system, fully responsive.
* **Tree‑shakable, dual ESM + CJS** bundle with generated .d.ts.

---

## 🔧 Installation

```bash
npm i @simplifyid/auth-module \
       react react-dom react-router-dom \
       @refinedev/core @supabase/supabase-js
# or
pnpm add @simplifyid/auth-module [...peer deps]
```

> **Peer deps** are kept as `peerDependencies` to avoid version clashes – install the same major versions that your app already uses.

---

## 🚀 Quick start

```tsx
import React from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { Refine } from "@refinedev/core";
import routerProvider from "@refinedev/react-router-v6";
import { AuthModule, makeSupabaseProvider } from "@simplifyid/auth-module";
import "@simplifyid/auth-module/dist/index.css"; // ★ import the premade styles

const authProvider = makeSupabaseProvider(
  import.meta.env.VITE_SUPABASE_URL!,
  import.meta.env.VITE_SUPABASE_ANON_KEY!
);

createRoot(document.getElementById("root")!).render(
  <BrowserRouter>
    <Refine routerProvider={routerProvider} authProvider={authProvider}>
      {/* your application routes go here */}
      <AuthModule
        config={{
          title: "ACME Portal",
          subtitle: "Sign in to manage stuff",
          logo: "/logo.svg",
          colors: { primary: "#4f46e5" },
          socialProviders: [
            { id: "google", name: "Google", enabled: true },
            { id: "github", name: "GitHub", enabled: true }
          ]
        }}
      />
    </Refine>
  </BrowserRouter>
);
```

The module mounts its own nested `Routes` element, so you only need to make sure the parent router (BrowserRouter / Refine) is in place.

---

## 🖌️ Theming

`<AuthModule />` accepts a **`config`** prop (or a remote JSON via `remoteConfigUrl`) that partially overrides the default theme.

```ts
interface AuthThemeProps {
  /** Partial theme object – every field is optional */
  config?: Partial<AuthThemeConfig>;
  /** Optional URL that returns `AuthThemeConfig` JSON.  Supersedes `config`. */
  remoteConfigUrl?: string;
}
```

### AuthThemeConfig (excerpt)

```ts
interface AuthThemeConfig {
  // Branding
  logo?: string;
  title: string;
  subtitle?: string;
  version?: string;

  // Colour palette (CSS vars) – override whatever you need
  colors: {
    primary: string;
    secondary: string;
    background: string;
    foreground: string;
    // ...etc
  };

  // Social login buttons
  socialProviders: Array<{
    id: "google" | "github" | "apple" | "azure";
    name: string;
    enabled: boolean;
  }>;

  // Layout toggles
  layout: {
    maxWidth: string; // e.g. "420px"
    padding: string;  // e.g. "2rem"
    centerContent: boolean;
    showLogo: boolean;
    showVersion: boolean;
  };

  // Custom wording per view (login, signup, forgot, reset)
  wording: { /* ... */ };
}
```

Any field you omit falls back to the built‑in defaults – so you can override as little or as much as you like.

---

## 🧩 API surface

| Export                                                 | Description                                              |
| ------------------------------------------------------ | -------------------------------------------------------- |
| `makeSupabaseProvider(url, anonKey, options?)`         | Returns a Refine‑style `authProvider` wired to Supabase. |
| `<AuthModule />`                                       | Renders the 4 auth pages and applies the theme provider. |
| `<AuthProvider>`                                       | Low‑level provider if you want to roll your own UI.      |
| React hooks: `useAuth()`, `useUser()`                  | Convenience hooks around Refine auth context.            |
| shadcn/ui primitives (`Button`, `Card`, `Input`, etc.) | Re‑exported so you can keep design consistency.          |

---

## 🤝 Contributing

1. `pnpm i` – install deps.
2. `pnpm dev` – watch build.
3. `pnpm test` – run Vitest.
4. PRs welcome!  Please follow Conventional Commits & run `pnpm lint` before pushing.

---

## 📄 License

MIT © 2025 SimplifyID