or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication-providers.mdcore-authentication.mddatabase-integration.mdindex.mdjwt-management.mdmiddleware-protection.mdreact-integration.mdserver-side-sessions.md
tile.json

tessl/npm-next-auth

Authentication library for Next.js applications with support for OAuth, email, and credentials authentication

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/next-auth@4.24.x

To install, run

npx @tessl/cli install tessl/npm-next-auth@4.24.0

index.mddocs/

NextAuth.js

NextAuth.js is a comprehensive authentication library for Next.js applications that provides flexible OAuth integration, email/passwordless authentication, and credentials-based authentication. It supports both JSON Web Token and database session management, is designed for serverless environments, and emphasizes security by default with features like CSRF protection and encrypted JWTs.

Package Information

  • Package Name: next-auth
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install next-auth

Core Imports

import NextAuth from "next-auth";
import { getServerSession } from "next-auth/next";
import { useSession, signIn, signOut } from "next-auth/react";
import { getToken } from "next-auth/jwt";
import { withAuth } from "next-auth/middleware";

For CommonJS:

const NextAuth = require("next-auth").default;
const { getServerSession } = require("next-auth/next");
const { useSession, signIn, signOut } = require("next-auth/react");

Basic Usage

// Configure NextAuth.js (pages/api/auth/[...nextauth].ts)
import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";

export default NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async session({ session, token }) {
      session.user.id = token.sub;
      return session;
    },
  },
});

// Use in React components
import { useSession, signIn, signOut } from "next-auth/react";

export default function Component() {
  const { data: session } = useSession();

  if (session) {
    return (
      <>
        <p>Signed in as {session.user?.email}</p>
        <button onClick={() => signOut()}>Sign out</button>
      </>
    );
  }
  return (
    <>
      <p>Not signed in</p>
      <button onClick={() => signIn()}>Sign in</button>
    </>
  );
}

Architecture

NextAuth.js is built around several key components:

  • Core Authentication: Main NextAuth function for configuration and request handling
  • Session Management: Support for both JWT and database sessions with flexible lifecycle callbacks
  • Provider System: Extensive built-in support for 67+ OAuth providers plus email and credentials authentication
  • Client Library: React hooks and functions for client-side authentication state management
  • Server Integration: Server-side session retrieval and JWT utilities for API routes and SSR
  • Middleware: Route protection and authorization for Next.js middleware
  • Adapter Pattern: Database integration through adapters for any database backend
  • Security: Built-in CSRF protection, encrypted JWTs (JWE), automatic key generation, and secure cookies

Capabilities

Core Authentication Configuration

Main NextAuth configuration and request handling functionality. The central component for setting up authentication providers, callbacks, and session management.

function NextAuth(options: AuthOptions): any;
function NextAuth(req: NextApiRequest, res: NextApiResponse, options: AuthOptions): any;
function NextAuth(req: NextRequest, res: RouteHandlerContext, options: AuthOptions): any;

interface AuthOptions {
  providers: Provider[];
  secret?: string;
  session?: Partial<SessionOptions>;
  jwt?: Partial<JWTOptions>;
  pages?: Partial<PagesOptions>;
  callbacks?: Partial<CallbacksOptions>;
  events?: Partial<EventCallbacks>;
  adapter?: Adapter;
  debug?: boolean;
  logger?: Partial<LoggerInstance>;
  theme?: Theme;
  useSecureCookies?: boolean;
  cookies?: Partial<CookiesOptions>;
}

Core Authentication

Server-Side Session Management

Server-side utilities for retrieving and managing user sessions in API routes, server components, and getServerSideProps.

function getServerSession<O extends GetServerSessionOptions, R = any>(
  ...args: GetServerSessionParams<O>
): Promise<R | null>;

interface Session extends DefaultSession {
  user?: {
    name?: string | null;
    email?: string | null;
    image?: string | null;
  };
  expires: ISODateString;
}

