ag-common-next-auth

0.0.153 verified Sat Apr 25 auth: no javascript

A set of reusable utilities for NextAuth.js, including OAuth callback handlers, session management, and Cognito integration. Current stable version 0.0.153. Released frequently (multiple versions per week) but still in early development. Key differentiators: provides pre-built NextAuth adapters and helpers for common providers, with TypeScript types included. Minimal documentation and limited community adoption; use with caution in production.

Common errors

error Error: OAuthCallback is not defined ↓

cause Importing default export instead of named export.

fix

Use import { OAuthCallback } from 'ag-common-next-auth'

error TypeError: Cannot read properties of undefined (reading 'clientId') ↓

cause Environment variables COGNITO_CLIENT_ID or COGNITO_CLIENT_SECRET missing.

fix

Add them to your .env file or hosting environment.

Warnings

gotcha Environment variables COGNITO_CLIENT_SECRET and NEXTAUTH_SECRET must be set, otherwise OAuthCallback will throw an error. ↓

fix Ensure both variables are defined in your deployment environment (Vercel, etc.).

breaking Version 0.0.150 renamed `OAuthHandler` to `OAuthCallback`. Old imports break. ↓

fix Update imports: replace `OAuthHandler` with `OAuthCallback`.

deprecated Function `validateSession` was deprecated in v0.0.130; use `checkEnvironment` instead. ↓

fix Replace `validateSession()` with `checkEnvironment()`.

gotcha CognitoProvider is not exported from the main package entry; it requires a subpath import. ↓

fix Import from 'ag-common-next-auth/providers/cognito'.

breaking In v0.0.120, the package switched from CommonJS to ESM-only. `require()` still works but may cause issues with dynamic imports. ↓

fix Use ES import syntax; if using Node.js <14, upgrade or use dynamic import().

Install

npm install ag-common-next-auth

yarn add ag-common-next-auth

pnpm add ag-common-next-auth

Imports

OAuthCallback

wrong

import OAuthCallback from 'ag-common-next-auth'

correct

import { OAuthCallback } from 'ag-common-next-auth'

Named export only; no default export.

checkEnvironment

wrong

const checkEnvironment = require('ag-common-next-auth').checkEnvironment

correct

import { checkEnvironment } from 'ag-common-next-auth'

ESM-only; CommonJS require works but is discouraged.

CognitoProvider

wrong

import { CognitoProvider } from 'ag-common-next-auth'

correct

import { CognitoProvider } from 'ag-common-next-auth/providers/cognito'

Subpath export; not available from main entry.

Quickstart

Shows how to use OAuthCallback handler with Cognito provider, including environment variable fallbacks.

import { OAuthCallback } from 'ag-common-next-auth';

export async function handler(req, res) {
  const result = await OAuthCallback(req, res, {
    clientId: process.env.COGNITO_CLIENT_ID ?? '',
    clientSecret: process.env.COGNITO_CLIENT_SECRET ?? '',
    redirectUri: 'https://example.com/api/auth/callback',
  });
  console.log('OAuth result:', result);
}