nuxt-sanctum

The nuxt-sanctum package brings Laravel Sanctum support to Nuxt.

Features

• 🚀  Universal rendering
• 🍪  Cookie-based authentication
• ⚙️  Sensible defaults, but configurable

Quick Setup

1. Add @hedger/nuxt-sanctum dependency to your project

# Using bun
bun add @hedger/nuxt-sanctum

# Using pnpm
pnpm add @hedger/nuxt-sanctum

# Using yarn
yarn add @hedger/nuxt-sanctum

# Using npm
npm install @hedger/nuxt-sanctum

2. Add @hedger/nuxt-sanctum to the modules section of nuxt.config.ts

export default defineNuxtConfig({
	modules: ["@hedger/nuxt-sanctum"],
});

Usage

The following examples should get your started. To customize the behavior, have a look at the options.

Signing In

To sign a user in, use the login method exposed by the useSanctum composable.

const { login } = useSanctum();

await login({
	email: "john.snow@example.com",
	password: "winteriscoming",
});

Redirecting after signing in

By default, the user will be redirected to the URL specified in the login.redirectsTo option. You may override this behavior by passing an alternative URL to the login method. Additionally, you may pass false to the login method to prevent redirection altogether.

// Override the default redirect
await login({
	email: "john.snow@example.com",
	password: "winteriscoming",
},"/somewhere-else");

// Prevent redirection
await login({
	email: "john.snow@example.com",
	password: "winteriscoming",
}, false);

Signing Out

To sign a user out, use the logout method exposed by the useSanctum composable.

const { logout } = useSanctum();

await logout();

Redirecting after signing out

By default, the user will be redirected to the URL specified in the logout.redirectsTo option. You may override this behavior by passing an alternative URL to the logout method. Additionally, you may pass false to the logout method to prevent redirection altogether.

// Override the default redirect
await logout("/somewhere-else");

// Prevent redirection
await logout(false);

Checking if a user is signed in

To check if a user is signed in, use the authenticated variable exposed by the useSanctum composable.

const { authenticated } = useSanctum();

if (authenticated.value) {
	// The user is signed in
}

Retrieving the user's details

To retrieve the details about the currently signed in user, use the user variable exposed by the useSanctum composable.

const { user } = useSanctum();

console.log(user.value?.name) // John Snow

Type safety

You may specify the type of the user object by passing it as a generic type argument to the useSanctum composable.

interface User {
	id: number;
	name: string;
	email: string;
}

const { user } = useSanctum<User>();

Making API requests

To make API requests, you may use the useSanctumFetch composable. This composable is a wrapper around the useFetch composable provided by the Nuxt that automatically handles the CSRF token and passes down the user's session cookie.

const { data } = useSanctumFetch("/api/user");

Restricting access to routes

This package provides the auth and guest middlewares to restrict access to routes.

Restricting to authenticated users

Use the auth middleware to ensure that only authenticated users can access a route. Unauthenticated users will be redirected to the URL specified in the middlewares.auth.redirectsTo option.

<script setup lang="ts">
	definePageMeta({
		middleware: "auth",
	});
</script>

Restricting to guest users

Use the guest middleware to ensure that only guest users can access a route. Authenticated users will be redirected to the URL specified in the middlewares.guest.redirectsTo option.

<script setup lang="ts">
	definePageMeta({
		middleware: "guest",
	});
</script>

Troubleshooting

Using HTTPS in development

When your Laravel API is served over HTTPS in a development environment, SSL errors may occur due to Node.js rejecting self-signed certificates. To fix this, set NODE_TLS_REJECT_UNAUTHORIZED to 0 when starting your development server.

{
	"scripts": {
		"dev": "NODE_TLS_REJECT_UNAUTHORIZED=0 nuxt dev"
	}
}

Note

Bun does not seem affected by this issue.

DNS resolution

If you run your Laravel API with php artisan serve, be aware that by default, it will only bind to the IPv4 interface. This may cause DNS resolution issues when using the useSanctumFetch composable, because it may try to resolve the localhost hostname to an IPv6 address.

There are a few ways to work around this:

• Bind to the IPv6 interface instead by running php artisan serve --host ::1
• Edit your /etc/hosts file to remove the IPv6 entry for localhost