How sidebase/nuxt-auth works
Main Components
• Nuxt Auth Module Core – Represent the core module file (src/module.ts) which acts as the entry point when the module is injected into a Nuxt app via nuxt.config.ts.
• Runtime Logic:
• Client-side functionalities under src/runtime (e.g., composables for authentication, such as useAuth and useAuthState, utilities for routing/navigations, and middleware – like sidebase-auth).
• Server-side components (found in src/runtime/server) including server plugins, services (e.g., authjs service and error handling), and API endpoints (both in the main module and in playground examples).
• Provider Implementations – Clearly differentiate between the “authjs” provider and the “local” provider. Note that separate playground directories (playground-authjs and playground-local) illustrate these implementations.
• Documentation – Highlight the docs folder (with its vitepress structure), which acts as a user guide for setup, configuration, and upgrades. This documentation ties into how the module is used in real-world scenarios.
• Testing/CI & Development Tools – Although secondary to runtime functionality, include elements like GitHub workflows, linting, and testing configurations (Vitest, Playwright, etc.) which illustrate the project’s continuous integration and quality assurance pipelines.
Relationships and Interactions
• A two-pronged runtime split:
• Client Side: Illustrate how composables (useAuth, useAuthState) interact with application-side session management and middleware (e.g., sidebase-auth) to protect pages.
• Server Side: Display how the server plugins and services (assert origin checks, token retrieval, error handlers) interconnect to provide secure API endpoints.
• “Playground Applications” to signify testing environments:
• One playground simulates a non-static Nuxt 3 app with provider “authjs”.
• The other simulates a static page with an external authentication backend (“local”), using separate front-end and back-end instances.
• Optionally, denote the integration with external OAuth providers (like GitHub, Google, etc.) as part of the authentication flow.
Architectural Patterns and Design Principles
• Separation of concerns: distinct modules for client- and server-side logic, isolation of provider-specific behaviors, and a clear division between the core module code and support infrastructure (such as testing and CI).
• Usage of composable functions and middleware that adhere to the modern reactive programming practices found in Nuxt 3.
• Mention the extensible and pluggable nature of the module which allows users to customize refresh behaviors and session handling.