nuxt-auth

You can manage the session lifecycle using customizable refresh behavior. This can be configured via the RefreshHandler to:

• Refresh the session periodically.
• Refresh the session when a tab regains focus.
• Perform a one-time session fetch on page load, followed by fetches triggered by specific actions like navigation.

The term provider in NuxtAuth can refer to two distinct concepts depending on the context:

1. Module-level Provider: The authentication strategy selected in your Nuxt configuration via the provider.type key. Supported types include local, refresh, or authjs.
2. OAuth Provider: The specific external service (e.g., Google, GitHub) used when the authjs module type is selected.

In NuxtAuth, understanding where your code executes is critical for managing authentication state correctly:

• application / application-side / universal-application: Refers to Nuxt code that is universally rendered. This code runs on both the server-side and the client-side (e.g., components, composables, and plugins). Because it executes twice, authentication logic or state access may behave differently depending on the environment.
• server / server-side: Refers to code that runs exclusively on the server, such as files within the ~/server directory (API routes, server middleware).

Since the JWT token is stored in a cookie accessible to the server, you cannot access it directly in client-side Vue components. To access JWT data in your .vue pages, you have two options:

1. Create an API endpoint: Create a server-side route that uses getToken to return the token, then fetch that endpoint from your component.
2. Inject data into the session: Modify the jwt callback within your NuxtAuthHandler configuration to include specific token data in the session object, making it available via the useAuth composable.

@sidebase/nuxt-auth provides multiple layers of protection:

• Application-side protection: Use middleware to protect the full application globally or protect specific pages locally.
• Server-side protection: Use server-side middleware and endpoint protection to secure your API routes and server logic.

NuxtAuth is designed as a wrapper around existing, trusted open-source implementations rather than a ground-up rewrite. Specifically, it wraps NextAuth.js to leverage its mature ecosystem of authentication providers and security implementations.

Key architectural decisions include:

• NextAuth.js Integration: Utilizing the logic from the Next.js ecosystem to ensure stability and provider support.
• Nuxt-native Composables: Translating NextAuth.js client logic into Nuxt 3+ patterns, such as the useAuth composable.
• Lifecycle Management: The session lifecycle is triggered via a Nuxt plugin rather than the useAuth composable itself, allowing useAuth to operate as a synchronous operation for better developer experience.

In @sidebase/nuxt-auth, the baseURL acts as a prefix for authentication requests. When defining endpoints in your provider configuration, the final URL is determined by the following logic:

1. Prefixing: If an endpoint path is a relative path (e.g., /login), it is prepended with the baseURL.
2. Full URLs: If an endpoint path is a fully specified URL (e.g., https://example.com/user), the baseURL is ignored for that specific call, and the provided URL is used directly.

This allows you to mix local authentication routes with external identity provider endpoints.

export default defineNuxtConfig({
  auth: {
    baseURL: 'https://example.com/api/auth',

    provider: {
      type: 'local',
      endpoints: {
        // The call would be made to `https://example.com/api/auth/login`
        signIn: { path: '/login', method: 'post' },
      }
    }
  }
})

The library supports two primary providers depending on your application type:

• authjs: Designed for non-static applications. It brings the reliability of Auth.js / NextAuth.js to the Nuxt 3+ ecosystem with a native developer experience.
• local: Designed for static pages that rely on an external backend using a credential flow. The Local Provider also supports refresh tokens.

To protect all pages in your application by default, enable the global middleware in your nuxt.config.ts. When global middleware is enabled, you can disable it for specific pages using definePageMeta with auth: false.

export default defineNuxtConfig({
  modules: ['@sidebase/nuxt-auth'],
  auth: {
    globalAppMiddleware: true
  }
})