Skip to main content

​
Installation

This guide covers everything you need to install and configure Arraf Auth in your project.

​
Prerequisites

Before installing Arraf Auth, ensure you have:
  • Node.js 18.0 or higher
  • TypeScript 5.0 or higher (recommended)
  • A supported database (PostgreSQL, MySQL, SQLite, etc.)
  • An SMS provider account (for phone OTP authentication)
While TypeScript is recommended for the best experience, Arraf Auth also works with JavaScript.

​
Core Package

The core package is framework-agnostic and provides all authentication logic: 
npm install @arraf-auth/core

​
Database Adapters

Choose a database adapter based on your ORM:

​
Prisma Adapter

npm install @arraf-auth/adapter-prisma @prisma/client
npm install -D prisma
The Prisma adapter requires Prisma Client and includes automatic schema generation.

​
Drizzle Adapter

npm install @arraf-auth/adapter-drizzle drizzle-orm
The Drizzle adapter works with any Drizzle-supported database driver.
Don’t see your ORM? You can easily create a custom adapter by implementing the DatabaseAdapter interface. See the Database Adapter API reference for details.

​
Framework Integrations

Install the integration package for your framework:

​
Next.js

npm install @arraf-auth/nextjs
Supports both App Router and Pages Router.

​
Express

npm install @arraf-auth/express
Works with Express 4.x and 5.x.

​
Hono

npm install @arraf-auth/hono
Compatible with Hono on Node.js, Cloudflare Workers, and other edge runtimes.

​
OAuth Providers

Install providers for OAuth authentication:

​
Google OAuth

npm install @arraf-auth/provider-google

​
GitHub OAuth

npm install @arraf-auth/provider-github
You can also create custom OAuth providers by implementing the OAuthProvider interface. See the OAuth Provider API reference for details.

​
Complete Installation Example

Here’s a typical installation for a Next.js project with Prisma: 
npm install @arraf-auth/core @arraf-auth/adapter-prisma @arraf-auth/nextjs
npm install @prisma/client
npm install -D prisma

# Optional: OAuth providers
npm install @arraf-auth/provider-google @arraf-auth/provider-github

​
Environment Variables

Create a .env file with the following required variables:
.env
# Required: Secret key for signing tokens and sessions
AUTH_SECRET="your-secret-key-here"

# Database connection (example for PostgreSQL)
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

# Optional: OAuth provider credentials
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Optional: SMS provider credentials
UNIFONIC_APP_SID="your-unifonic-app-sid"
UNIFONIC_SENDER_ID="your-sender-id"
Never commit your .env file to version control. Add it to .gitignore to keep your secrets safe.
Generate a secure random secret for AUTH_SECRET: 
openssl rand -base64 32

​
Database Setup

After installing your database adapter, you need to set up the database schema.

​
With Prisma

  1. Initialize Prisma (if not already done):
npx prisma init
  1. Add the Arraf Auth schema to prisma/schema.prisma
  2. Push to your database:
npx prisma db push
  1. Generate the Prisma Client:
npx prisma generate

​
With Drizzle

  1. Create your schema file with Arraf Auth tables
  2. Generate and run migrations:
npx drizzle-kit generate
npx drizzle-kit migrate

Database Setup Guide

See the complete database setup guide for detailed schema definitions and migration instructions.

​
Verify Installation

Create a test file to verify your installation:
test-auth.ts
import { createAuth } from "@arraf-auth/core"
import { prismaAdapter } from "@arraf-auth/adapter-prisma"
import { PrismaClient } from "@prisma/client"

const prisma = new PrismaClient()

const auth = createAuth({
  secret: "test-secret",
  database: prismaAdapter(prisma),
  sms: {
    send: async ({ to, message }) => {
      console.log(`Would send SMS to ${to}: ${message}`)
      return { success: true }
    }
  }
})

console.log("✓ Arraf Auth configured successfully!")
console.log("✓ Database adapter:", typeof auth.$context.adapter)
console.log("✓ Session manager:", typeof auth.$context.sessionManager)
Run it: 
npx tsx test-auth.ts
You should see success messages confirming the installation.

​
Package Overview

Here’s a quick reference of all available packages:
PackageDescriptionVersion
@arraf-auth/coreFramework-agnostic authentication enginenpm
@arraf-auth/adapter-prismaPrisma ORM database adapternpm
@arraf-auth/adapter-drizzleDrizzle ORM database adapternpm
@arraf-auth/nextjsNext.js App Router & Pages Router integrationnpm
@arraf-auth/expressExpress.js middleware integrationnpm
@arraf-auth/honoHono framework integrationnpm
@arraf-auth/provider-googleGoogle OAuth providernpm
@arraf-auth/provider-githubGitHub OAuth providernpm

​
Next Steps

Quickstart

Get a working auth system in 5 minutes

Database Setup

Configure your database schema and migrations

Phone + OTP

Set up phone authentication with SMS providers

Next.js Integration

Integration guide for Next.js App Router and Pages Router

​
Troubleshooting

​
TypeScript Errors

If you see TypeScript errors, ensure you have TypeScript 5.0 or higher: 
npm install -D typescript@latest

​
Prisma Generation Errors

If Prisma Client is not generating, run: 
npx prisma generate

​
Module Resolution Issues

For Next.js projects, ensure your tsconfig.json has the correct module resolution:
tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2020"
  }
}
Still having issues? Open an issue on GitHub for support.

Build docs developers (and LLMs) love

Get started for freeTalk to us