sidebase/nuxt-auth for Nuxt authentication

Why @sidebase/nuxt-auth targets two different Nuxt deployment models

@sidebase/nuxt-auth addresses the authentication layer of a Nuxt 3+ application while leaving the project responsible for choosing an authentication strategy. It supports OAuth providers such as GitHub, Google, Twitter, and Azure, custom OAuth implementations, username-and-password credentials, and Email Magic Links. The same application-facing API also exposes sessions and sign-in and sign-out operations.

The important design choice is the division between two providers. Auth.js is intended for non-static applications and places Auth.js, also described in the README as NextAuth.js, behind a Nuxt-oriented interface. Local Provider is intended for static pages that use an external backend with a credential flow. It can also work with refresh tokens. These are materially different architectures. The module does not imply that every feature belongs equally to both paths, so an adopter still needs to check the provider compatibility documentation.

This is useful for teams that want common session and protection primitives without building every Nuxt integration layer from scratch. It is a poor fit for an application that expects the module alone to host a complete identity backend. In particular, the Local Provider documentation explicitly requires a separate backend for a static frontend.

How the useAuth session model connects sign-in, pages, and server checks

The application-side interface is centered on the `useAuth` composable. According to the README, it provides session state through `status`, `data`, and `lastRefreshedAt`. Its documented methods are `getSession`, `getCsrfToken`, `getProviders`, `signIn`, and `signOut`. The methods and properties are described as TypeScript supported, which matters in a TypeScript project because the module exposes typed access to session data rather than requiring an untyped wrapper.

Protection can be applied at several boundaries. The README lists global middleware for the full application and local middleware for specific pages. For Auth.js applications, it also lists server-side middleware and endpoint protection. Server utilities include `getServerSession` for session access and `getToken` for JWT access. The exact server utility available to a project will depend on the selected provider and its configuration.

Session refresh is another part of the lifecycle rather than an incidental detail. The module documents periodic refresh, refresh when a tab regains focus, and a one-time fetch on page load followed by refreshes for selected actions such as navigation. A custom `RefreshHandler` provides further configuration. This gives an application a way to balance freshness against request volume, although the README does not prescribe one refresh policy for every project.

Installing @sidebase/nuxt-auth in a Nuxt application

The shortest documented installation path uses Nuxt's module command:

npx nuxi@latest module add sidebase-auth

This invokes the documented module installation flow. The README then directs the developer to the Quick Start documentation at `https://auth.sidebase.io/guide/getting-started/introduction` for application-specific configuration. The README does not show the complete provider configuration in the quoted installation section, so a provider cannot be selected safely from that snippet alone.

For manual installation, the package can be added as a development dependency with `npm`, `pnpm`, or `yarn`:

npm i -D @sidebase/nuxt-auth

The equivalent documented `pnpm` command is:

pnpm i -D @sidebase/nuxt-auth

The documented Yarn command is:

yarn add --dev @sidebase/nuxt-auth

After manual installation, register the module in `nuxt.config.ts`:

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

This registration makes the module available to the Nuxt application. The next step still depends on whether the application uses Auth.js or Local Provider, and on the identity backend it uses.

A first Local Provider flow for a static Nuxt frontend

The repository includes a `playground-local` directory, and its documentation describes the static application arrangement. The frontend is generated and served separately from an authentication backend. The documented configuration change sets `baseURL: 'http://localhost:3001'` in the `auth` configuration of `playground-local/nuxt.config.ts`.

For a local static-app workflow, the documented frontend commands are:

cd playground-local
pnpm generate
pnpm start

The backend is started separately:

cd playground-local
pnpm dev

The README states that the second Nuxt app should then run on `http://localhost:3001` and is used for authentication in this playground arrangement. That arrangement demonstrates the Local Provider's external-backend assumption. It does not turn a generated frontend into a self-contained authentication service. A real deployment must provide the corresponding backend behavior and network settings.

The repository's development requirements add another practical constraint. `package.json` specifies Node.js `>=20` and `pnpm` `>=9.4.0` as engine requirements. Those values apply to the project package's development environment, so a contributor should check them before using the repository's scripts.

Auth.js versus Local Provider in @sidebase/nuxt-auth

Auth.js is the appropriate path to examine when the Nuxt application is non-static and the team wants to use Auth.js behavior with a Nuxt-native developer interface. The README specifically associates this provider with server-side capabilities, including server-side session access, JWT access, middleware, and endpoint protection. The package manifest also declares `next-auth` as an optional peer dependency at `~4.21.1`, which indicates that the Auth.js path has its own integration dependency.

Local Provider addresses a different problem. It is for static pages connected to an external backend and a credential flow. The README specifically states that Local Provider supports refresh tokens from version `v0.9.0`. That makes refresh-token behavior relevant to the provider, but it does not remove the need for a backend.

The practical comparison is therefore architectural. Auth.js offers a path for a non-static Nuxt application using Auth.js, while Local Provider keeps authentication work outside a generated frontend. Teams should not choose based only on whether the page is built with Nuxt. They should first identify where sessions are issued and validated, then choose the provider whose model matches that boundary.

Operational limits, maintenance signals, and MIT packaging

The clearest limitation is provider-dependent coverage. The README lists broad capabilities, but it does not claim that Auth.js and Local Provider implement every listed feature identically. It directs readers to a provider compatibility page for the full feature matrix. That distinction matters when a project needs server-side endpoint protection, refresh tokens, OAuth, or a particular session refresh strategy.

The README does not document rollback behavior, deployment-specific environment variables, or a complete production configuration in the quoted text. It also does not claim that the module handles identity storage, password security, or email delivery by itself. Credentials, OAuth secrets, token validation, and backend behavior must therefore be verified in the configuration and services used by the application.

The package uses the MIT license, and `package.json` identifies the published package as `@sidebase/nuxt-auth` version `1.4.0`. The repository is not archived. Its last push was on 2026-09-25, so the repository has a recent recorded development signal, but that does not by itself guarantee compatibility with every Nuxt or Auth.js upgrade. Upgrade cost includes reviewing provider-specific configuration, checking the optional `next-auth` peer dependency, and testing session refresh and protected routes. The repository uses `pnpm` for development and provides scripts such as `pnpm typecheck`, `pnpm lint`, `pnpm test:unit`, and `pnpm test:e2e` for project-level validation.

Editorial conclusion

Adopt @sidebase/nuxt-auth when a Nuxt 3+ application needs built-in authentication interfaces and page or endpoint protection. Do not choose it as a standalone identity service for a static Local Provider deployment, because that path requires an external backend. Before adoption, verify that the selected provider matches the deployment model, confirm the required Node.js and pnpm environment for development, and confirm that the authentication backend or Auth.js configuration supplies every credential and callback required by the application.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sidebase/nuxt-auth on GitHub