Registry / auth-security / next-auth-hasura-adapter

next-auth-hasura-adapter

JSON →
library2.0.0jsnpmunverified

The `next-auth-hasura-adapter` is a specialized adapter designed to integrate NextAuth.js authentication with a Hasura GraphQL engine backend. It is currently at version 2.0.0 and functions as a peer dependency of `next-auth` (specifically compatible with `next-auth` v4.x and above), meaning its release cycle is inherently tied to the evolution of the core NextAuth.js library. This package facilitates the storage and retrieval of authentication-related data, such as users, accounts, sessions, and verification tokens, directly within a PostgreSQL database managed by Hasura. It distinguishes itself by providing a `HasuraAdapter` instance that connects to a Hasura endpoint via GraphQL, eliminating the need for separate ORM configurations or database setups for NextAuth's internal data. Developers must apply a provided SQL schema to their Hasura-connected database to ensure the necessary tables and relationships are present for the adapter to function correctly. This makes it an ideal choice for projects already leveraging Hasura as their backend.

npm install next-auth-hasura-adapter
INSTALL
IMPORT
SIG · NEXT-AUTH-HASURA-A
N
next-auth-hasura-adapter
auth-securityjavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HasuraAdapter
import { HasuraAdapter } from 'next-auth-hasura-adapter';
const HasuraAdapter = require('next-auth-hasura-adapter');
This is the primary named export for the adapter function. The package is ESM-first, so CommonJS require() is generally discouraged in modern Next.js applications, which typically use ESM imports.
HasuraAdapterOptions
import type { HasuraAdapterOptions } from 'next-auth-hasura-adapter';
TypeScript type definition for the configuration options passed to the `HasuraAdapter`.
NextAuth
import NextAuth from 'next-auth';
import { NextAuth } from 'next-auth';
NextAuth is a default export from the primary `next-auth` package, required for configuring the authentication routes.

This quickstart demonstrates how to configure NextAuth.js with the Hasura Adapter in a Next.js API route, including setting up providers, adapter options using environment variables, and basic JWT session handling for user ID propagation.

