{"id":16735,"library":"next-auth-hasura-adapter","title":"NextAuth.js Hasura Adapter","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/AmruthPillai/next-auth-hasura-adapter","tags":["javascript","next.js","next-auth","hasura","typescript"],"install":[{"cmd":"npm install next-auth-hasura-adapter","lang":"bash","label":"npm"},{"cmd":"yarn add next-auth-hasura-adapter","lang":"bash","label":"yarn"},{"cmd":"pnpm add next-auth-hasura-adapter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an adapter for next-auth and requires it as its core dependency.","package":"next-auth","optional":false},{"reason":"Used for defining GraphQL schemas and operations.","package":"graphql","optional":false},{"reason":"Helper for parsing GraphQL query strings into an AST.","package":"graphql-tag","optional":false},{"reason":"Lightweight GraphQL client for sending requests to the Hasura API.","package":"graphql-request","optional":false}],"imports":[{"note":"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.","wrong":"const HasuraAdapter = require('next-auth-hasura-adapter');","symbol":"HasuraAdapter","correct":"import { HasuraAdapter } from 'next-auth-hasura-adapter';"},{"note":"TypeScript type definition for the configuration options passed to the `HasuraAdapter`.","symbol":"HasuraAdapterOptions","correct":"import type { HasuraAdapterOptions } from 'next-auth-hasura-adapter';"},{"note":"NextAuth is a default export from the primary `next-auth` package, required for configuring the authentication routes.","wrong":"import { NextAuth } from 'next-auth';","symbol":"NextAuth","correct":"import NextAuth from 'next-auth';"}],"quickstart":{"code":"// pages/api/auth/[...nextauth].ts\nimport NextAuth from \"next-auth\";\nimport GitHubProvider from \"next-auth/providers/github\"; // Example provider\nimport { HasuraAdapter } from \"next-auth-hasura-adapter\";\n\n// Ensure your Hasura GraphQL endpoint and admin secret are set as environment variables.\n// Example: HASURA_GRAPHQL_ENDPOINT=https://your-hasura-instance/v1/graphql\n// Example: HASURA_GRAPHQL_ADMIN_SECRET=your_admin_secret_here\nconst HASURA_API_ENDPOINT = process.env.HASURA_GRAPHQL_ENDPOINT ?? '';\nconst HASURA_ADMIN_SECRET = process.env.HASURA_GRAPHQL_ADMIN_SECRET ?? '';\n\nif (!HASURA_API_ENDPOINT || !HASURA_ADMIN_SECRET) {\n  throw new Error(\"Missing Hasura GraphQL Endpoint or Admin Secret environment variables. Please set HASURA_GRAPHQL_ENDPOINT and HASURA_GRAPHQL_ADMIN_SECRET.\");\n}\n\nexport default NextAuth({\n  // Configure one or more authentication providers (e.g., GitHub)\n  providers: [\n    GitHubProvider({\n      clientId: process.env.GITHUB_ID ?? '', // Ensure GITHUB_ID is set in your .env\n      clientSecret: process.env.GITHUB_SECRET ?? '', // Ensure GITHUB_SECRET is set in your .env\n    }),\n    // Add more providers as needed (e.g., GoogleProvider, EmailProvider)\n  ],\n  // Use the Hasura Adapter to persist user data\n  adapter: HasuraAdapter({\n    endpoint: HASURA_API_ENDPOINT,\n    admin_secret: HASURA_ADMIN_SECRET,\n  }),\n  // Recommended for adapters like Hasura for stateless sessions\n  session: {\n    strategy: \"jwt\"\n  },\n  // Define callbacks to customize JWT and session objects\n  callbacks: {\n    async jwt({ token, user }) {\n      if (user) {\n        token.id = user.id; // Attach user ID to the JWT\n      }\n      // Custom Hasura claims can be added here if needed for authorization\n      return token;\n    },\n    async session({ session, token }) {\n      // Expose user ID to the client via the session object\n      if (session.user) {\n        session.user.id = token.id;\n      }\n      return session;\n    },\n  },\n  // NEXTAUTH_SECRET is required for any NextAuth.js application in production\n  secret: process.env.NEXTAUTH_SECRET ?? ''\n});\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your `next-auth` dependency is `^4.0.0` or later. Upgrade `next-auth` to a compatible version if necessary.","message":"This 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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `admin_secret` for your Hasura instance should *never* be exposed client-side. Always pass it via secure server-side environment variables.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that the `endpoint` URL configured for the `HasuraAdapter` is the exact GraphQL endpoint URL. For example, `process.env.HASURA_GRAPHQL_ENDPOINT`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"A `secret` property is required in the `NextAuth` configuration object when deploying to production, even when using an adapter, for JWT signing and encryption.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"The `endpoint` or `admin_secret` properties were not provided or were empty strings in the HasuraAdapter configuration.","error":"Error: \"The next-auth-hasura-adapter requires the 'endpoint' and 'admin_secret' options to be set.\""},{"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`).","cause":"The required NextAuth database schema has not been correctly applied to your Hasura-managed PostgreSQL database.","error":"GraphQL Error: \"column \\\"userId\\\" of relation \\\"accounts\\\" does not exist\" or similar 'table/column not found' errors."},{"fix":"Add the `adapter: HasuraAdapter(...)` configuration to your `NextAuth` options in `pages/api/auth/[...nextauth].ts` or equivalent API route.","cause":"The `adapter` property is missing or incorrectly configured within your `NextAuth` configuration object.","error":"NextAuth.js: No adapter has been specified"},{"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`.","cause":"The `HasuraAdapter` was imported incorrectly, or the `next-auth-hasura-adapter` package might not be installed correctly.","error":"TypeError: HasuraAdapter is not a function"}],"ecosystem":"npm"}