Server-Side Sessions

React Client Integration

React hooks and components for managing authentication state and user interactions in client-side components.

function useSession<R extends boolean>(
  options?: UseSessionOptions<R>
): SessionContextValue<R>;

function SessionProvider(props: SessionProviderProps): JSX.Element;

function signIn<P extends RedirectableProviderType | undefined = undefined>(
  provider?: LiteralUnion<P extends RedirectableProviderType ? P | BuiltInProviderType : BuiltInProviderType>,
  options?: SignInOptions,
  authorizationParams?: SignInAuthorizationParams
): Promise<P extends RedirectableProviderType ? SignInResponse | undefined : undefined>;

function signOut<R extends boolean = true>(
  options?: SignOutParams<R>
): Promise<R extends true ? undefined : SignOutResponse>;

React Integration

JWT Token Management

JWT utilities for encoding, decoding, and extracting tokens from requests. Essential for API authentication and custom session handling.

function encode(params: JWTEncodeParams): Promise<string>;
function decode(params: JWTDecodeParams): Promise<JWT | null>;
function getToken<R extends boolean = false>(
  params: GetTokenParams<R>
): Promise<R extends true ? string : JWT | null>;

interface JWT extends Record<string, unknown>, DefaultJWT {
  name?: string | null;
  email?: string | null;
  picture?: string | null;
  sub?: string;
}

JWT Management

Middleware and Route Protection

Middleware functions for protecting routes and implementing authorization logic in Next.js applications.

function withAuth(): ReturnType<NextMiddlewareWithAuth>;
function withAuth(middleware: NextMiddlewareWithAuth): NextMiddlewareWithAuth;
function withAuth(options: NextAuthMiddlewareOptions): NextMiddlewareWithAuth;

interface NextAuthMiddlewareOptions {
  pages?: AuthOptions["pages"];
  cookies?: Partial<Record<keyof Pick<keyof AuthOptions["cookies"], "sessionToken">, Omit<CookieOption, "options">>>;
  jwt?: Partial<Pick<JWTOptions, "decode">>;
  callbacks?: {
    authorized?: (params: { token: JWT | null; req: NextRequest }) => Awaitable<boolean>;
  };
  secret?: string;
}

Middleware Protection

Authentication Providers

Built-in support for 67+ authentication providers including OAuth, email, and credentials-based authentication.

interface Provider extends CommonProviderOptions {
  id: string;
  name: string;
  type: ProviderType;
  options?: any;
}

type ProviderType = "oauth" | "email" | "credentials";

// OAuth Provider Configuration
interface OAuthConfig<P> {
  id: string;
  name: string;
  type: "oauth";
  authorization: string | AuthorizationEndpointHandler;
  token: string | TokenEndpointHandler;
  userinfo?: string | UserinfoEndpointHandler;
  client: Partial<ClientMetadata>;
  clientId: string;
  clientSecret: string;
}

Authentication Providers

Database Integration

Adapter interface for integrating with any database backend, supporting user management, session storage, and account linking.

interface Adapter {
  createUser?: (user: Omit<AdapterUser, "id">) => Awaitable<AdapterUser>;
  getUser?: (id: string) => Awaitable<AdapterUser | null>;
  getUserByEmail?: (email: string) => Awaitable<AdapterUser | null>;
  getUserByAccount?: (providerAccountId: Pick<AdapterAccount, "provider" | "providerAccountId">) => Awaitable<AdapterUser | null>;
  updateUser?: (user: Partial<AdapterUser> & Pick<AdapterUser, "id">) => Awaitable<AdapterUser>;
  linkAccount?: (account: AdapterAccount) => Promise<void> | Awaitable<AdapterAccount | null | undefined>;
  createSession?: (session: { sessionToken: string; userId: string; expires: Date }) => Awaitable<AdapterSession>;
  getSessionAndUser?: (sessionToken: string) => Awaitable<{ session: AdapterSession; user: AdapterUser } | null>;
  updateSession?: (session: Partial<AdapterSession> & Pick<AdapterSession, "sessionToken">) => Awaitable<AdapterSession | null | undefined>;
  deleteSession?: (sessionToken: string) => Promise<void> | Awaitable<AdapterSession | null | undefined>;
}

