Module (nuxt.config.ts)

Use the auth-key inside the nuxt.config.ts to configure the nuxt-auth module itself. Here are the available configuration options and their default values:

export default defineNuxtConfig({  modules: ['@sidebase/nuxt-auth'],  auth: {    // The module is enabled. Change this to disable the module    isEnabled: true,    // The origin is set to the development origin. Change this when deploying to production by setting `origin` in this config before build-time or by exporting `AUTH_ORIGIN` by running `export AUTH_ORIGIN=...`    origin: 'http://localhost:3000',    // The base path to the authentication endpoints. Change this if you want to add your auth-endpoints at a non-default location    basePath: '/api/auth',    // Whether to periodically refresh the session. Change this to `true` for a refresh every seconds or set this to a number like `5000` for a refresh every 5000 milliseconds (aka: 5 seconds)    enableSessionRefreshPeriodically: false,    // Whether to refresh the session whenever a window focus event happens, i.e, when your user refocuses the window. Set this to `false` to turn this off    enableSessionRefreshOnWindowFocus: true,    // Whether to add a global authentication middleware that will protect all pages without exclusion    globalAppMiddleware: false,    // Select the default-provider to use when `signIn` is called. Setting this here will also effect the global middleware behavior: E.g., when you set it to `github` and the user is unauthorized, they will be directly forwarded to the Github OAuth page instead of seeing the app-login page    defaultProvider: undefined,    // Whether to automatically set the callback url to the page the user tried to visit when the middleware stopped them. This is useful to disable this when using the credentials provider, as it does not allow a `callbackUrl`. Setting this to a string-value will result in that being used as the callbackUrl path.    addDefaultCallbackUrl: true,    // Configuration of the global auth-middleware (only applies if you set `globalAppMiddleware: true` above!)    globalMiddlewareOptions: {        // Whether to allow access to 404 pages without authentication. Set this to `false` to force users to sign-in before seeing `404` pages. Setting this to false may lead to vue-router problems (as the target page does not exist)        allow404WithoutAuth: true,        // Whether to automatically set the callback url to the page the user tried to visit when the middleware stopped them. This is useful to disable this when using the credentials provider, as it does not allow a `callbackUrl`. Setting this to a string-value will result in that being used as the callbackUrl path. Note: You also need to set the global `addDefaultCallbackUrl` setting to `false` if you want to fully disable this for the global middleware.        addDefaultCallbackUrl: true    }  }})

The origin and the basePath together are equivalent to the NEXTAUTH_URL environment variable of NextAuth.js

origin

You must set the origin in production! You have two options to set it:

  1. Set the AUTH_ORIGIN environment variable at runtime
  2. Set the origin origin-config key inside the nuxt.config.ts (see an example above) at build-time

The AUTH_ORIGIN environment variable takes precendence over the origin configuration key, so you can always overwrite the origin at deploy-time.

The origin must be set so that nuxt-auth can ensure that callbacks for authentication are correct. The origin consists out of (up to) 3 parts:

  • scheme: http or https
  • host: e.g., localhost, example.org, www.sidebase.io
  • port: e.g., :3000, :4444; leave empty to implicitly set :80 for http, and :443 for https (this is an internet convention, don't ask)

For the demo-app at https://nuxt-auth-example.sidebase.io we set the origin to https://nuxt-auth-example.sidebase.io. If for some reason required, you can explicitly set the origin to http://localhost:3000 to stop nuxt-auth from aborting npm run build when the origin is unset.

basePath

This is what tells the module where you added the authentication endpoints. Per default the basePath is set to /api/auth, so that means that the module expects that all requests to /api/auth/* will be handled by the NuxtAuthHandler.

To statify this, you need to create a catch-all server-route at that location by creating a file ~/server/api/auth/[...].ts that exports the NuxtAuthHandler, see more on this in the Quick Start or in the NuxtAuthHandler documentation

If you want to have the authentication at another location, you can overwrite the basePath, e.g., when setting:

  • basePath: "/api/_auth" -> add the authentication catch-all endpoints into ~/server/api/_auth/[...].ts
  • basePath: "/_auth" -> add the authentication catch-all endpoints into ~/server/routes/_auth/[...].ts

See Nuxt server-routes docs on catch-all routes for a further explanation.

globalAppMiddleware

This is a middleware that comes included with nuxt-auth. When you enable it, it will protect all pages, so even your index page (/) will not be accessible without a login anymore.

Read more on this topic in the page protection docs.