auth-flow-kit - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #golang #go #android #macos #nodejs #awesome #security #ios #mcp #openai

auth-flow-kit

(★ 257)

A global authentication state toolkit for React with prebuilt UI screens and a globally accessible useAuth() hook. No separate stores, persistence layers, or setup files required. Integrates directly at the app layout level, with auth state remaining consistent across refreshes without manual persistence.

파일 탐색기

최종 버전 다운로드 (.zip)

- App.css
- App.tsx
- main.tsx
- vite.svg
- - LoginScreen.tsx
  - PasswordResetScreen.tsx
  - SignupScreen.tsx
- AuthContext.tsx
- http.ts
- index.ts
- Protected.tsx
- types.ts
.gitignore
BUG_HUNTING_GUIDE.md
bun.lock
bun.lockb
CODE_OF_CONDUCT.md
COMMIT_MESSAGES.md
CONTRIBUTING.md
eslint.config.js
index.html
LICENSE
package-lock.json
package.json
README.md
SECURITY.md
tsconfig.json
tsup.config.ts
vite.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @kendevelops/auth-flow-kit

A beginner‑friendly authentication toolkit for **React** and **Next.js 13–16 (App Router)**.

This is literally the **simplest and shortest setup** for your Next.js apps.
You do **not** need extra wrapper files.

---

It gives you:

- Global auth state (Redux / Zustand‑style, but zero setup)
- Prebuilt auth UI screens (Login, Signup, Reset)
- A simple `useAuth()` hook you can use anywhere

This library is intentionally designed to be **easy to understand**, even if you are new to authentication.

---

## 🔄 No Persistence Setup Needed

auth-flow-kit keeps authentication state in memory by default, and automatically restores the session when the app reloads.

**What this means in practice:**

From a developer's point of view:

> "I refresh the page and I'm still logged in."

That's it.

---

## 📦 Installation

```bash
npm install @kendevelops/auth-flow-kit
```

```bash
yarn add @kendevelops/auth-flow-kit
```

```bash
bun add @kendevelops/auth-flow-kit
```

---

# 🚀 Usage with Next.js App Router (Recommended)

---

## Step 1: Wrap your app in `app/layout.tsx`

> Yes, `layout.tsx` can be a client component when it hosts providers. This is normal.

```tsx
// app/layout.tsx
"use client";

import { AuthProvider } from "@kendevelops/auth-flow-kit";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AuthProvider
          config={{
            baseURL: "https://your-backend-url.com",
            endpoints: {
              login: "/auth/login",
              signup: "/auth/signup",
              forgot: "/auth/forgot",
            },
          }}
        >
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}
```

This makes auth **global** and available everywhere.

---

## Step 2: Use auth screens in `app/page.tsx`

```tsx
// app/page.tsx
"use client";

import {
  LoginScreen,
  SignupScreen,
  PasswordResetScreen,
  Protected,
  useAuth,
} from "@kendevelops/auth-flow-kit";

import { useEffect, useState } from "react";

export default function Home() {
  const { user } = useAuth();
  const [page, setPage] = useState<"login" | "signup" | "reset" | "dashboard">(
    "login",
  );

// Keep UI in sync with auth (important on refresh)
  useEffect(() => {
    if (user) setPage("dashboard");
  }, [user]);

return (
    <>
      {page === "login" && <LoginScreen />}
      {page === "signup" && <SignupScreen />}
      {page === "reset" && <PasswordResetScreen />}

{page === "dashboard" && (
        <Protected>
          <Dashboard />
        </Protected>
      )}
    </>
  );
}

function Dashboard() {
  const { user, logout } = useAuth();

return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome {user?.name}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}
```

---

# 🔒 Protecting Components

Wrap anything that requires authentication:

```tsx
<Protected>
  <SecretArea />
</Protected>
```

- While loading → shows a loading state
- If not authenticated → renders nothing (or redirects if configured)

---