Database Integration

Types

Core Types

type Awaitable<T> = T | PromiseLike<T>;

interface User extends DefaultUser {
  id: string;
  name?: string | null;
  email?: string | null;
  image?: string | null;
}

interface Account extends Partial<TokenSetParameters> {
  providerAccountId: string;
  userId?: string;
  provider: string;
  type: ProviderType;
}

interface Profile extends Record<string, any> {
  sub?: string;
  name?: string;
  email?: string;
  image?: string;
}

type ISODateString = string;

Configuration Types

interface SessionOptions {
  strategy: "jwt" | "database";
  maxAge: number;
  updateAge: number;
  generateSessionToken?: () => Awaitable<string>;
}

interface JWTOptions {
  secret: string;
  maxAge: number;
  encode?: (params: JWTEncodeParams) => Awaitable<string>;
  decode?: (params: JWTDecodeParams) => Awaitable<JWT | null>;
}

interface PagesOptions {
  signIn?: string;
  signOut?: string;
  error?: string;
  verifyRequest?: string;
  newUser?: string;
}

Callback Types

interface CallbacksOptions<P = Profile, A = Account> {
  signIn?: (params: {
    user: User | AdapterUser;
    account: A | null;
    profile?: P;
    email?: { verificationRequest?: boolean };
    credentials?: Record<string, CredentialInput>;
  }) => Awaitable<string | boolean>;
  
  redirect?: (params: {
    url: string;
    baseUrl: string;
  }) => Awaitable<string>;
  
  session?: (params: {
    session: Session;
    token: JWT;
    user: AdapterUser;
    newSession?: any;
    trigger?: "update";
  }) => Awaitable<Session | DefaultSession>;
  
  jwt?: (params: {
    token: JWT;
    user: User | AdapterUser;
    account: A | null;
    profile?: P;
    trigger?: "signIn" | "signUp" | "update";
    isNewUser?: boolean;
    session?: any;
  }) => Awaitable<JWT>;
}

Event Callbacks

interface EventCallbacks {
  /** Called when a user successfully signs in */
  signIn: (message: {
    user: User;
    account: Account | null;
    profile?: Profile;
    isNewUser?: boolean;
  }) => Awaitable<void>;
  
  /** Called when a user signs out */
  signOut: (message: { 
    session: Session; 
    token: JWT; 
  }) => Awaitable<void>;
  
  /** Called when a new user is created */
  createUser: (message: { user: User }) => Awaitable<void>;
  
  /** Called when a user is updated */
  updateUser: (message: { user: User }) => Awaitable<void>;
  
  /** Called when an account is linked to a user */
  linkAccount: (message: {
    user: User | AdapterUser;
    account: Account;
    profile: User | AdapterUser;
  }) => Awaitable<void>;
  
  /** Called when a session is accessed */
  session: (message: { 
    session: Session; 
    token: JWT; 
  }) => Awaitable<void>;
}

type EventType = keyof EventCallbacks;

Theme Configuration

interface Theme {
  /** Color scheme for built-in pages */
  colorScheme?: "auto" | "dark" | "light";
  /** Logo URL for built-in pages */
  logo?: string;
  /** Brand color for built-in pages */
  brandColor?: string;
  /** Button text color for built-in pages */
  buttonText?: string;
}

Session Interfaces

interface DefaultSession {
  user?: {
    name?: string | null;
    email?: string | null;
    image?: string | null;
  };
  expires: ISODateString;
}

interface Session extends DefaultSession {}

type SessionStrategy = "jwt" | "database";