How kinde-oss/kinde-auth-nextjs works
Project Type and Purpose
• This is a NextJS SDK package (“Kinde NextJS”) designed to simplify authentication and session management with the Kinde identity platform.
• It ships as an NPM package, exposes both server-side helpers (middleware, API handlers, session managers) and client-side React hooks/components.
• A “playground” NextJS App Router sample app shows how to consume the SDK via npm link and exercise its auth flows.
Key Directories and Their Roles
• /src – The core SDK code, subdivided into:
• api-client.js – low-level HTTP client for talking to Kinde’s API
• authMiddleware/ – Express-style middleware to protect API routes
• handlers/ – NextJS API route handler implementations (login, logout, callback, etc.)
• frontend/ – React providers, hooks, component factories, utils for in-browser auth
• session/ – Helpers to read/write tokens, flags, permissions, users from session store
• middleware/ – NextJS middleware integration point
• utils/ – Utility functions (cookie ops, JWT validation, URL generators)
• routerClients/ – Abstractions for NextJS App vs Pages Router
• server/ – Shared entry point for server code
• /playground – A NextJS App Router example app using the SDK:
• /app/api/auth/[...kindeAuth] – API routes orchestrating the OAuth flow
• /app/dashboard, /app/protect – Sample protected pages
• AuthProvider.tsx – React context provider from SDK
• Config & Tooling root:
• rollup.config.mjs – Bundler config for packaging the SDK
• jest.config.mjs, vitest.config.ts – Testing setup
• .github/workflows – CI (build, test) and publish pipelines
• pnpm-workspace.yaml – Monorepo management
a. Main Components
• SDK Package
• Client-side layer: React Provider, hooks, components
• Server-side layer: NextJS middleware, API handlers, session managers
• Utilities: cookie management, JWT validation, router clients
• Playground NextJS App
• Frontend pages (protected vs. public)
• API routes that delegate to SDK handlers
• Env config (.env.local) containing Kinde credentials
• External Service
• Kinde Auth API (OAuth endpoints, token introspection, user info)
• CI/CD Pipeline
• GitHub Actions for linting, unit tests, bundle, release to NPM
b. Relationships & Data Flow
• User → Playground Frontend (React app)
• On first load, AuthProvider initializes session (reads cookies)
• For protected pages, React hooks call SDK’s client or redirect to login
• Playground Frontend → Playground API Routes
• Calls /api/auth/login, /api/auth/callback, /api/protected
• NextJS routes use SDK handlers (in src/handlers)
• SDK Handlers → Kinde Auth API
• Redirect user to Kinde’s OAuth endpoint
• On callback, exchange code for tokens, set cookies
• Subsequent requests → NextJS Middleware (src/middleware)
• Validates session via cookies or introspection
• Populates request context or rejects
• CI/CD → GitHub Actions
• On push: run lint, tests (Jest/Vitest), build (Rollup)
• On release tag: publish to NPM
c. Architectural Patterns & Principles
• Modular separation of client vs. server concerns
• NextJS App Router conventions (middleware, app/api, React Server Components)
• Dependency Injection via React Context (AuthProvider)
• Single source of truth for session state (cookies + in-memory)
• Abstraction over routing (AppRouter vs. PagesRouter)
d. Key Technologies
• NextJS (App Router)
• React + TypeScript
• Rollup for ESM bundling
• Jest & Vitest for testing
• PNPM workspace for monorepo
• GitHub Actions for CI/CD