# 🧠 Using `useAuth()` Anywhere

```tsx
"use client";
import { useAuth } from "@kendevelops/auth-flow-kit";

export default function Navbar() {
  const { user, logout } = useAuth();

return (
    <nav>
      {user ? (
        <>
          <span>Hello {user.name}</span>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <span>Not logged in</span>
      )}
    </nav>
  );
}
```

---

# 🌐 React (Non‑Next.js) Usage

```tsx
import { AuthProvider, LoginScreen } from "@kendevelops/auth-flow-kit";

export default function App() {
  return (
    <AuthProvider
      config={{
        baseURL: "https://your-backend-url.com",
        endpoints: {
          login: "/auth/login",
          signup: "/auth/signup",
          forgot: "/auth/forgot",
        },
      }}
    >
      <LoginScreen />
    </AuthProvider>
  );
}
```

---

# 🛠 Backend Requirements

This section defines the exact API contract your backend must implement. The library makes three types of requests and expects specific JSON response shapes.

---

## POST `/auth/login`

**Request body:**

```json
{
  "email": "user@example.com",
  "password": "secret123"
}
```

**Success response (200):**

```json
{
  "accessToken": "your-token-here",
  "user": {
    "id": "usr_abc123",
    "name": "Jane Doe",
    "email": "user@example.com"
  }
}
```

**Error response (4xx):**

```json
{ "message": "Invalid email or password" }
```

The `message` field is displayed directly to the user in the login form.

---

## POST `/auth/signup`

**Request body:**

```json
{
  "name": "Jane Doe",
  "email": "user@example.com",
  "password": "secret123"
}
```

> You can include extra fields in your signup form and pass them through — the library forwards the full payload as-is.

**Success response (200):** Same shape as the login response.

```json
{
  "accessToken": "your-token-here",
  "user": {
    "id": "usr_xyz789",
    "name": "Jane Doe",
    "email": "user@example.com"
  }
}
```

---

## POST `/auth/forgot` _(optional)_

Only needed if you use `<PasswordResetScreen />`.

**Request body:**

```json
{ "email": "user@example.com" }
```

**Response:** Any `2xx` is treated as success. The library does not read the response body — it just shows a "Check your email" confirmation. A `404` logs a descriptive console error with guidance on fixing `config.endpoints.forgot`.

---

## Response field reference

| Field          | Type   | Required | Description                                                                                         |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `accessToken`  | string | ✅       | Stored in `localStorage` and sent as `Authorization: Bearer <token>` on authenticated requests.     |
| `user`         | object | ✅       | Stored in `localStorage` and exposed via `useAuth().user`.                                          |
| `user.id`      | string | ✅       | Unique user identifier.                                                                             |
| `user.name`    | string | ✅       | Display name used in your UI.                                                                       |
| `user.email`   | string | ✅       | User's email address.                                                                               |
| `refreshToken` | string | ❌       | Accepted but not used by the library for now, updating soon. You can include it for your own logic. |

---

## How session persistence works

auth-flow-kit handles persistence entirely on the client — **your backend does not need a session restore or `/me` endpoint.**

On successful login or signup:

- `accessToken` is saved to `localStorage` as `afk_access_token`
- `user` is saved to `localStorage` as `afk_user`

On page reload, `AuthProvider` reads `afk_user` directly from `localStorage` and restores the session instantly — no network request is made.

On logout, both keys are removed.

---

# 🎯 Who This Library Is For

- Developers who want to go straight into building their app before worrying about auth
- MVP builders
- SaaS dashboards
- Internal tools
- Learners who want to understand authentication

If you already have a backend and just want auth to **work**, this library is for you.

---

# 🎉 Summary

**auth-flow-kit** gives you:

- Global auth state (no reducers, no stores)
- Prebuilt auth UI screens
- Simple backend requirements
- Refresh‑safe authentication
- Works with Next.js and plain React

Authentication, without the chaos.