Authentication Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Authentication Integrations provide a typed, unified model for implementing security and identity management within Farm.js applications. These integrations wrap external Service Provider SDKs or implement local authentication logic to manage sessions, protect routes, and handle user identities across server and client boundaries.
The framework supports two primary modes of authentication: built-in local authentication and provider-specific integrations. Built-in authentication uses auth: true in the project configuration, whereas external providers like Auth0, Clerk, or Better Auth are mounted through the integrations registry. Both modes utilize Farm's file-based routing and middleware system to enforce security policies.
Sources: README.md:20-30, skills/farmjs/SKILL.md:180-190, AGENTS.md:50-60
Core Authentication Architectures
Farm.js differentiates between framework-managed authentication and provider-managed authentication.
Built-in Authentication (auth: true)
Built-in authentication provides a zero-config setup for local email and password management. It utilizes local SQLite storage during development and transitions to Postgres for production environments. This mode automatically handles account creation, sign-in, and session persistence without requiring manual implementation of API routes.
Sources: packages/create-farm-app/templates/auth/README.md:5-15, skills/farmjs/SKILL.md:195-200
Provider Integrations
Provider integrations use a typed adapter model to connect to third-party identity services. These integrations mount provider-owned routes (e.g., /api/auth/*) and provide typed callers for operations like login, logout, and session retrieval.
Sources: skills/farmjs/SKILL.md:180-195, packages/create-farm-app/src/index.ts:50-70
Authentication Data Flow
The following diagram illustrates how a request interacts with the authentication system.
The authentication system validates sessions before route handlers execute.
Sources: packages/create-farm-app/templates/auth/README.md:25-35, skills/farmjs/SKILL.md:200-210
Supported Authentication Providers
Farm.js includes official starters for several major authentication providers through the @farm.js/create-app template system.
| Provider | Integration Package | Primary Features |
|---|---|---|
| Built-in Auth | @farm.js/auth | Email/password, SQLite/Postgres sessions, Local ownership. |
| Better Auth | @farm.js/better-auth | Social providers, advanced plugins, custom adapters. |
| Auth0 | @farm.js/auth0 | Managed enterprise auth, OAuth2, universal login. |
| Clerk | @farm.js/clerk | User management UI, account entry points, secure sessions. |
| Supabase | @farm.js/supabase | PostgreSQL-backed auth, OAuth, secure JWT sessions. |
| WorkOS | @farm.js/workos | AuthKit, organization-level sessions, B2B features. |
| Auth.js | @farm.js/authjs | GitHub/Google OAuth, standard Auth.js ecosystem. |
Sources: packages/create-farm-app/src/index.ts:70-150, skills/farmjs/SKILL.md:180-190
Implementation and Configuration
Server-Side Session Handling
Server components and API routes access authentication state through the auth helper. The auth.session() function retrieves the current session data, while auth.user() returns the specific user object.
Sources: packages/create-farm-app/templates/auth/README.md:25-30, skills/farmjs/SKILL.md:205-210
Client-Side Hooks
For interactive components, the useAuth hook provides access to the current account and session state. This hook is imported from the specific integration client package (e.g., @farm.js/auth/client).
Sources: packages/create-farm-app/templates/auth/README.md:30-35, skills/farmjs/SKILL.md:200-205
Route Protection via Middleware
Developers implement route-level protection by creating a middleware.ts file within a route segment. The middleware checks for an active session and redirects anonymous users to a sign-in page.
// Example: src/app/dashboard/middleware.ts
import { auth } from "@farm.js/auth/server";
export async function middleware(req) {
const session = await auth.session();
if (!session) {
return Response.redirect(new URL("/sign-in", req.url));
}
}
Sources: packages/create-farm-app/templates/auth/README.md:28-32, skills/farmjs/SKILL.md:210-215
Production Configuration
Production authentication requires specific environment variables to manage encryption and external service connections.
| Variable | Requirement | Description |
|---|---|---|
FARM_AUTH_URL | Required | The public application origin (e.g., https://example.com). |
FARM_AUTH_SECRET | Required | A 32+ character random secret for encrypting session data. |
DATABASE_URL | Required | Connection string for the production Postgres database. |
Sources: packages/create-farm-app/templates/auth/README.md:45-55, packages/create-farm-app/src/index.ts:50-60
Database Migrations
Before serving production traffic, the auth schema must be applied to the target database. The command pnpm auth:migrate executes the necessary schema updates for built-in authentication.
Sources: packages/create-farm-app/templates/auth/README.md:58-62, packages/create-farm-app/src/index.ts:60-65
Integration Registry Logic
Integrations are registered in the farm.config.ts file. This registry enables the framework to generate typed callers and inject necessary providers into the application tree.
The registry ensures that integration secrets remain on the server while exposing typed interfaces to the browser.
Sources: skills/farmjs/SKILL.md:150-175, ARCHITECTURE.md:40-60
Authentication in Farm.js balances developer speed through auth: true with the flexibility of complex third-party providers. By maintaining typed boundaries, the framework ensures that authentication state is predictable across the full stack.