Next.js Auth Integration

Relevant source files

The following files were used as context for generating this wiki page:

• packages/auth/package.json
• packages/auth/src/index.test.ts
• README.md
• DECISIONS.md
• packages/eslint-config/index.js
• packages/auth/src/next.ts

Introduction

The Next.js Auth Integration in the wrelik-kit repository is implemented through the @wrelik/auth package. It serves as a vendor-agnostic adapter for Clerk, providing a standardized interface for authentication, session handling, and Role-Based Access Control (RBAC) across the Wrelik ecosystem. The primary goal of this integration is to prevent direct dependencies on vendor SDKs within application code, ensuring that switching authentication providers only requires updates to the adapter package rather than the entire codebase.

Sources: README.md:16-18, DECISIONS.md:14-18

Architecture and Design Principles

The integration follows an "Adapter-first" architecture. By wrapping the Clerk SDK, the system enforces best practices, simplifies the API surface area, and reduces vendor lock-in. Applications are strictly forbidden from importing Clerk SDKs directly, a constraint enforced by repository-wide linting rules.

Sources: README.md:9-14, packages/eslint-config/index.js:15-21

Core Components

Component	Responsibility
@wrelik/auth	Main adapter package providing unified auth logic.
Clerk	The underlying third-party authentication provider.
@wrelik/errors	Provides typed errors like AuthRequiredError for auth failures.
ESLint Config	Prevents direct imports of @clerk/nextjs in consuming apps.

Sources: packages/auth/package.json:16, DECISIONS.md:5, packages/eslint-config/index.js:15-21

Authentication Flow

The following diagram illustrates how the @wrelik/auth package mediates between the application logic and the Clerk provider.

This flow ensures that the application only interacts with the standardized session object provided by the adapter.
Sources: README.md:57-59, DECISIONS.md:14-18

Implementation Details

The integration is split into a general core and a specific Next.js entry point. The package exports multiple entry points to support different environments.

Sources: packages/auth/package.json:10-13

Session Parsing and Validation

The system converts provider-specific authentication objects into a standard internal session format. This format typically includes the userId, tenantId (mapped from Clerk's orgId), and user roles.

Key Functions

• requireUser(session): Validates that a session contains a valid userId. If the user is null, it throws an AuthRequiredError.
• fromClerkAuth(clerkAuth): A parser that transforms the raw Clerk authentication object into the standardized internal representation.

Sources: packages/auth/src/index.test.ts:5-14, packages/auth/src/index.test.ts:27

Usage Constraints

To maintain the integrity of the adapter-first architecture, specific ESLint rules are configured to error out if a developer attempts to bypass the @wrelik/auth package.

// From packages/eslint-config/index.js
'no-restricted-imports': [
  'error',
  {
    paths: [
      {
        name: '@clerk/nextjs',
        message: 'Please use @wrelik/auth instead.',
      }
    ]
  }
]

Sources: packages/eslint-config/index.js:15-21

Conclusion

The Next.js Auth Integration provides a robust, abstracted layer for identity management. By utilizing the @wrelik/auth package, developers can leverage Clerk's features while maintaining a clean separation between application business logic and the underlying authentication infrastructure. This design ensures the Wrelik ecosystem remains flexible and resilient to vendor changes.