heavstal-auth

Latest Release • MIT License RECOMMENDED

Heavstal Auth

heavstal-auth is the official authentication provider for the Heavstal Identity ecosystem, built specifically for NextAuth.js (Auth.js).

It abstracts away the complexity of OIDC discovery, token exchanges, and profile mapping, allowing developers to integrate "Sign in with Heavstal" in just 3 lines of code.

Why use this?

Method	Lines of Code	Complexity	Maintenance
Manual Configuration	50+	High (Manual URL handling)	Hard (Must update URLs manually)
heavstal-auth	3	Zero	Auto-Managed

Installation

bash

npm install heavstal-auth

> Note: Requires next-auth installed in your project.

Usage

Simply import the provider and add it to your NextAuth configuration. It works exactly like the built-in Google or GitHub providers.

In `app/api/auth/[...nextauth]/route.ts`:

typescript

import NextAuth from "next-auth"
import HeavstalProvider from "heavstal-auth"

const handler = NextAuth({
  providers: [
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
    }),
    // ...other providers
  ],
})

export { handler as GET, handler as POST }

TypeScript Support

The package is written in TypeScript and exports the user profile types automatically.

typescript

// The profile returned by Heavstal contains:
interface HeavstalProfile {
  id: string       // Heavstal User ID
  name: string     // Display Name
  email: string    // Verified Email
  image: string    // Profile Picture URL
}

Configuration

You can get your clientId and clientSecret from the [Heavstal Developer Console](https://heavstal-tech.vercel.app/oauth/apps).

Add them to your .env file: