@mayrlabs/auth-nextjs
v0.4.1
Published
The official Next.js App Router integration for @mayrlabs/auth featuring Middleware guards, Server Actions utilities, and React Context bindings.
Maintainers
youngmayorReadme
@mayrlabs/auth-nextjs
The Next.js integration wrapper for the MayR Labs authentication ecosystem (@mayrlabs/auth). Providing out-of-the-box Route Handlers, React Context Providers, Server Actions hooks, and Middleware protection for Next.js applications (App Router).
✨ Features
- ⚡ Modular SDK: Dedicated
clientandissuerexports for optimized bundling. - ⚡ Next.js Integration: Optimized handlers for Callback, Server Components, and Actions.
- ⚛️ React Providers: Out-of-the-box Context Providers and hooks for client-side user access.
- 🚀 Zero Config: Inherits all secure logic (PS256, JWK, JWT decoding) from
@mayrlabs/authseamlessly.
🚀 Getting Started
Installation
npm install @mayrlabs/auth-nextjsEnvironment Variables
The SDK now strictly validates environment variables using Zod. Ensure the following are set in your .env:
Client Auth Variables (createNextClientAuth)
MAYRLABS_CLIENT_ID: (Required) Your application's unique ID.MAYRLABS_CLIENT_SECRET: (Required) Your application's secret key.MAYRLABS_CLIENT_AUDIENCE: (Required) The audience validation for tokens.MAYRLABS_AUTH_PUBLIC_JWK: (Optional) Your application's Public JWK. Not required ifremotePublicKey: trueis set.MAYRLABS_ACCOUNT_URL: (Default:https://myaccount.mayrlabs.com) The URL of the central account center.MAYRLABS_AUTH_SESSION_KEY: (Default:mayrlabs-auth-session) Local session cookie key.MAYRLABS_AUTH_ERROR_REDIRECT: (Default:/login) Path to redirect on error.MAYRLABS_AUTH_SUCCESS_REDIRECT: (Default:/dashboard) Path to redirect on success.
Issuer Auth Variables (createNextIssuerAuth)
MAYRLABS_AUTH_PRIVATE_JWK: (Required) The private JWK for signing tokens.MAYRLABS_AUTH_PUBLIC_JWK: (Required) The public JWK for verifying session tokens.MAYRLABS_AUTH_ISSUER: (Default:auth.mayrlabs.com) The token issuer string.
🏢 Client SDK Usage (createNextClientAuth)
Initialize your client auth utilities. All configuration is primarily handled via environment variables.
// lib/auth.ts
import { createNextClientAuth } from "@mayrlabs/auth-nextjs";
export const {
handleCallback,
getUser,
getUserOrThrow,
getUserOrRedirect,
authProxy,
logoutHandler,
AuthProvider,
} = createNextClientAuth({
remotePublicKey: true, // Automatically fetches JWKS from {ACCOUNT_URL}/.well-known/jwks.json
});⚛️ React Setup
The AuthProvider is a Server Component that should be wrapped around your layout. It automatically handles the session and provides the context to client components.
// app/layout.tsx
import { AuthProvider } from "@/lib/auth";
export default function RootLayout({ children }) {
return (
<html>
<body>
<AuthProvider>{children}</AuthProvider>
</body>
</html>
);
}Use the useUser hook in any Client Component:
"use client";
import { useUser } from "@mayrlabs/auth-nextjs/provider";
export function UserProfile() {
const { user } = useUser();
if (!user) return <p>Not logged in</p>;
return <p>Hello, {user.email}!</p>;
}🏛️ Issuer SDK Usage (createNextIssuerAuth)
For applications acting as identity providers (e.g., the Account App).
// lib/issuer-auth.ts
import { createNextIssuerAuth } from "@mayrlabs/auth-nextjs/issuer";
export const {
setup,
getUser,
getUserOrThrow,
logoutHandler,
} = createNextIssuerAuth();Methods
getUser(): (Async) Retrieves the user payload from the session cookie.logoutHandler(request): A Route Handler compatible function to clear the session.
🔒 Shared Utilities
🛡️ Proxy Protection (Middleware)
// middleware.ts
import { authProxy } from "@/lib/auth";
import { type NextRequest, NextResponse } from "next/server";
export default async function middleware(request: NextRequest) {
if (request.nextUrl.pathname.startsWith("/dashboard")) {
return authProxy(request);
}
return NextResponse.next();
}🚪 SSO Callback
// app/api/auth/callback/route.ts
import { handleCallback } from "@/lib/auth";
export const GET = handleCallback;Built with discipline by MayR Labs. Build. Ship. Repeat intelligently.