# @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 (
{children}
);
}
```
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" && }
{page === "signup" && }
{page === "reset" && }
{page === "dashboard" && (
)}
);
}
function Dashboard() {
const { user, logout } = useAuth();
return (
Dashboard
Welcome {user?.name}
);
}
```
---
# 🔒 Protecting Components
Wrap anything that requires authentication:
```tsx
```
- 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 (
);
}
```
---
# 🌐 React (Non‑Next.js) Usage
```tsx
import { AuthProvider, LoginScreen } from "@kendevelops/auth-flow-kit";
export default function App() {
return (
);
}
```
---
# 🛠 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 ``.
**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 ` 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.