Nuxt Cookies Auth
➡️ useFetch with automatic token refresh (stored in httpOnly
cookies) ⬅️
Nuxt 3 module for passing cookies with each useFetch
request (with the client calls and the SSR calls as well).
httpOnly Cookies are the best option for storing access token (this way it is protected against XSS). Module automatically tries to refresh tokens with a POST
call to a specified url on a 401 Unauthorized exception response.
Features
- 🌲 Handles access and refresh tokens, both can be
httpOnly
- 🚠 Automatically tries to refresh tokens on 401 response
- ⛰ Works on client and server api
Quick Setup
- Add
nuxt-cookies-auth
dependency to your project
# Using pnpm
pnpm add -D nuxt-cookies-auth
# Using yarn
yarn add --dev nuxt-cookies-auth
# Using npm
npm install --save-dev nuxt-cookies-auth
- Add
nuxt-cookies-auth
to themodules
section ofnuxt.config.ts
export default defineNuxtConfig({
modules: ["nuxt-cookies-auth"]
...
})
- Add configuration to the
nuxt.config.ts
export default defineNuxtConfig({
...
cookiesAuth: {
apiBaseUrl: "",
refreshTokenUrl: "/api/refresh",
redirectOnRefreshTokenExpiration: true,
redirectTo: "/login"
}
...
})
Configuration
-
refreshTokenUrl: url expecting
POST
request for refreshing tokens (default:"/api/refresh"
) -
apiBaseUrl: default API url. For calling Nuxt 3 server api routes leave it blank, otherwise put an absolute server url, eg:
http://test.com/api
(default: blank).
It sets thebaseURL
to theuseFetch
as well when theuseCookiesAuth
is called. -
redirectOnRefreshTokenExpiration: redirect or not to the
redirectTo
path when the api returns 401 response for the refresh token request (default: true) - redirectTo: path where the app will be redirected when the api returns 401 response for refresh token request (default: /login)
# More detailed example of configuration
That's it! You can now use useCookiesAuth
in your Nuxt app ✨
Usage
// use spread operator for useCookiesAuth composable and useFetch options:
const { data, error } = await useFetch("/api/data", {
...useCookiesAuth()
})
// with body or other parameters:
const { data, error } = await useFetch("/api/data", {
...useCookiesAuth(),
method: "POST",
query: {
id: 7
},
body: {
message: "Hello!"
}
})
Usage with middleware
useCookiesAuth
internally needs to know from what route the request has been made for redirecting in case of 401 response for refresh token request. But using useRoute
in nuxt frontend middleware is causing:
[nuxt] Calling `useRoute` within middleware may lead to misleading results. Instead, use the (to, from) arguments passed to the middleware to access the new and old routes.
For such case there us an useCookiesAuth
overload where you can pass a path from the middleware from
parameter to bypass this.
export default defineNuxtRouteMiddleware(async (to, from) => {
...
const { data } = useFetch<User>("/api/data", {
...useCookiesAuth(from.path)
})
...
return
})
Example
Configuration
When you have api url http://test.com/api/v1/auth/refresh
for refreshing token and http://test.com/api/v1/users
for getting list of users, set:
apiBaseUrl: "http://test.com/api/v1"
refreshTokeUrl: "/auth/refresh"
- and call
useFetch("/users", { ...useCookiesAuth() })
.
Backend
For an authorization with tokens in cookies there are only two routes needed:
- login
- refresh
Login sets two cookies. First with the access token with shorter expiration and second refresh token with a longer expiration.
You can check the Nuxt 3 server api login route.
Second route for refreshing token just checks the refresh token and when it is correct it sends back a new pair of access and refresh token. This is the route that must be set to the refreshTokenUrl
configuration field in nuxt.config.ts
.
Development
# Install dependencies
npm install
# Generate type stubs
npm run dev:prepare
# Develop with the playground
npm run dev
# Build the playground
npm run dev:build
# Run ESLint
npm run lint
# Run Vitest
npm run test
npm run test:watch
# Release new version
npm run release
Warranty
There is no warranty. Usage is at your own risk.