Installation

Install AuthCore v3.3.1 and set up your complete authentication system with enterprise security, multi-tenant architecture, and production-ready UI components.

Choose Your Installation Method

AuthCore v3.3.1 offers three installation methods depending on your project needs:

Main Template Mode

AuthCore becomes your primary source code with complete ownership.

bash

Full Template Mode

Copy all source code for maximum customization.

bash

Package Mode

Traditional npm package approach.

bash
Which mode should I choose?

Main Template Mode: Choose this when AuthCore IS your application. Perfect for auth-focused SaaS products.
Full Template Mode: Choose this when you want 100% control over all code. Ideal for extensive customization.
Package Mode: Choose this for traditional library usage. Import components from the npm package.

Step 3: Configure Environment Variables

Create a .env file in your project root:

.env
DATABASE_URLYour database connection string
NEXTAUTH_SECRETSecret key for JWT encryption (generate with: openssl rand -base64 32)
NEXTAUTH_URLYour application URL (use http://localhost:3000 for development)

Step 4: Initialize AuthCore

AuthCore offers two setup modes - choose the one that fits your needs:

Main Template Mode (Introduced in v3.3.x)

AuthCore becomes your main source code. Perfect for complete ownership and customization.

Terminal

What you get:

  • All components become @/components (direct imports)
  • All hooks become @/hooks (direct imports)
  • Server logic in @/lib/auth, @/lib/validation
  • All types in @/types (direct imports)
  • Database schema, API routes, environment templates
  • AuthCore styles and Tailwind preset included
  • Result: Import from @/components, @/hooks, etc.

Full Template Mode (Recommended)

Get 100% ownership of all source code. Perfect for custom designs and unique workflows.

Terminal

What you get:

  • All 84 components copied to src/components/authcore/
  • All hooks copied to src/hooks/authcore/
  • Server utilities copied to src/lib/auth/
  • Import paths automatically rewritten to local paths
  • Modify any file without package constraints
  • Package dependency becomes optional

Auth UI Refresh (New in v3.3.1)

Every installation now includes the glassmorphic AuthForm shell, an upgraded password strength indicator, and inline visibility toggles—no additional setup required.

  • Gradient glass panels with elevated social login trays that blend into marketing pages
  • Requirement chips and contextual recommendations ensure passwords feel professional and actionable
  • Password fields across the suite inherit the new visibility toggle from the shared TextInput

Standard Mode

Import components from the package. Best for quick setup and standard features.

Terminal

What you get:

  • API routes and server actions
  • Database schema
  • Components imported from package
  • Smaller project size
  • Easy updates via npm

What the CLI creates (both modes):

  • Prisma schema with auth tables
  • API routes (App or Pages Router)
  • Server actions and adapters (App Router)
  • Environment template with all variables
  • Verification and rollback scripts
  • Manifest for audit trail

See the Quick Start guide for CLI flag reference and advanced options.

Alternative: Manual Database Setup

If you prefer manual setup or already have Prisma configured:

Terminal

This will create the necessary tables for users, tenants, organizations, security settings, and more.

Step 5: Seed Demo Data (Optional)

Create a demo tenant and user for testing:

Terminal

Demo Credentials:

  • Email: owner@example.com
  • Password: password123
  • Tenant: Demo Tenant

Verify Installation

Run the automated verification tests to ensure your auth stack is working:

Terminal

The verify command tests these endpoints:

POST /api/auth/register - User registration
POST /api/auth/check-2fa - 2FA status check
GET /api/auth/policy - Auth policy configuration
POST /api/waitlist - Waitlist signup
GET /api/organizations - Organization listing

Manual checks:

  • Database connection: npx authcore status
  • Prisma Studio: npx prisma studio
  • Environment variables: npx authcore status

Troubleshooting

Database Connection Failed

Make sure your DATABASE_URL is correct and the database server is running.

  • For MySQL: Check username, password, host, and port
  • For PostgreSQL: Ensure the database exists
  • For SQLite: Make sure the file path is correct

Prisma Client Not Generated

Run npx prisma generate manually.

Migration Errors

Reset the database and try again: npx prisma migrate reset

🔌 Component Auto-Wiring

After installation, all AuthCore components automatically connect to your APIs, server actions, and auth policies. No manual wiring required!

What Gets Auto-Wired

84 Client Components

AuthForm, LoginForm, RegisterForm, TwoFactorSetup, WaitlistForm, CreateOrganization, etc.

All Hooks

useAuth, useLogin, useRegister, useMagicLink, useTwoFactor, useAuthPolicy

50 Server Exports

AuthService, TenantService, TwoFactorService, middleware, utilities

Auto Policy Fetching

Components fetch /api/auth/policy and adapt UI based on tenant rules

Your Login Page

How it works:

  • Components use NextAuth session context automatically
  • Forms call generated API routes (/api/auth/register, /api/auth/policy)
  • Server actions work with AuthService from codalware-auth/server
  • Email flows use your EMAIL_FROM and SMTP config
  • No prop drilling or manual configuration needed

See the Component Documentation for all props and customization options.

Next Steps

Continue to Quick Start →

Build your first authenticated app with AuthCore