Configuration

NuxtAuth offers a wide range of configuration options that can be defined inside the nuxt.config.ts. You can find an example of a fully configured authjs app below:

export default defineNuxtConfig({
  modules: ['@sidebase/nuxt-auth'],
  auth: {
    isEnabled: true,
    disableServerSideAuth: false,
    originEnvKey: 'AUTH_ORIGIN',
    baseURL: 'http://localhost:3000/api/auth',
    provider: { /* your provider config */ },
    sessionRefresh: {
      enablePeriodically: true,
      enableOnWindowFocus: true,
    }
  }
})

isEnabled

• Type: boolean
• Default: true

Whether the module is enabled at all

originEnvKey

• Type: string
• Default: AUTH_ORIGIN

The name of the environment variable that holds the origin of the application. This is used to determine the origin of your application in production.

By default, NuxtAuth will look at AUTH_ORIGIN environment variable and runtimeConfig.authOrigin.

TIP

If you want to use runtimeConfig and NUXT_ prefixed environment variables, you need to make sure to also define the key inside runtimeConfig, because otherwise Nuxt will not acknowledge your env variable (issue #906, read more here).

export default defineNuxtConfig({
  auth: {
    originEnvKey: 'NUXT_YOUR_ORIGIN'
  },
  runtimeConfig: {
    yourOrigin: ''
  }
})

You can read additional information on origin determining here.

disableServerSideAuth

• Type: boolean
• Default: false

Forces your server to send a "loading" authentication status on all requests, thus prompting the client to do a fetch. If your website has caching, this prevents the server from caching someone's authentication status. This affects the entire site; for route-specific rules add disableServerSideAuth on routeRules. Read more here.

baseURL

• Type: string | undefined
• Default:
  • AuthJS Provider:
    • Development: http://localhost:3000/api/auth
    • Production: undefined
  • Local / Refresh Provider: /api/auth

The full url at which the app will run combined with the path to authentication. You can set this differently depending on your selected authentication-provider:

• authjs: You must set the full URL, with origin and path in production. You can leave this empty in development
• local: You can set a full URL, but can also leave this empty to fallback to the default value of /api/auth or set only the path.

authjs Provider

baseURL can be undefined during development but must be set to the combination of origin + path that points to your NuxtAuthHandler for production. The origin consists out of:

• scheme: http / https
• host: e.g., localhost, example.org, google.com
• port: empty (implies :80 for http and :443 for https), :3000, :8888
• path: the path that directs to the location of your NuxtAuthHandler e.g. /api/auth

local Provider

Defaults to /api/auth for both development and production. Setting this is optional, if you set it you can set it to either:

• just a path: Will lead to nuxt-auth using baseURL as a relative path appended to the origin you deploy to. Example: /backend/auth
• an origin and a path: Will lead to nuxt-auth using baseURL as an absolute request path to perform requests to. Example: https://example.com/auth

WARNING

If you point to a different origin than the one you deploy to you likely have to take care of CORS: Allowing cross origin requests.

provider

• Type: ProviderAuthjs | ProviderLocal
• Default: undefined

Configuration of the authentication provider. Different providers are supported:

• AuthJS: See configuration options here
• Local: See configuration options here

sessionRefresh

• Type: SessionConfig | boolean
• Default: { enablePeriodically: false, enableOnWindowFocus: true, refreshHandler: RefreshHandler }

Configuration of the application-side session. You can configure the following attributes:

enablePeriodically

• Type: boolean | number
• Default: undefined

Whether to refresh the session every X milliseconds. The refresh will only happen if a session already exists. Setting this to a number X will refresh the session every X milliseconds. Setting this to true is equivalent to enablePeriodically: 1000, the session will be refreshed every second. Setting this to false will turn the session refresh off.

enableOnWindowFocus

• Type: boolean
• Default: true

Whether to refresh the session every time the browser window is refocused.

refreshHandler

• Type: string
• Default: undefined

To customize the session refreshing you can provide the path to your refresh handler. When setting this option, enablePeriodically and enableOnWindowFocus are ignored.

A custom RefreshHandler requires init and destroy functions:

• init will be called when the nuxt application is mounted. Here you may add event listeners and initialize custom refresh behaviour.
• destroy will be called when your app is unmounted. Here you may run your clean up routine e.g. to remove your event listeners.

nuxt.config.ts

export default defineNuxtConfig({
  auth: {
    sessionRefresh: {
      // You can place it anywhere and name as you wish
      handler: './config/AuthRefreshHandler'
    }
  }
})

~/config/AuthRefreshHandler.ts

import type { RefreshHandler } from '@sidebase/nuxt-auth'

// You may also use a plain object with `satisfies RefreshHandler`
class CustomRefreshHandler implements RefreshHandler {
  init(): void {
    console.info('Use the full power of the refreshHandler!')
  }

  destroy(): void {
    console.info(
      'Hover above class properties or go to their definition '
      + 'to learn more about how to craft a refreshHandler'
    )
  }
}

export default new CustomRefreshHandler()

If no custom RefreshHandler is defined, the built-in-handler will be used to handle refreshes.

globalAppMiddleware

• Type: GlobalMiddlewareOptions | boolean
• Default: false

Whether to add a global authentication middleware that protects all pages. Can be either false to disable, true to enable with defaults or an object to enable with provided options.

• If you enable this, everything is going to be protected and you can selectively disable protection for some pages by specifying definePageMeta({ auth: false })
• If you disable this, everything is going to be public and you can selectively enable protection for some pages by specifying definePageMeta({ auth: true })

Read more about protecting pages.