// pages/api/auth/[...nextauth].ts import NextAuth from "next-auth"; import GitHubProvider from "next-auth/providers/github"; // Example provider import { HasuraAdapter } from "next-auth-hasura-adapter"; // Ensure your Hasura GraphQL endpoint and admin secret are set as environment variables. // Example: HASURA_GRAPHQL_ENDPOINT=https://your-hasura-instance/v1/graphql // Example: HASURA_GRAPHQL_ADMIN_SECRET=your_admin_secret_here const HASURA_API_ENDPOINT = process.env.HASURA_GRAPHQL_ENDPOINT ?? ''; const HASURA_ADMIN_SECRET = process.env.HASURA_GRAPHQL_ADMIN_SECRET ?? ''; if (!HASURA_API_ENDPOINT || !HASURA_ADMIN_SECRET) { throw new Error("Missing Hasura GraphQL Endpoint or Admin Secret environment variables. Please set HASURA_GRAPHQL_ENDPOINT and HASURA_GRAPHQL_ADMIN_SECRET."); } export default NextAuth({ // Configure one or more authentication providers (e.g., GitHub) providers: [ GitHubProvider({ clientId: process.env.GITHUB_ID ?? '', // Ensure GITHUB_ID is set in your .env clientSecret: process.env.GITHUB_SECRET ?? '', // Ensure GITHUB_SECRET is set in your .env }), // Add more providers as needed (e.g., GoogleProvider, EmailProvider) ], // Use the Hasura Adapter to persist user data adapter: HasuraAdapter({ endpoint: HASURA_API_ENDPOINT, admin_secret: HASURA_ADMIN_SECRET, }), // Recommended for adapters like Hasura for stateless sessions session: { strategy: "jwt" }, // Define callbacks to customize JWT and session objects callbacks: { async jwt({ token, user }) { if (user) { token.id = user.id; // Attach user ID to the JWT } // Custom Hasura claims can be added here if needed for authorization return token; }, async session({ session, token }) { // Expose user ID to the client via the session object if (session.user) { session.user.id = token.id; } return session; }, }, // NEXTAUTH_SECRET is required for any NextAuth.js application in production secret: process.env.NEXTAUTH_SECRET ?? '' });
Debug
Known issues
breakingThis adapter is built specifically for NextAuth.js v4.x and higher. It is not compatible with NextAuth.js v3.x or earlier versions, which had significant API changes.
fix
Ensure your `next-auth` dependency is `^4.0.0` or later. Upgrade `next-auth` to a compatible version if necessary.
affects: <2.0.0
gotchaThe adapter requires a specific SQL schema to be applied to your Hasura-connected PostgreSQL database. Failure to apply the `nextauth.sql` schema will result in runtime errors when the adapter attempts to interact with non-existent tables or columns.
fix
Execute the SQL script found in `src/data/nextauth.sql` (or provided in the README) against your database. Ensure all tables (`accounts`, `sessions`, `users`, `verification_tokens`) and their relationships are correctly set up.
affects: >=1.0.0
gotchaThe `admin_secret` for your Hasura instance should *never* be exposed client-side. Always pass it via secure server-side environment variables.
fix
Store `HASURA_GRAPHQL_ADMIN_SECRET` in your `.env.local` file or equivalent secure environment variable configuration for your deployment platform, and access it via `process.env.HASURA_GRAPHQL_ADMIN_SECRET` on the server.
affects: >=1.0.0
gotchaThe `endpoint` option must point to your Hasura GraphQL API endpoint (e.g., `https://my-hasura-app.com/v1/graphql`), not the Hasura Console URL or any other administrative endpoint.
fix
Verify that the `endpoint` URL configured for the `HasuraAdapter` is the exact GraphQL endpoint URL. For example, `process.env.HASURA_GRAPHQL_ENDPOINT`.
affects: >=1.0.0
gotchaA `secret` property is required in the `NextAuth` configuration object when deploying to production, even when using an adapter, for JWT signing and encryption.
fix
Add `secret: process.env.NEXTAUTH_SECRET` to your `NextAuth` configuration. Generate a strong, random string for `NEXTAUTH_SECRET` and store it securely in your environment variables.
affects: >=1.0.0
Errors
Common errors & fixes
Error: "The next-auth-hasura-adapter requires the 'endpoint' and 'admin_secret' options to be set."
The `endpoint` or `admin_secret` properties were not provided or were empty strings in the HasuraAdapter configuration.
fix
Ensure `endpoint` and `admin_secret` are correctly supplied to the `HasuraAdapter` function, typically through environment variables like `process.env.HASURA_GRAPHQL_ENDPOINT` and `process.env.HASURA_GRAPHQL_ADMIN_SECRET`.
GraphQL Error: "column \"userId\" of relation \"accounts\" does not exist" or similar 'table/column not found' errors.
The required NextAuth database schema has not been correctly applied to your Hasura-managed PostgreSQL database.
fix
Execute the SQL script `src/data/nextauth.sql` (or the one provided in the README) against your PostgreSQL database to create all necessary tables and relationships (e.g., `accounts`, `sessions`, `users`, `verification_tokens`).
NextAuth.js: No adapter has been specified
The `adapter` property is missing or incorrectly configured within your `NextAuth` configuration object.
fix
Add the `adapter: HasuraAdapter(...)` configuration to your `NextAuth` options in `pages/api/auth/[...nextauth].ts` or equivalent API route.
TypeError: HasuraAdapter is not a function
The `HasuraAdapter` was imported incorrectly, or the `next-auth-hasura-adapter` package might not be installed correctly.
fix
Ensure you are using `import { HasuraAdapter } from 'next-auth-hasura-adapter';` and that the package is properly installed via `npm install next-auth-hasura-adapter`.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
next-authrequiredThis package is an adapter for next-auth and requires it as its core dependency.
graphqlrequiredUsed for defining GraphQL schemas and operations.
graphql-tagrequiredHelper for parsing GraphQL query strings into an AST.
graphql-requestrequiredLightweight GraphQL client for sending requests to the Hasura API.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources