Usage

Configuration

How to configure nuxt-auth-sanctum for Nuxt

Initial setup

The only required configuration option is baseUrl which will be used for API calls to your Laravel API, so you can start using the module with the following definition:

nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-auth-sanctum'],

    sanctum: {
        baseUrl: 'http://localhost:80', // Laravel API
    },
})

Available options

For any additional configurations, you can adjust the next list of available parameters:

Parameter	Description	Default
`baseUrl`	The base URL of the Laravel API	`undefined`
`mode`	Authentication mode to work with Laravel API. Supported values - `cookie`, `token`.	`cookie`
`origin`	The URL of the current application to use in Referrer header	`useRequestUrl().origin`
`userStateKey`	The key to use to store the user identity in the `useState` variable.	`sanctum.user.identity`
`redirectIfAuthenticated`	Determine whether to redirect the user if it is already authenticated on a login attempt.	`false`
`redirectIfUnauthenticated`	Determine whether to redirect when the user got unauthenticated on any API request.	`false`
`endpoints.csrf`	The endpoint to request a new CSRF token	`/sanctum/csrf-cookie`
`endpoints.login`	The endpoint to send user credentials to authenticate	`/login`
`endpoints.logout`	The endpoint to destroy current user session	`/logout`
`endpoints.user`	The endpoint to fetch current user data	`/api/user`
`csrf.cookie`	Name of the CSRF cookie to extract from server response	`XSRF-TOKEN`
`csrf.header`	Name of the CSRF header to pass from client to server	`X-XSRF-TOKEN`
`client.retry`	The number of times to retry a request when it fails	`false`
`client.initialRequest`	Determines whether to request the user identity on plugin initialization	`true`
`redirect.keepRequestedRoute`	Determines whether to keep the requested route when redirecting after login	`false`
`redirect.onLogin`	Route to redirect to when user is authenticated. If set to false, do nothing	`/`
`redirect.onLogout`	Route to redirect to when user is not authenticated. If set to false, do nothing	`/`
`redirect.onAuthOnly`	Route to redirect to when user has to be authenticated. If set to false, do nothing	`/login`
`redirect.onGuestOnly`	Route to redirect to when user has to be a guest. If set to false, do nothing	`/`
`globalMiddleware.enabled`	Determines whether the global middleware is enabled	`false`
`globalMiddleware.prepend`	Determines whether the global middleware is prepended to the list of middlewares	`false`
`globalMiddleware.allow404WithoutAuth`	Determines whether to allow 404 page without authentication	`true`
`logLevel`	The level to use for the logger. More details here.	`3`
`appendPlugin`	Determines whether to append the plugin to the Nuxt application. More details here.	`false`
`serverProxy.enabled`	Determines whether the server side proxy is enabled. Available on server-side only.	`false`
`serverProxy.route`	Nuxt server route to catch all requests. This route will receive any nested path as well. Available on server-side only.	`/api/sanctum`
`serverProxy.baseUrl`	The base URL of the Laravel API. Available on server-side only.	`http://localhost:80`

For more details, please check the source code - options.ts.

Overrides

You can override any of these options in the nuxt.config.ts file:

nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-auth-sanctum'],

    sanctum: {
        baseUrl: 'http://localhost:80', // Your Laravel API
        redirect: {
            onLogin: '/dashboard', // Custom route after successful login
        },
    },
})

RuntimeConfig

Module configuration is exposed to runtimeConfig property of your Nuxt app, so you can override either in sanctum module config or runtimeConfig.public.sanctum property.

nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-auth-sanctum'],

    runtimeConfig: {
        public: {
            sanctum: {
                baseUrl: 'http://localhost:80',
            },
        },
    },
})

Server vs Client Configuration

The module supports different configurations for server-side (SSR) and client-side (CSR) contexts.

Configuration Priority

Context	Priority (highest to lowest)
Server	`runtimeConfig.sanctum` → `runtimeConfig.public.sanctum` → module defaults
Client	`runtimeConfig.public.sanctum` → module defaults

Examples

Shared config (same for both server and client):

nuxt.config.ts

runtimeConfig: {
    public: {
        sanctum: {
            baseUrl: 'http://localhost:80',
        },
    },
}

Different config (server vs client):

nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-auth-sanctum'],

    // Default values for both server and client
    sanctum: {
        baseUrl: 'http://localhost:80',
        logLevel: 3,
    },

    // Server-specific overrides
    runtimeConfig: {
        sanctum: {
            baseUrl: 'http://laravel:80',  // Docker internal URL
            logLevel: 4,                   // Verbose server logs
        },

        // Client-specific overrides
        public: {
            sanctum: {
                baseUrl: 'https://myapp.com',  // Public TLD
                logLevel: 2,                   // Minimal client logs
            }
        }
    },
})

Server-Only Options

The following options are only available on the server-side:

serverProxy.enabled
serverProxy.route
serverProxy.baseUrl

Environment variables

It is possible to override options via environment variables too. It might be useful when you want to use .env file to provide baseUrl for Laravel API.

If you are using SSR (Server-Side Rendering) and relying entirely on .env files rather than hardcoding the baseUrl in your nuxt.config.ts, you must provide both the public and private environment variables. Otherwise, the server-side fetch will not see the public variable and the page will hang indefinitely with an infinite loop of SSR requests.

Here is what it should look like in your .env file:

.env

# Used by the browser (CSR)
NUXT_PUBLIC_SANCTUM_BASE_URL='http://localhost:8000'

# Used by the Nuxt server (SSR)
NUXT_SANCTUM_BASE_URL='http://localhost:8000'

The origin option requires a static default in nuxt.config.ts for environment variables to work. Unlike other options, Nuxt ignores env var overrides for keys that are undefined by default.

sanctum: {
    origin: 'http://localhost:3000', // Set static default first
}

Then in your .env:

# For client-side (CSR)
NUXT_PUBLIC_SANCTUM_ORIGIN=https://your-domain.com

# For server-side (SSR)
NUXT_SANCTUM_ORIGIN=https://your-domain.com

Note: NUXT_PUBLIC_SANCTUM_ORIGIN only affects client-side, while NUXT_SANCTUM_ORIGIN only affects server-side.

Configuration example

Here is an example of a full module configuration

nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-auth-sanctum'],

    sanctum: {
        mode: 'cookie',
        userStateKey: 'sanctum.user.identity',
        redirectIfAuthenticated: false,
        redirectIfUnauthenticated: false,
        endpoints: {
            csrf: '/sanctum/csrf-cookie',
            login: '/login',
            logout: '/logout',
            user: '/api/user',
        },
        csrf: {
            cookie: 'XSRF-TOKEN',
            header: 'X-XSRF-TOKEN',
        },
        client: {
            retry: false,
            initialRequest: true,
        },
        redirect: {
            keepRequestedRoute: false,
            onLogin: '/',
            onLogout: '/',
            onAuthOnly: '/login',
            onGuestOnly: '/',
        },
        globalMiddleware: {
            enabled: false,
            allow404WithoutAuth: true,
        },
        logLevel: 3,
        appendPlugin: false,
    }
})

Installation

How to add nuxt-auth-sanctum to your Nuxt application!

Cookie Authentication

Set up cookie CSRF authentication for Sanctum