OmniBase NextJS 13+ SDK
npm install @omnibase/nextjsComplete authentication and multi-tenant solution for Next.js applications
The Omnibase Next.js SDK provides seamless integration of Ory Kratos authentication flows and multi-tenant management for Next.js applications. Built with TypeScript support, React Server Components, and modern Next.js patterns, it offers a production-ready solution for complex authentication scenarios.
!npm version
!License
!TypeScript
| Feature | Description | Documentation |
|---------|-------------|---------------|
| Authentication Flows | Complete login, registration, recovery, settings, and verification flows | Auth Docs |
| Session Management | Server-side session handling with React Context integration | Session Docs |
| Flow Router | Automatic routing and handling of authentication flows | Flow Router |
| Multi-tenant Support | Organization management with tenant switching and invitations | Tenant Docs |
| Middleware Integration | Next.js middleware for route protection and session management | Middleware Docs |
| Server Actions | Next.js server actions for seamless data mutations | Server Actions |
``tsx
// app/layout.tsx
import { SessionProvider } from '@omnibase/nextjs/auth';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
return (
// middleware.ts (REQUIRED for authentication)
import { createOmniBaseMiddleware } from '@omnibase/nextjs/middleware';
export default createOmniBaseMiddleware();
export const config = {
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
};
// app/auth/[...flow]/page.tsx
import { FlowRouter } from '@omnibase/nextjs/auth';
export default function AuthPage({
params,
searchParams
}: {
params: Promise<{ flow: string[] }>;
searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}) {
return (
searchParams={searchParams}
url="/auth"
flowMap={{
login: (flow) =>
Installation
`bash
npm
npm install @omnibase/nextjsyarn
yarn add @omnibase/nextjspnpm
pnpm add @omnibase/nextjsbun
bun add @omnibase/nextjs
`Environment Configuration
`bash
Required
OMNIBASE_AUTH_URL=http://localhost:4433 # Your OmniBase Auth URL
SUPABASE_URL=http://localhost:8080 # Your Supabase API URL
Optional - Tenant Management
OMNIBASE_ONBOARDING_REDIRECT_URL=/dashboard # Redirect after tenant creation
OMNIBASE_DELETE_TENANT_REDIRECT_URL=/ # Redirect after tenant deletion
OMNIBASE_ACCEPT_TENANT_INVITE_REDIRECT_URL=/dashboard # Redirect after accepting invite
`Complete Workflow Example
This example demonstrates a complete authentication and multi-tenant workflow:
`tsx
// app/layout.tsx - Setup SessionProvider
import { SessionProvider } from '@omnibase/nextjs/auth';export default async function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}// app/dashboard/page.tsx - Protected route with session access
import { getServerSession } from '@omnibase/nextjs/auth';
import { redirect } from 'next/navigation';
export default async function Dashboard() {
const session = await getServerSession();
if (!session) {
redirect('/auth/login');
}
return (
Welcome, {session.identity.traits.email}
Active Tenant: {session.tenant?.name}
);
}// app/tenant/create/page.tsx - Create tenant with server action
import { createTenantAction } from '@omnibase/nextjs/auth';
import { useActionState } from 'react';
export default function CreateTenant({ userId }: { userId: string }) {
const [state, formAction, isPending] = useActionState(createTenantAction, null);
return (
);
}
`Middleware
⚠️ REQUIRED: The OmniBase middleware is essential for authentication to work properly. Without it, sessions will not be validated and authentication flows will not function.
`tsx
// middleware.ts
import { createOmniBaseMiddleware } from '@omnibase/nextjs/middleware';export default createOmniBaseMiddleware();
export const config = {
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
};
`The middleware automatically handles:
- Session validation (required for authentication)
- Authentication redirects
- Cookie management
- Ory Kratos integration
Authentication
The SDK provides comprehensive authentication support through Ory Kratos integration. Access session data on the server using
getServerSession(), handle authentication flows with FlowRouter, and protect routes with middleware.Multi-tenant
createTenantAction), switching (switchActiveTenantAction), and deleting tenants (deleteTenantAction). Handle user invitations with acceptTenantInviteAction.Error Handling
The SDK provides consistent error handling across all operations:
`tsx
import { createTenantAction } from '@omnibase/nextjs/auth';export default function CreateTenantForm() {
const [state, formAction, isPending] = useActionState(createTenantAction, null);
return (
);
}
`Server Actions
All server actions return structured responses:
`tsx
// Pattern: { success: boolean, error?: string, message?: string }
// Some actions redirect on success (create, delete, accept invite)
const [state, action, isPending] = useActionState(createTenantAction, null);
``| Feature | Description |
|---------|-------------|
| Server-Side Sessions | All session handling happens on the server for maximum security |
| Encrypted Cookies | JWT tokens are stored in secure, HTTP-only cookies |
| CSRF Protection | Built-in CSRF protection for all server actions |
| Automatic Token Management | Seamless token refresh and rotation |
Runtime Environments
- ✅ Next.js 15+ (App Router)
- ✅ Next.js 13+ (App Router)
- ✅ Node.js 18+
- ✅ Edge Runtime
Frameworks
- ✅ Next.js App Router
- ✅ React Server Components
- ✅ React Server Actions
- ✅ Next.js Middleware
Module Systems
- ✅ ESM (ES Modules)
- ✅ CommonJS
- ✅ TypeScript
Auth Module: Provides React Server Components, session management, flow routing, and server actions for handling all Ory Kratos authentication flows including login, registration, recovery, verification, and user settings.
Middleware Module: Offers Next.js middleware integration with OmniBase for automatic session validation, authentication redirects, and secure cookie management at the edge.
Tenant Module: Enables multi-tenant functionality with server actions for creating, switching, deleting tenants, and managing user invitations with automatic JWT token management.
- @omnibase/core-js - Framework-agnostic core JavaScript SDK with shared functionality
- @omnibase/shadcn - Pre-built authentication UI components using shadcn/ui
MIT License - see LICENSE file for details.