@sidebase/nuxt-auth banner

@sidebase/nuxt-auth

Authentication built for Nuxt 3! Easily add authentication via OAuth providers, credentials or Email Magic URLs!

Quick Start

npx nuxi@latest module add sidebase-auth

Or install manually

1. Install the package as a dev dependency

npm i -D @sidebase/nuxt-auth

pnpm i -D @sidebase/nuxt-auth

yarn add --dev @sidebase/nuxt-auth

2. Add the modules to your `nuxt.config.ts`

export default defineNuxtConfig({
    modules: ['@sidebase/nuxt-auth']
})

Then visit the Quick Start documentation to continue the configuration of your app!

Features

@sidebase/nuxt-auth is a library with the goal of supporting authentication for any universal Nuxt 3 application. At the moment three providers are supported:

authjs: for non-static apps that want to use Auth.js / NextAuth.js to offer the reliability & convenience of a 23k star library to the Nuxt 3 ecosystem with a native developer experience (DX)
local: for static pages that rely on an external backend with a credential flow for authentication.
refresh: for static pages that rely on an external backend with a credential flow and refresh tokens for authentication.

You can find a full list of our features, as well as which provider supports each feature on our docs.

Authentication providers:

OAuth (e.g., Github, Google, Twitter, Azure, ...)
Custom OAuth (write it yourself)
Credentials (password + username)
Email Magic URLs

Application Side Session Managment using `useAuth`

Session fetching with status, data and lastRefreshedAt
Methods to getSession, getCsrfToken, getProviders, signIn and signOut
Full TypeScript support for all methods and properties

Application protection

Application-side middleware protection for the full application or specific pages
Server-side middleware and endpoint protection

Advanced features for session life-cycle management:

Pre-built and customizable refresh behaviour
- Refresh the session periodically
- Refresh the session on tab-refocus
- One time session fetch on page load, afterwards for specific actions (e.g., on navigation)
Completly configure the Refresh behaviour of your application using the RefreshHandler

Server Side utilities

Session access using getServerSession
JWT Token access using getToken
Server-side middleware and endpoint protection

Demo Page

Want to get a preview of what @sidebase/nuxt-auth has to offer? Visit the nuxt-auth demo page here. Peak into the demo source-code here.

Development

This project uses pnpm for development.

Run pnpm dev:prepare to generate type stubs.
Use pnpm dev inside a module playground directory to start a playground in development mode.
Run pnpm lint to run eslint
Run pnpm typecheck to run typescheck via tsc
Run pnpm publish --access public to publish
Run pnpm publish --access public --tag next to publish a pre-release

Module Playground

This module also has it's own playground:

> git clone https://github.com/sidebase/nuxt-auth

> cd nuxt-auth

> cd playground-[PROVIDER]

> pnpm i

> pnpm dev:prepare

> pnpm dev

Additional playground commands

Run pnpm dev:prepare to generate type stubs.
Run pnpm dev to start the playground.
Run pnpm test:e2e to run the end-to-end tests.
Run pnpm lint to run eslint
Run pnpm typecheck to run typescheck via tsc

Testing different Providers

We have one playground per provider:

How to test static Nuxt 3 apps?

To test static Nuxt 3 apps we want to run a static frontend and a separate backend that will take over authentication:

playground-local/nuxt.config.ts: Add baseURL: 'http://localhost:3001' to the auth-config

Start the static frontend:

cd playground-local

pnpm generate

pnpm start

Start the authentication backend (we use a second instance of the same nuxt3 app):

cd playground-local

pnpm dev

# A second Nuxt app should now be running on http://localhost:3001. 
# We use this purely for authentication

Visit http://localhost:3000 -> this should open the static application. Performing any auth-related actions, the app should send requests to the backend running on port 3001

Thank you to everyone who has contributed to this project by writing issues or opening pull requests. Your efforts help us improve and grow. If you are interested in contributing, please take a moment to review our Contributing Guidelines. We appreciate your support and look forward to your contributions!

Acknowledgments

@sidebase/nuxt-auth is supported by all of our amazing contributors and the Nuxt 3 team!