Por qué better-auth para SvelteKit

Toda aplicación web seria se enfrenta tarde o temprano con la autenticación. El ecosistema no carece de opciones: Lucia, Auth.js, Clerk, Supabase Auth, cada una con su propia opinión sobre dónde viven las sesiones, cómo luce el esquema de base de datos y qué tan estrecha es su integración con el framework. better-auth adopta una posición refrescantemente práctica: es consciente del framework pero no está atado a él, genera su esquema como SQL plano mediante una CLI, expone una API TypeScript limpia e incluye un plugin para SvelteKit que conecta las cookies al modelo de respuesta de SvelteKit correctamente.

Algo que better-auth no exige es un ORM. Funciona directamente con clientes de base de datos nativos y gestiona sus propias consultas internamente. Le proporcionas una conexión; él se encarga de todo lo relacionado con la autenticación a partir de ahí. Tus propias consultas de dominio siguen siendo tuyas para escribirlas como prefieras.

Este artículo usa better-sqlite3 como driver de base de datos concreto: requiere cero configuración, se ejecuta en el mismo proceso y es la forma más rápida de tener una configuración funcional. La capa de base de datos es deliberadamente una zona de intercambio: si usas PostgreSQL, MySQL o Turso, solo esa sección cambia. Todas las demás partes — el hook, el cliente, la interfaz, el cableado del contexto — son idénticas independientemente de qué base de datos esté por debajo.

Al final tendrás un sistema de autenticación completo y funcional construido en esta secuencia exacta:

Paso	Qué hace	Archivo(s)
1	Instalar paquetes y aprobar la compilación nativa	—
2	Configurar variables de entorno	`.env`
3	Abrir la conexión a la base de datos	`src/lib/server/db.ts`
4	Configurar better-auth	`src/lib/server/auth.ts`
5	Declarar los locals de TypeScript	`src/app.d.ts`
6	Generar el esquema de base de datos	`npx @better-auth/cli`
7	Aplicar el esquema	`sqlite3` o `db.exec()`
8	Montar la ruta API catch-all	`src/routes/api/auth/[...all]/+server.ts`
9	Validar sesiones en el hook	`src/hooks.server.ts`
10	Crear el cliente del navegador	`src/lib/client/auth.ts`
11	Construir la página de inicio de sesión	`src/routes/login/+page.svelte`
12	Construir la página de registro	`src/routes/register/+page.svelte`
13	Construir el botón de cierre de sesión	`src/lib/components/LogoutButton.svelte`
14	Conectar `locals.user` al contexto	`src/routes/+layout.server.ts` + `+layout.svelte`
15	Construir la página del dashboard	`src/routes/dashboard/+page.svelte`

Cada paso crea algo de lo que depende el siguiente. El orden importa; en particular, auth.ts debe existir antes de ejecutar la CLI, y app.d.ts debe declarar los locals antes de que el hook les asigne valores. Sigue los pasos en orden y no encontrarás errores evitables.

Una vez que locals.user está disponible, se integra directamente con el patrón createAuthContext() que se cubre en Arquitectura de Autenticación con Context. Ese artículo explica por qué el contexto es el mecanismo de distribución correcto. Este explica cómo alimentarlo con datos de sesión reales.

El Espacio del Problema

Implementar tu propia autenticación desde cero es una de las formas más confiables de introducir vulnerabilidades de seguridad. El hash de contraseñas, la generación de tokens de sesión, la protección CSRF, los atributos de cookies (HttpOnly, Secure, SameSite), la rotación de tokens — cada uno es una pieza sutil y fundamental. Equivocarse en cualquiera de ellas puede exponer silenciosamente a tus usuarios.

Al mismo tiempo, muchas soluciones de autenticación "totalmente gestionadas" te quitan el control exactamente en los momentos equivocados. Almacenan las sesiones en su nube, imponen su esquema y hacen que sea incómodo inspeccionar un registro de sesión en tu propia base de datos o ejecutar una migración específica.

better-auth apunta al punto medio: tú posees la base de datos, tú posees el esquema, tú posees el despliegue. La librería se encarga de la criptografía y el ciclo de vida de las sesiones. Tu trabajo es integrarlo en el modelo de solicitud/respuesta de SvelteKit, lo cual resulta ser sorprendentemente mínimo una vez que ves las piezas individuales.

Paso 1 — Instalar Paquetes

pnpm add better-auth better-sqlite3
pnpm add -D @types/better-sqlite3

Eso es todo lo que hay que instalar. Dos paquetes, nada más.

Una vez completada la instalación, pnpm mostrará una advertencia:

Ignored build scripts: better-sqlite3.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

Esto es esperado y es bloqueante — debes resolverlo antes de continuar. better-sqlite3 es un addon nativo de Node.js que compila un pequeño binario C++ durante la instalación. Sin ese binario el paquete simplemente no funciona. La política de seguridad de pnpm bloquea los scripts de compilación de dependencias por defecto hasta que los apruebes explícitamente:

pnpm approve-builds better-sqlite3

pnpm escribe la aprobación en el archivo .npmrc de tu proyecto, por lo que persiste entre instalaciones futuras y es seguro incluirlo en tu repositorio. Ejecutar pnpm approve-builds sin argumentos abre un selector interactivo si prefieres revisar todas las aprobaciones pendientes de una vez.

Un paquete que específicamente no debes agregar aquí: @better-auth/cli. La CLI es necesaria en el Paso 6 para generar el esquema de base de datos, pero no debe instalarse como dependencia del proyecto. @better-auth/cli lista @prisma/client como peer opcional, y la configuración auto-install-peers de pnpm resuelve peers opcionales de forma anticipada por defecto, lo que significa que instalar la CLI trae Prisma a tu proyecto silenciosamente.

Usa npx en su lugar, que descarga y ejecuta la CLI en una ubicación temporal aislada sin tocar tu node_modules. Cuando ejecutes el comando npx en el Paso 6 por primera vez, verás un mensaje como este:

Need to install the following packages:
  @better-auth/cli@x.x.x
Ok to proceed? (y)

Esto es normal — escribe y y presiona Enter para continuar. npx almacena en caché la descarga, por lo que el mensaje solo aparece una vez.

Paso 2 — Variables de Entorno

better-auth necesita dos valores en tiempo de ejecución que pertenecen a tu archivo .env:

# .env

# A long random string used to sign and verify session tokens.
# Generate a good one with: openssl rand -base64 32
BETTER_AUTH_SECRET="replace_with_a_strong_random_secret"

# The base URL your application is served from.
# In production, set this to your actual domain.
BETTER_AUTH_URL="http://localhost:5173"

# Also add this - the browser client needs the base URL too,
# and it must use the PUBLIC_ prefix to be accessible in browser code.
PUBLIC_BASE_URL="http://localhost:5173"

BETTER_AUTH_SECRET es el valor más sensible desde el punto de vista de seguridad en esta configuración. better-auth lo usa para firmar criptográficamente los tokens de sesión; cualquiera que tenga el secreto puede falsificar un token de sesión válido sin tocar la base de datos. Trátalo como una contraseña raíz de base de datos: nunca lo confirmes en el repositorio, rótalo si se filtra e inyéctalo desde un gestor de secretos en producción.

BETTER_AUTH_URL le dice a better-auth dónde vive la aplicación para que pueda construir URLs absolutas. Los correos de restablecimiento de contraseña, los URIs de redirección de OAuth y cualquier otra URL que better-auth necesite construir se derivan de este valor.

PUBLIC_BASE_URL sirve el mismo propósito para el cliente del navegador. El prefijo PUBLIC_ es la convención de SvelteKit para las variables de entorno que son seguras de incluir en los bundles del navegador. Las variables sin este prefijo son solo del servidor y no pueden importarse en el código del cliente.

SvelteKit expone las variables solo del servidor a través de $env/static/private y las variables públicas a través de $env/static/public. El static en ambas significa que los valores se insertan en línea en tiempo de compilación; el bundler se niega a incluir variables private en cualquier código que pueda llegar al navegador.

Paso 3 — Abrir la Conexión a la Base de Datos

Crea un módulo que abra una única conexión better-sqlite3 para el proceso del servidor. Este es el único archivo específico de la base de datos en toda la integración — todo lo demás es igual independientemente de qué base de datos uses.

// src/lib/server/db.ts

import Database from 'better-sqlite3'
import { join } from 'node:path'

// Open a single connection for the entire server process to share.
export const db = new Database(join(process.cwd(), 'db/local.db'))

// Enable WAL mode for better concurrency during development.
db.pragma('journal_mode = WAL')

Por qué el modo WAL

WAL (Write-Ahead Logging) permite lecturas concurrentes durante las escrituras. better-auth realiza una consulta de sesión en cada solicitud autenticada, por lo que sin WAL una operación de escritura — un inicio de sesión, una actualización de sesión — bloquearía brevemente todas las lecturas.

Algo que vale la pena saber: db.pragma('journal_mode = WAL') no se ejecuta al iniciar el servidor. SvelteKit carga los módulos del servidor de forma diferida, por lo que db.ts solo se importa la primera vez que una solicitud lo necesita — cuando hooks.server.ts se ejecuta para una solicitud entrante. Esto significa que local.db-wal y local.db-shm no aparecerán en el disco hasta que abras una página en el navegador por primera vez después de iniciar el servidor de desarrollo. Ese es el comportamiento esperado. Ejecutar sqlite3 db/local.db < db/schema.sql solo nunca producirá los archivos auxiliares — solo la aplicación en ejecución puede hacerlo.

Por qué `process.cwd()` en lugar de una ruta relativa

Una cadena relativa simple como 'db/local.db' se resuelve contra el directorio desde el que se inició el proceso de Node. Cuando SvelteKit ejecuta el servidor de desarrollo, siempre es la raíz del proyecto, por lo que funciona. Pero cuando la CLI de better-auth importa este archivo a través de npx, puede usar un directorio de trabajo diferente y colocar silenciosamente el archivo de base de datos en el lugar equivocado. process.cwd() siempre está anclado a la raíz del proyecto cuando se invoca a través de scripts de pnpm o npx ejecutados desde el directorio del proyecto, por lo que join(process.cwd(), 'db/local.db') es seguro en ambos contextos.

Agrega los archivos de base de datos a .gitignore — el directorio en sí permanece rastreado ya que schema.sql también vive allí:

echo 'db/local.db' >> .gitignore
echo 'db/local.db-wal' >> .gitignore
echo 'db/local.db-shm' >> .gitignore

Este es el único archivo que cambia cuando pasas a PostgreSQL, MySQL o Turso. better-auth incluye adaptadores oficiales para cada uno. Reemplaza la línea database: db en auth.ts (Paso 4) con el adaptador correspondiente; todo lo demás en este artículo sigue igual.

Base de Datos	Driver	Cómo pasarlo a betterAuth()
SQLite	`better-sqlite3`	`database: db` - pasar directamente, no se necesita adaptador
Turso / libSQL	`@libsql/client`	`database: libsqlAdapter(client)` desde `better-auth/adapters/libsql`
PostgreSQL	`pg` / `postgres`	`database: pgAdapter(pool)` desde `better-auth/adapters/pg`
MySQL	`mysql2`	`database: mysqlAdapter(conn)` desde `better-auth/adapters/mysql`
MongoDB	`mongodb`	`database: mongodbAdapter(client)` desde `better-auth/adapters/mongodb`

Cada paso después del Paso 3 es idéntico independientemente del adaptador que elijas. La configuración completa para cada alternativa común está a continuación — los principiantes con SQLite pueden ir directamente al Paso 4.

PostgreSQL con `pg`

pnpm add pg better-auth
pnpm add -D @types/pg

// src/lib/server/db.ts
import pg from 'pg'

// A connection pool — pg manages multiple connections automatically.
// Pool size defaults to 10; tune with max: N if needed.
export const db = new pg.Pool({
	connectionString: process.env.DATABASE_URL
	// In production, always require SSL:
	// ssl: { rejectUnauthorized: true },
})

// src/lib/server/auth.ts — only the database line changes
import { pgAdapter } from 'better-auth/adapters/pg'
import { db } from '$lib/server/db.js'

export const auth = betterAuth({
	database: pgAdapter(db)
	// ... everything else stays the same
})

# .env
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Turso (libSQL) — SQLite en el Edge

Turso es un servicio de SQLite distribuido. Mismo dialecto SQL que better-sqlite3, pero se ejecuta como una base de datos remota gestionada o con réplica embebida — muy adecuado para despliegues en el edge y configuraciones multi-región.

pnpm add @libsql/client better-auth

// src/lib/server/db.ts
import { createClient } from '@libsql/client'

export const db = createClient({
	url: process.env.TURSO_DATABASE_URL!,
	authToken: process.env.TURSO_AUTH_TOKEN
})

// src/lib/server/auth.ts — only the database line changes
import { libsqlAdapter } from 'better-auth/adapters/libsql'
import { db } from '$lib/server/db.js'

export const auth = betterAuth({
	database: libsqlAdapter(db)
	// ... everything else stays the same
})

# .env
TURSO_DATABASE_URL="libsql://your-db.turso.io"
TURSO_AUTH_TOKEN="your-turso-token"

Para desarrollo local sin una cuenta de Turso, apúntalo a un archivo local en su lugar:

export const db = createClient({ url: 'file:db/local.db' })

MySQL con `mysql2`

pnpm add mysql2 better-auth

// src/lib/server/db.ts
import mysql from 'mysql2/promise'

// createPool returns a promise-based pool compatible with
// better-auth's MySQL adapter.
export const db = mysql.createPool({
	uri: process.env.DATABASE_URL
	// waitForConnections: true,
	// connectionLimit: 10,
})

// src/lib/server/auth.ts — only the database line changes
import { mysqlAdapter } from 'better-auth/adapters/mysql'
import { db } from '$lib/server/db.js'

export const auth = betterAuth({
	database: mysqlAdapter(db)
	// ... everything else stays the same
})

# .env
DATABASE_URL="mysql://user:password@localhost:3306/mydb"

Paso 4 — Configurar better-auth

Ahora que existe una conexión a la base de datos, crea la configuración central de autenticación. Todas las demás piezas de la integración o bien alimentan a este objeto o leen de él.

better-auth no tiene ninguna estrategia de autenticación incorporada — nada está habilitado por defecto. Optas explícitamente por cada estrategia a través del array plugins. Esto mantiene el bundle ligero: la librería solo incluye código para lo que realmente usas. La configuración base establece los primitivos de seguridad (secreto, URL base, conexión a la base de datos, manejo de cookies de SvelteKit) y luego agregas estrategias de autenticación encima.

Configuración Base

Comienza con el cableado mínimo que requiere toda configuración independientemente de la estrategia de autenticación que elijas:

// src/lib/server/auth.ts

import { betterAuth } from 'better-auth'
import { sveltekitCookies } from 'better-auth/svelte-kit'
import { getRequestEvent } from '$app/server'
import { db } from '$lib/server/db.js'
import { BETTER_AUTH_SECRET, BETTER_AUTH_URL } from '$env/static/private'

export const auth = betterAuth({
	secret: BETTER_AUTH_SECRET,
	baseURL: BETTER_AUTH_URL,

	// Pass the better-sqlite3 connection directly.
	// better-auth detects the driver and manages all auth-related
	// queries itself - you never write SQL for the auth tables.
	database: db,

	plugins: [
		// Teaches better-auth to write session cookies using SvelteKit's
		// event.cookies.set() rather than raw Set-Cookie headers.
		// getRequestEvent is required - better-auth uses it to access
		// the active RequestEvent and route cookie writes through
		// event.cookies.set() rather than raw Set-Cookie headers.
		//
		// sveltekitCookies must always be the LAST plugin in the array.
		sveltekitCookies(getRequestEvent)
	]
})

// Infer TypeScript types directly from the configuration object.
// These update automatically when you add or remove plugins —
// no manual type maintenance required.
export type Session = typeof auth.$Infer.Session
export type User = typeof auth.$Infer.Session.user

sveltekitCookies(getRequestEvent) es el único plugin no negociable. El modelo de respuesta de SvelteKit requiere que las cookies se escriban a través de event.cookies.set(). Si better-auth escribe un encabezado Set-Cookie directamente en el objeto Response — que es el comportamiento HTTP estándar fuera de SvelteKit —, SvelteKit lo descarta silenciosamente. La cookie de sesión nunca llega al navegador, el inicio de sesión parece completarse exitosamente en el servidor, pero el usuario no está autenticado en la siguiente solicitud sin ningún mensaje de error que explique por qué.

getRequestEvent se importa desde $app/server y le da al plugin acceso al RequestEvent activo de SvelteKit en el momento de la llamada, específicamente el objeto cookies que necesita. Este argumento se volvió obligatorio en una versión posterior de better-auth; llamar a sveltekitCookies() sin él es tanto un error de TypeScript como un fallo silencioso en tiempo de ejecución.

Una restricción más que es fácil pasar por alto: sveltekitCookies siempre debe ser el último plugin del array. better-auth ejecuta los plugins en orden, y sveltekitCookies intercepta las operaciones de cookies de los plugins que se ejecutaron antes. Si se lista otro plugin después de él, las escrituras de cookies de ese plugin ocurren después del punto de intercepción y se descartan silenciosamente.

Elegir una Estrategia de Autenticación

Con la configuración base en su lugar, agrega uno o más plugins de estrategia de autenticación al array plugins. Cada estrategia es una importación independiente — agrega solo lo que tu aplicación necesita.

Email y contraseña es el punto de partida más común. emailAndPassword es una opción de nivel superior en betterAuth(), no un plugin. Agrégalo junto a la configuración base:

export const auth = betterAuth({
	secret: BETTER_AUTH_SECRET,
	baseURL: BETTER_AUTH_URL,
	database: db,

	// Top-level option, not a plugin. Enables signIn.email() and signUp.email()
	// on the browser client. better-auth hashes passwords with bcrypt internally.
	emailAndPassword: { enabled: true },

	plugins: [
		sveltekitCookies(getRequestEvent) // must be last
	]
})

OAuth (inicio de sesión social) autentica a través de un proveedor externo — GitHub, Google, Discord y otros. No se almacena ninguna contraseña local. Configura los proveedores a través del objeto de nivel superior socialProviders, luego agrega las credenciales a .env:

export const auth = betterAuth({
	// ...base config...
	socialProviders: {
		github: { clientId: GITHUB_CLIENT_ID, clientSecret: GITHUB_CLIENT_SECRET },
		google: { clientId: GOOGLE_CLIENT_ID, clientSecret: GOOGLE_CLIENT_SECRET }
	},
	plugins: [sveltekitCookies(getRequestEvent)]
})

Magic link envía una URL de inicio de sesión de un solo uso al correo del usuario — sin contraseña almacenada. Vive en el array plugins (antes de sveltekitCookies) y necesita un transporte de correo electrónico:

import { magicLink } from 'better-auth/plugins'

export const auth = betterAuth({
	// ...base config...
	plugins: [
		magicLink({
			sendMagicLink: async ({ email, url }) => {
				await sendEmail({ to: email, subject: 'Sign in', html: `<a href="${url}">Sign in</a>` })
			}
		}),
		sveltekitCookies(getRequestEvent) // must be last
	]
})

Combinar estrategias es sencillo ya que emailAndPassword y socialProviders son opciones de nivel superior y coexisten libremente. El resto de este artículo usa email/contraseña como ejemplo concreto. Todo a partir del Paso 5 es idéntico independientemente de la estrategia que elijas.

Paso 5 — Declarar los Tipos Locales de TypeScript

Antes de escribir el hook que asigna valores a event.locals, necesitas indicarle a TypeScript qué contiene event.locals. SvelteKit utiliza una declaración de ambiente global para esto en src/app.d.ts — sin ella, TypeScript no sabe que las propiedades user y session existen, y el hook producirá errores de tipo.

// src/app.d.ts

import type { User, Session } from '$lib/server/auth.js'

declare global {
	namespace App {
		interface Locals {
			// The authenticated user, or null if there is no valid session.
			// Set by hooks.server.ts before any load function runs.
			user: User | null

			// The raw session record from better-auth.
			// Useful if you need session metadata such as expiry or IP address.
			session: Session | null
		}
	}
}

export {}

Los tipos User y Session provienen de las exportaciones inferidas que creaste en el Paso 4. Esto mantiene todo sincronizado: si better-auth cambia la forma del usuario al agregar un plugin, el cambio fluye automáticamente a través del tipo inferido hacia app.d.ts y hacia cada función load que lee locals.user.

Paso 6 — Generar el Esquema de la Base de Datos

better-auth necesita cuatro tablas: user, session, account y verification. El CLI las genera como SQL plano basándose en tu configuración de auth.ts. Este es el momento correcto para ejecutarlo: la configuración debe existir primero, por eso fue el Paso 4 y este es el Paso 6.

Ejecuta el CLI con npx. El flag --config es necesario porque el CLI busca auth.ts en la raíz del proyecto por defecto y no encontrará el tuyo dentro de src/lib/server/ sin que le indiques dónde buscar:

mkdir -p db
npx @better-auth/cli generate --config src/lib/server/auth.ts --output db/schema.sql

El flag -p en mkdir hace que el comando no tenga efecto si db/ ya existe, por lo que es seguro ejecutarlo en cualquier momento. Si es la primera vez que ejecutas el comando, npx te pedirá que confirmes la descarga; escribe y para continuar. El CLI no se instala en tu proyecto; se ejecuta desde una caché temporal. Consulta el Paso 1 para saber por qué se prefiere npx en lugar de instalar el CLI como dependencia.

El schema.sql generado para SQLite tiene este aspecto:

-- schema.sql
-- Generated by @better-auth/cli
-- Re-run this command whenever you add or remove plugins.

CREATE TABLE IF NOT EXISTS "user" (
  "id"            TEXT NOT NULL PRIMARY KEY,
  "name"          TEXT NOT NULL,
  "email"         TEXT NOT NULL UNIQUE,
  "emailVerified" INTEGER NOT NULL,
  "image"         TEXT,
  "createdAt"     INTEGER NOT NULL,
  "updatedAt"     INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS "session" (
  "id"        TEXT NOT NULL PRIMARY KEY,
  "expiresAt" INTEGER NOT NULL,
  "token"     TEXT NOT NULL UNIQUE,
  "createdAt" INTEGER NOT NULL,
  "updatedAt" INTEGER NOT NULL,
  "ipAddress" TEXT,
  "userAgent" TEXT,
  "userId"    TEXT NOT NULL REFERENCES "user"("id") ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS "account" (
  "id"                    TEXT NOT NULL PRIMARY KEY,
  "accountId"             TEXT NOT NULL,
  "providerId"            TEXT NOT NULL,
  "userId"                TEXT NOT NULL REFERENCES "user"("id") ON DELETE CASCADE,
  "accessToken"           TEXT,
  "refreshToken"          TEXT,
  "idToken"               TEXT,
  "accessTokenExpiresAt"  INTEGER,
  "refreshTokenExpiresAt" INTEGER,
  "scope"                 TEXT,
  "password"              TEXT,
  "createdAt"             INTEGER NOT NULL,
  "updatedAt"             INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS "verification" (
  "id"         TEXT NOT NULL PRIMARY KEY,
  "identifier" TEXT NOT NULL,
  "value"      TEXT NOT NULL,
  "expiresAt"  INTEGER NOT NULL,
  "createdAt"  INTEGER,
  "updatedAt"  INTEGER
);

La tabla account es donde viven las contraseñas hasheadas cuando se utiliza el plugin emailAndPassword. La tabla verification maneja los tokens de verificación de correo electrónico y los tokens de restablecimiento de contraseña. better-auth gestiona todas las lecturas y escrituras en estas tablas; nunca las consultas directamente.

El esquema generado refleja tu configuración actual de plugins. Agregar `twoFactor()` requiere una tabla `twoFactor`. Agregar `organization()` requiere varias tablas nuevas. Vuelve a ejecutar el CLI después de cambiar tu lista de plugins y luego aplica el nuevo SQL.

Para asegurarte de que la versión del CLI coincida con tu versión instalada de better-auth, indícala explícitamente:

npx @better-auth/cli@1.x.x generate --config src/lib/server/auth.ts --output db/schema.sql

Reemplaza 1.x.x con tu versión instalada; comprueba node_modules/better-auth/package.json. Las versiones incompatibles pueden generar un esquema que no coincide con lo que la librería espera en tiempo de ejecución.

Paso 7 — Aplicar el Esquema

Aplica el SQL generado a tu base de datos SQLite:

sqlite3 db/local.db < db/schema.sql

db/local.db se creará si aún no existe. La cláusula IF NOT EXISTS en cada instrucción CREATE TABLE hace que este comando sea seguro para re-ejecutar; aplicar el esquema contra una base de datos que ya tiene las tablas no tiene ningún efecto.

Si quieres que la base de datos se inicialice automáticamente al arrancar —útil para que un clon nuevo funcione sin pasos manuales—, puedes aplicar el esquema desde db.ts en su lugar:

// src/lib/server/db.ts

import Database from 'better-sqlite3'
import { readFileSync } from 'node:fs'
import { join } from 'node:path'

export const db = new Database(join(process.cwd(), 'db/local.db'))
db.pragma('journal_mode = WAL')

// Apply the generated schema on every startup.
// IF NOT EXISTS makes this safe to run against an existing database.
const schema = readFileSync(join(process.cwd(), 'db/schema.sql'), 'utf-8')
db.exec(schema)

Ambos enfoques funcionan. El comando sqlite3 es explícito y fácil de auditar; el enfoque de inicio automático es conveniente para el desarrollo. En producción con una base de datos real, normalmente aplicarías los cambios de esquema a través de un gestor de migraciones apropiado con archivos versionados.

Reiniciar la Base de Datos

Durante el desarrollo, ocasionalmente necesitarás empezar desde cero — para probar el registro con una base de datos nueva, limpiar cuentas de prueba o recuperarte de un estado corrupto. Elimina los tres archivos SQLite y vuelve a aplicar el esquema:

rm db/local.db db/local.db-wal db/local.db-shm
sqlite3 db/local.db < db/schema.sql

Los archivos auxiliares WAL (local.db-wal y local.db-shm) deben eliminarse junto con el archivo principal. Dejarlos huérfanos provoca errores de SQLite en el próximo inicio porque hacen referencia a un registro de transacciones para un archivo de base de datos que ya no existe.

Si estás utilizando el enfoque de inicialización al arranque (db.exec(schema) en db.ts), omite el segundo comando — simplemente elimina los archivos y reinicia el servidor de desarrollo. El esquema se vuelve a aplicar automáticamente en el próximo inicio.

Paso 8 — Montar la Ruta API Catch-All

better-auth maneja todos sus propios endpoints — inicio de sesión, cierre de sesión, registro, renovación de sesión, verificación de correo electrónico — a través de un único manejador de solicitudes. Móntalo en la ubicación convencional:

// src/routes/api/auth/[...all]/+server.ts

import { auth } from '$lib/server/auth.js'
import type { RequestHandler } from './$types'

export const GET: RequestHandler = (event) => {
	return auth.handler(event.request)
}

export const POST: RequestHandler = (event) => {
	return auth.handler(event.request)
}

Si TypeScript reporta Cannot find module './$types', la generación de tipos de SvelteKit aún no ha ejecutado. SvelteKit genera los archivos $types automáticamente cuando el servidor de desarrollo inicia o cuando ejecutas sync explícitamente:

pnpm exec svelte-kit sync

Ejecuta esto una vez; el error desaparece y RequestHandler se resuelve correctamente. El servidor de desarrollo ejecuta sync en cada inicio, por lo que en el desarrollo normal solo te encontrarás con esto al crear archivos antes de iniciar el servidor por primera vez.

El segmento dinámico [...all] captura cada ruta bajo /api/auth/. Cuando el navegador envía POST /api/auth/sign-in/email, SvelteKit lo enruta a este archivo y auth.handler lo despacha a la lógica de inicio de sesión con correo electrónico y contraseña. Cuando el navegador envía POST /api/auth/sign-out, el mismo manejador lo enruta al cierre de sesión. Nunca escribes rutas individuales para operaciones de autenticación individuales; el manejador las cubre todas, incluidas las operaciones agregadas por futuros plugins.

El manejador retorna una Response estándar. El plugin sveltekitCookies() del Paso 4 intercepta la escritura de la cookie de sesión dentro del manejador y la enruta a través de event.cookies.set() antes de que se retorne la respuesta, que es por qué ese plugin era necesario.

Paso 9 — Validar Sesiones en el Hook

El hook es donde cada solicitud obtiene su identidad autenticada. Se ejecuta antes de cualquier función load o acción de formulario en tu aplicación, lo que significa que para cuando tus páginas se ejecutan, event.locals.user ya está resuelto.

// src/hooks.server.ts

import { auth } from '$lib/server/auth.js'
import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	const session = await auth.api.getSession({
		headers: event.request.headers
	})

	// Always assign both locals. null means unauthenticated —
	// which is a valid and expected state, not missing data.
	event.locals.user = session?.user ?? null
	event.locals.session = session?.session ?? null

	return resolve(event)
}

auth.api.getSession lee la cookie de sesión de los encabezados de la solicitud, valida el token criptográficamente contra BETTER_AUTH_SECRET, verifica que la sesión no haya expirado y retorna los objetos completos de sesión y usuario, o null si algo falla en la validación. Todo el proceso es local: tu archivo SQLite, tu secreto, sin llamadas a redes externas.

event.locals tiene alcance por solicitud. SvelteKit crea un objeto locals nuevo para cada solicitud entrante y lo descarta después de enviar la respuesta. No hay estado mutable compartido entre solicitudes, no hay riesgo de que los datos de un usuario se filtren en la solicitud de otro usuario, y no hay contaminación de SSR.

Con locals.user poblado por el hook, proteger una ruta dentro de una función load es una sola verificación:

// src/routes/dashboard/+page.server.ts

import { redirect } from '@sveltejs/kit'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		// This redirect happens before SvelteKit renders any HTML.
		// The user never receives a flash of protected content.
		redirect(303, '/login')
	}

	return { user: locals.user }
}

Paso 10 — Crear el Cliente de Navegador

El objeto auth de src/lib/server/auth.ts no puede importarse en código del navegador — contiene una conexión a la base de datos que no existe en el navegador, y SvelteKit aplica el límite de $lib/server/ en tiempo de compilación. Para operaciones del lado del navegador, better-auth proporciona un cliente tipado separado que se comunica con el servidor a través de HTTP:

// src/lib/client/auth.ts

// Import from 'better-auth/svelte', not 'better-auth/client'.
// The Svelte-specific client adds useSession() as a reactive Svelte store,
// so session state integrates natively with Svelte's reactivity model.
// The generic 'better-auth/client' works but gives you a plain object
// that does not update components automatically.
import { createAuthClient } from 'better-auth/svelte'
import { PUBLIC_BASE_URL } from '$env/static/public'

export const authClient = createAuthClient({
	baseURL: PUBLIC_BASE_URL ?? 'http://localhost:5173'
})

export type AuthClientSession = typeof authClient.$Infer.Session

No se necesitan plugins en el cliente para correo electrónico y contraseña. Los métodos signIn.email() y signUp.email() están disponibles por defecto porque emailAndPassword fue habilitado en el servidor en el Paso 4. Los plugins de cliente solo son necesarios para plugins de servidor que extienden la superficie de la API — por ejemplo, agregar twoFactor() en el servidor significa agregar twoFactorClient() al array de plugins del cliente aquí, para que los métodos de doble factor estén disponibles y correctamente tipados.

Colocar el cliente en src/lib/client/ en lugar de src/lib/server/ es intencional. El límite de server/ se aplica en tiempo de compilación; cualquier intento de importar un módulo de $lib/server/ en código del navegador es un error de compilación. El cliente solo realiza llamadas fetch y pertenece fuera de ese límite.

Paso 11 — Construir la Página de Inicio de Sesión

Con toda la infraestructura en su lugar, el inicio de sesión es un manejo de formularios Svelte 5 directo:

<!-- src/routes/login/+page.svelte -->
<script lang="ts">
	import { authClient } from '$lib/client/auth.js'
	import { goto, invalidateAll } from '$app/navigation'

	let email = $state('')
	let password = $state('')
	let error = $state<string | null>(null)
	let submitting = $state(false)

	async function handleSubmit(event: Event) {
		event.preventDefault()
		error = null
		submitting = true

		const result = await authClient.signIn.email({ email, password })

		submitting = false

		if (result.error) {
			error = result.error.message ?? 'Sign in failed. Please try again.'
			return
		}

		// The session cookie has been written by the server.
		// invalidateAll() forces the layout load to re-run so locals.user
		// is picked up by the hook and page.data.user updates before
		// navigating. Without this, the context still holds null from
		// before sign-in and the dashboard shows the unauthenticated state.
		await invalidateAll()
		goto('/dashboard')
	}
</script>

<div class="page">
	<div class="card">
		<div class="card-header">
			<h1 class="card-title">Sign in</h1>
			<p class="card-description">Enter your email and password to continue.</p>
		</div>

		{#if error}
			<div class="alert" role="alert">{error}</div>
		{/if}

		<form class="form" onsubmit={handleSubmit}>
			<div class="field">
				<label class="label" for="email">Email</label>
				<input
					id="email"
					class="input"
					type="email"
					bind:value={email}
					autocomplete="email"
					placeholder="you@example.com"
					required
				/>
			</div>

			<div class="field">
				<label class="label" for="password">Password</label>
				<input
					id="password"
					class="input"
					type="password"
					bind:value={password}
					autocomplete="current-password"
					placeholder="••••••••"
					required
				/>
			</div>

			<button class="btn-primary" type="submit" disabled={submitting}>
				{submitting ? 'Signing in…' : 'Sign in'}
			</button>
		</form>

		<p class="footer-link">
			Don't have an account? <a href="/register">Create one</a>
		</p>
	</div>
</div>

<style>
	.page {
		min-height: 100vh;
		display: flex;
		align-items: center;
		justify-content: center;
		padding: 1rem;
		background-color: hsl(0 0% 98%);
	}

	.card {
		width: 100%;
		max-width: 400px;
		background: hsl(0 0% 100%);
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.5rem;
		padding: 2rem;
		box-shadow: 0 1px 3px hsl(0 0% 0% / 0.06);
	}

	.card-header {
		margin-bottom: 1.5rem;
	}

	.card-title {
		font-size: 1.25rem;
		font-weight: 600;
		color: hsl(240 10% 3.9%);
		margin: 0 0 0.25rem;
	}

	.card-description {
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		margin: 0;
	}

	.alert {
		background: hsl(0 86% 97%);
		border: 1px solid hsl(0 72% 88%);
		color: hsl(0 72% 40%);
		border-radius: 0.375rem;
		padding: 0.75rem 1rem;
		font-size: 0.875rem;
		margin-bottom: 1rem;
	}

	.form {
		display: flex;
		flex-direction: column;
		gap: 1rem;
	}

	.field {
		display: flex;
		flex-direction: column;
		gap: 0.375rem;
	}

	.label {
		font-size: 0.875rem;
		font-weight: 500;
		color: hsl(240 10% 3.9%);
	}

	.input {
		height: 2.5rem;
		padding: 0 0.75rem;
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.375rem;
		background: hsl(0 0% 100%);
		color: hsl(240 10% 3.9%);
		font-size: 0.875rem;
		outline: none;
		transition:
			border-color 0.15s,
			box-shadow 0.15s;
	}

	.input::placeholder {
		color: hsl(240 3.8% 70%);
	}

	.input:focus {
		border-color: hsl(240 5.9% 10%);
		box-shadow: 0 0 0 3px hsl(240 5.9% 10% / 0.1);
	}

	.btn-primary {
		height: 2.5rem;
		padding: 0 1rem;
		background: hsl(240 5.9% 10%);
		color: hsl(0 0% 98%);
		border: none;
		border-radius: 0.375rem;
		font-size: 0.875rem;
		font-weight: 500;
		cursor: pointer;
		transition: background 0.15s;
		margin-top: 0.25rem;
	}

	.btn-primary:hover:not(:disabled) {
		background: hsl(240 5.9% 20%);
	}

	.btn-primary:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.footer-link {
		text-align: center;
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		margin-top: 1.25rem;
		margin-bottom: 0;
	}

	.footer-link a {
		color: hsl(240 5.9% 10%);
		font-weight: 500;
		text-decoration: underline;
		text-underline-offset: 3px;
	}
</style>

authClient.signIn.email() envía las credenciales a POST /api/auth/sign-in/email. La ruta catch-all del Paso 8 lo maneja. better-auth valida las credenciales contra la contraseña hasheada en la tabla account, crea un registro de sesión en la tabla session, y el plugin sveltekitCookies() escribe la cookie de sesión HttpOnly antes de que la respuesta salga del servidor. A partir de este momento, cada solicitud que realice el navegador incluirá esa cookie, y el hook del Paso 9 la resolverá en locals.user.

Paso 12 — Construir la Página de Registro

El registro sigue la misma estructura que el inicio de sesión, con un campo adicional para el nombre:

<!-- src/routes/register/+page.svelte -->
<script lang="ts">
	import { authClient } from '$lib/client/auth.js'
	import { goto, invalidateAll } from '$app/navigation'

	let name = $state('')
	let email = $state('')
	let password = $state('')
	let error = $state<string | null>(null)
	let submitting = $state(false)

	async function handleSubmit(event: Event) {
		event.preventDefault()
		error = null
		submitting = true

		const result = await authClient.signUp.email({ name, email, password })

		submitting = false

		if (result.error) {
			error = result.error.message ?? 'Registration failed. Please try again.'
			return
		}

		// Same as sign-in: invalidate first so the layout load re-runs
		// and the context reflects the newly created session.
		await invalidateAll()
		goto('/dashboard')
	}
</script>

<div class="page">
	<div class="card">
		<div class="card-header">
			<h1 class="card-title">Create account</h1>
			<p class="card-description">Fill in the details below to get started.</p>
		</div>

		{#if error}
			<div class="alert" role="alert">{error}</div>
		{/if}

		<form class="form" onsubmit={handleSubmit}>
			<div class="field">
				<label class="label" for="name">Name</label>
				<input
					id="name"
					class="input"
					type="text"
					bind:value={name}
					autocomplete="name"
					placeholder="Jane Smith"
					required
				/>
			</div>

			<div class="field">
				<label class="label" for="email">Email</label>
				<input
					id="email"
					class="input"
					type="email"
					bind:value={email}
					autocomplete="email"
					placeholder="you@example.com"
					required
				/>
			</div>

			<div class="field">
				<label class="label" for="password">Password</label>
				<input
					id="password"
					class="input"
					type="password"
					bind:value={password}
					autocomplete="new-password"
					placeholder="Min. 8 characters"
					minlength={8}
					required
				/>
			</div>

			<button class="btn-primary" type="submit" disabled={submitting}>
				{submitting ? 'Creating account…' : 'Create account'}
			</button>
		</form>

		<p class="footer-link">
			Already have an account? <a href="/login">Sign in</a>
		</p>
	</div>
</div>

<style>
	.page {
		min-height: 100vh;
		display: flex;
		align-items: center;
		justify-content: center;
		padding: 1rem;
		background-color: hsl(0 0% 98%);
	}

	.card {
		width: 100%;
		max-width: 400px;
		background: hsl(0 0% 100%);
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.5rem;
		padding: 2rem;
		box-shadow: 0 1px 3px hsl(0 0% 0% / 0.06);
	}

	.card-header {
		margin-bottom: 1.5rem;
	}

	.card-title {
		font-size: 1.25rem;
		font-weight: 600;
		color: hsl(240 10% 3.9%);
		margin: 0 0 0.25rem;
	}

	.card-description {
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		margin: 0;
	}

	.alert {
		background: hsl(0 86% 97%);
		border: 1px solid hsl(0 72% 88%);
		color: hsl(0 72% 40%);
		border-radius: 0.375rem;
		padding: 0.75rem 1rem;
		font-size: 0.875rem;
		margin-bottom: 1rem;
	}

	.form {
		display: flex;
		flex-direction: column;
		gap: 1rem;
	}

	.field {
		display: flex;
		flex-direction: column;
		gap: 0.375rem;
	}

	.label {
		font-size: 0.875rem;
		font-weight: 500;
		color: hsl(240 10% 3.9%);
	}

	.input {
		height: 2.5rem;
		padding: 0 0.75rem;
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.375rem;
		background: hsl(0 0% 100%);
		color: hsl(240 10% 3.9%);
		font-size: 0.875rem;
		outline: none;
		transition:
			border-color 0.15s,
			box-shadow 0.15s;
	}

	.input::placeholder {
		color: hsl(240 3.8% 70%);
	}

	.input:focus {
		border-color: hsl(240 5.9% 10%);
		box-shadow: 0 0 0 3px hsl(240 5.9% 10% / 0.1);
	}

	.btn-primary {
		height: 2.5rem;
		padding: 0 1rem;
		background: hsl(240 5.9% 10%);
		color: hsl(0 0% 98%);
		border: none;
		border-radius: 0.375rem;
		font-size: 0.875rem;
		font-weight: 500;
		cursor: pointer;
		transition: background 0.15s;
		margin-top: 0.25rem;
	}

	.btn-primary:hover:not(:disabled) {
		background: hsl(240 5.9% 20%);
	}

	.btn-primary:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.footer-link {
		text-align: center;
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		margin-top: 1.25rem;
		margin-bottom: 0;
	}

	.footer-link a {
		color: hsl(240 5.9% 10%);
		font-weight: 500;
		text-decoration: underline;
		text-underline-offset: 3px;
	}
</style>

better-auth maneja el hashing de contraseñas internamente; nunca ves ni almacenas contraseñas en texto plano. El plugin emailAndPassword() utiliza bcrypt. Se escribe un registro user en la tabla user, se escribe un registro account correspondiente con la contraseña hasheada en la tabla account, y se crea una sesión en la misma respuesta. Para cuando se ejecuta goto('/dashboard'), el usuario ya ha iniciado sesión.

Paso 13 — Construir el Botón de Cierre de Sesión

El cierre de sesión limpia la sesión del lado del servidor y luego resincroniza el estado del lado del cliente. La llamada a invalidateAll() es fácil de pasar por alto y provoca un error sutil cuando está ausente:

<!-- src/lib/components/LogoutButton.svelte -->
<script lang="ts">
	import { authClient } from '$lib/client/auth.js'
	import { goto, invalidateAll } from '$app/navigation'

	let loading = $state(false)

	async function handleLogout() {
		loading = true
		try {
			await authClient.signOut()
			// Discard SvelteKit's cached load results so page.data.user
			// reflects the now-cleared session before navigation.
			await invalidateAll()
			await goto('/')
		} finally {
			// Reset loading unconditionally. If this component stays
			// mounted (e.g. used on a page rather than in the root layout),
			// the button would stay disabled indefinitely without this.
			loading = false
		}
	}
</script>

<button class="btn" onclick={handleLogout} disabled={loading}>
	{loading ? 'Signing out…' : 'Sign out'}
</button>

<style>
	.btn {
		height: 2rem;
		padding: 0 0.75rem;
		background: transparent;
		color: hsl(240 10% 3.9%);
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.375rem;
		font-size: 0.8125rem;
		font-weight: 500;
		cursor: pointer;
		transition:
			background 0.15s,
			border-color 0.15s;
	}

	.btn:hover:not(:disabled) {
		background: hsl(240 4.8% 95.9%);
		border-color: hsl(240 5.9% 80%);
	}

	.btn:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}
</style>

authClient.signOut() llama a POST /api/auth/sign-out, que elimina el registro de sesión de la base de datos y limpia la cookie. Eso completa la parte del servidor. invalidateAll() maneja la parte del cliente: descarta la caché de funciones load de SvelteKit y activa una re-ejecución. La re-ejecución lee null de locals.user a través del hook, lo retorna a través de la función load del layout, y la cadena reactiva actualiza todo lo que está aguas abajo.

Paso 14 — Conectar locals.user al Contexto

El paso final hace que locals.user esté disponible para tu árbol de componentes. La función de carga del servidor del layout lee desde locals y devuelve el usuario para que forme parte de page.data — accesible para el componente del layout y todas las páginas debajo de él.

// src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ locals }) => {
	// locals.user was set by the hook in Step 9.
	// Returning it here makes it available as page.data.user
	// to the layout component and all pages.
	return {
		user: locals.user
	}
}

El componente del layout recibe page.data.user y necesita hacerlo disponible para el resto del árbol de componentes. El enfoque más simple es leer page.data.user directamente en cualquier componente — pero esto acopla cada componente a page.data y hace más difícil cambiar la fuente de autenticación más adelante. La API de contexto de Svelte es una mejor opción: establece el usuario una vez en el layout raíz, y cualquier componente en cualquier lugar del árbol puede leerlo sin prop drilling.

Aquí hay una configuración de contexto mínima pero completa que funciona tal como está:

// src/lib/auth/context.svelte.ts

import { getContext, setContext } from 'svelte'
import type { User } from '$lib/server/auth.js'

const AUTH_KEY = Symbol('auth')

interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
}

// Accept a getter function rather than a static value.
// The context object is created once and set once — it never gets replaced.
// Because the getters call getUser() on every read, they always reflect
// the current page.data.user without any $effect or manual synchronisation.
// When invalidateAll() causes the layout load to re-run, page.data.user
// updates, and every component reading auth.user or auth.isAuthenticated
// picks up the new value automatically on the next render.
function createAuthContext(getUser: () => User | null): AuthContext {
	return {
		get user() {
			return getUser()
		},
		get isAuthenticated() {
			return getUser() !== null
		}
	}
}

export function setAuthContext(getUser: () => User | null) {
	return setContext(AUTH_KEY, createAuthContext(getUser))
}

export function getAuthContext(): AuthContext {
	return getContext<AuthContext>(AUTH_KEY)
}

Establece el contexto una vez en el layout raíz, luego incluye un componente Nav que lo lee para mostrar el estado de autenticación:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { page } from '$app/state'
	import { setAuthContext } from '$lib/auth/context.svelte.js'
	import Nav from '$lib/components/Nav.svelte'

	// Pass a getter so the context always reads the current page.data.user.
	// The context object is created once and never replaced — components
	// holding a reference to it via getAuthContext() see updates immediately
	// after invalidateAll() causes the layout load to re-run.
	setAuthContext(() => page.data.user)

	let { children } = $props()
</script>

<Nav />

<main class="main">
	{@render children?.()}
</main>

<style>
	:global(*, *::before, *::after) {
		box-sizing: border-box;
	}

	:global(body) {
		margin: 0;
		background: hsl(0 0% 98%);
		color: hsl(240 10% 3.9%);
		font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
		-webkit-font-smoothing: antialiased;
	}

	:global(a) {
		color: inherit;
	}

	.main {
		max-width: 1200px;
		margin: 0 auto;
		padding: 2rem 1.5rem;
	}
</style>

Nav llama a getAuthContext() para leer el usuario actual y renderiza controles de inicio o cierre de sesión según corresponda. El botón de logout llama a authClient.signOut() seguido de invalidateAll() — el mismo patrón del Paso 13 — para que el contexto se actualice inmediatamente sin una recarga completa de la página:

<!-- src/lib/components/Nav.svelte -->
<script lang="ts">
	import { goto, invalidateAll } from '$app/navigation'
	import { authClient } from '$lib/client/auth.js'
	import { getAuthContext } from '$lib/auth/context.svelte.js'

	const auth = getAuthContext()

	let loading = $state(false)

	async function handleLogout() {
		loading = true
		try {
			await authClient.signOut()
			await invalidateAll()
			await goto('/')
		} finally {
			// Nav lives in the root layout and never unmounts, so loading
			// state persists across navigations. Reset it unconditionally
			// once the full logout sequence completes or fails.
			loading = false
		}
	}
</script>

<header class="header">
	<nav class="nav">
		<a class="brand" href="/">MyApp</a>

		<div class="links">
			{#if auth.isAuthenticated}
				<a class="nav-link" href="/dashboard">Dashboard</a>
				<span class="user-name">{auth.user?.name}</span>
				<button class="btn-outline" onclick={handleLogout} disabled={loading}>
					{loading ? 'Signing out…' : 'Sign out'}
				</button>
			{:else}
				<a class="nav-link" href="/login">Sign in</a>
				<a class="btn-primary" href="/register">Create account</a>
			{/if}
		</div>
	</nav>
</header>

<style>
	.header {
		position: sticky;
		top: 0;
		z-index: 50;
		background: hsl(0 0% 100% / 0.95);
		backdrop-filter: blur(8px);
		border-bottom: 1px solid hsl(240 5.9% 90%);
	}

	.nav {
		max-width: 1200px;
		margin: 0 auto;
		padding: 0 1.5rem;
		height: 3.5rem;
		display: flex;
		align-items: center;
		justify-content: space-between;
	}

	.brand {
		font-size: 1rem;
		font-weight: 600;
		color: hsl(240 10% 3.9%);
		text-decoration: none;
		letter-spacing: -0.01em;
	}

	.links {
		display: flex;
		align-items: center;
		gap: 0.5rem;
	}

	.nav-link {
		padding: 0 0.5rem;
		height: 2rem;
		display: flex;
		align-items: center;
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		text-decoration: none;
		border-radius: 0.375rem;
		transition:
			color 0.15s,
			background 0.15s;
	}

	.nav-link:hover {
		color: hsl(240 10% 3.9%);
		background: hsl(240 4.8% 95.9%);
	}

	.user-name {
		padding: 0 0.5rem;
		font-size: 0.875rem;
		color: hsl(240 10% 3.9%);
		font-weight: 500;
	}

	.btn-primary {
		height: 2rem;
		padding: 0 0.875rem;
		background: hsl(240 5.9% 10%);
		color: hsl(0 0% 98%);
		border-radius: 0.375rem;
		font-size: 0.8125rem;
		font-weight: 500;
		text-decoration: none;
		display: flex;
		align-items: center;
		transition: background 0.15s;
	}

	.btn-primary:hover {
		background: hsl(240 5.9% 20%);
	}

	.btn-outline {
		height: 2rem;
		padding: 0 0.75rem;
		background: transparent;
		color: hsl(240 10% 3.9%);
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.375rem;
		font-size: 0.8125rem;
		font-weight: 500;
		cursor: pointer;
		transition:
			background 0.15s,
			border-color 0.15s;
	}

	.btn-outline:hover:not(:disabled) {
		background: hsl(240 4.8% 95.9%);
		border-color: hsl(240 5.9% 80%);
	}

	.btn-outline:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}
</style>

Con esto en su lugar puedes verificar el flujo completo de autenticación en un solo lugar: inicia sesión en /login, observa cómo el nav cambia al estado autenticado mostrando el nombre del usuario, luego cierra sesión y observa cómo revierte — todo sin recargar la página.

Cuando el usuario cierra sesión, invalidateAll() del Paso 13 vuelve a ejecutar la carga del servidor del layout, page.data.user se convierte en null, y el $state reactivo dentro del contexto propaga ese cambio a cada componente que lee auth.user o auth.isAuthenticated — sin necesidad de sincronización manual.

Esta versión mínima cubre las necesidades más comunes. El artículo complementario Arquitectura de Autenticación con Contexto extiende esta base con verificación de permisos basada en roles, patrones multi-tenant, y la justificación completa de por qué el contexto es el mecanismo de distribución correcto para el estado de autenticación en SvelteKit.

Paso 15 — Construir la Página del Dashboard

El dashboard es una página protegida que lee el usuario autenticado desde locals a través de la carga del servidor y lo muestra. También es el destino de redirección después del inicio de sesión y el registro.

// src/routes/dashboard/+page.server.ts

import { redirect } from '@sveltejs/kit'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	return { user: locals.user }
}

<!-- src/routes/dashboard/+page.svelte -->
<script lang="ts">
	import type { PageData } from './$types'

	let { data }: { data: PageData } = $props()
</script>

<div class="page">
	<div class="header">
		<div>
			<h1 class="title">Dashboard</h1>
			<p class="subtitle">Welcome back, {data.user.name}.</p>
		</div>
	</div>

	<div class="grid">
		<div class="card">
			<div class="card-header">
				<span class="card-label">Account</span>
			</div>
			<div class="card-body">
				<div class="field">
					<span class="field-label">Name</span>
					<span class="field-value">{data.user.name}</span>
				</div>
				<div class="field">
					<span class="field-label">Email</span>
					<span class="field-value">{data.user.email}</span>
				</div>
				<div class="field">
					<span class="field-label">User ID</span>
					<span class="field-value mono">{data.user.id}</span>
				</div>
				<div class="field">
					<span class="field-label">Email verified</span>
					<span class="badge {data.user.emailVerified ? 'badge-success' : 'badge-warning'}">
						{data.user.emailVerified ? 'Verified' : 'Not verified'}
					</span>
				</div>
			</div>
		</div>

		<div class="card">
			<div class="card-header">
				<span class="card-label">Session</span>
			</div>
			<div class="card-body">
				<div class="field">
					<span class="field-label">Status</span>
					<span class="badge badge-success">Active</span>
				</div>
				<div class="field">
					<span class="field-label">Member since</span>
					<span class="field-value">
						{new Date(data.user.createdAt).toLocaleDateString('en-GB', {
							day: 'numeric',
							month: 'long',
							year: 'numeric'
						})}
					</span>
				</div>
			</div>
		</div>
	</div>
</div>

<style>
	.page {
		max-width: 800px;
	}

	.header {
		margin-bottom: 2rem;
	}

	.title {
		font-size: 1.5rem;
		font-weight: 600;
		color: hsl(240 10% 3.9%);
		margin: 0 0 0.25rem;
	}

	.subtitle {
		font-size: 0.875rem;
		color: hsl(240 3.8% 46.1%);
		margin: 0;
	}

	.grid {
		display: grid;
		grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
		gap: 1rem;
	}

	.card {
		background: hsl(0 0% 100%);
		border: 1px solid hsl(240 5.9% 90%);
		border-radius: 0.5rem;
		overflow: hidden;
	}

	.card-header {
		padding: 1rem 1.25rem 0.75rem;
		border-bottom: 1px solid hsl(240 5.9% 90%);
	}

	.card-label {
		font-size: 0.8125rem;
		font-weight: 600;
		color: hsl(240 10% 3.9%);
		text-transform: uppercase;
		letter-spacing: 0.04em;
	}

	.card-body {
		padding: 1rem 1.25rem;
		display: flex;
		flex-direction: column;
		gap: 0.875rem;
	}

	.field {
		display: flex;
		justify-content: space-between;
		align-items: center;
		gap: 1rem;
	}

	.field-label {
		font-size: 0.8125rem;
		color: hsl(240 3.8% 46.1%);
		flex-shrink: 0;
	}

	.field-value {
		font-size: 0.8125rem;
		color: hsl(240 10% 3.9%);
		font-weight: 500;
		text-align: right;
		word-break: break-all;
	}

	.mono {
		font-family: 'SF Mono', 'Fira Code', monospace;
		font-size: 0.75rem;
		color: hsl(240 3.8% 46.1%);
	}

	.badge {
		display: inline-flex;
		align-items: center;
		height: 1.375rem;
		padding: 0 0.5rem;
		border-radius: 9999px;
		font-size: 0.75rem;
		font-weight: 500;
	}

	.badge-success {
		background: hsl(142 76% 95%);
		color: hsl(142 72% 29%);
	}

	.badge-warning {
		background: hsl(48 96% 93%);
		color: hsl(32 95% 35%);
	}
</style>

La carga del servidor redirige a los visitantes no autenticados a /login antes de que se renderice cualquier HTML. La página en sí solo recibe datos que llegaron a través de locals.user — validados en el servidor en cada solicitud por el hook.

Probando el Flujo Completo

Con los 15 pasos completos, verifica que todo funcione en este orden:

Inicia el servidor de desarrollo: pnpm dev
Abre http://localhost:5173/register y crea una cuenta
Deberías ser redirigido a /dashboard y el nav debería mostrar tu nombre y un botón de cierre de sesión
Haz clic en cerrar sesión — el nav debería volver a los enlaces de inicio de sesión y registro inmediatamente
Abre http://localhost:5173/login e inicia sesión con las credenciales que acabas de registrar
Deberías estar de vuelta en el estado autenticado

El error más común en este punto es ir a /login antes de haberse registrado, lo que produce User not found en los logs del servidor. No hay usuarios semilla — la base de datos comienza vacía y cada cuenta debe crearse a través de /register primero.

Errores Comunes y Anti-Patrones

Ejecutar el CLI Antes de que Exista auth.ts

El CLI lee auth.ts para determinar qué plugins están activos y qué tablas necesitan. Ejecutarlo antes de que el Paso 4 esté completo produce No configuration file found.

# ❌ auth.ts does not exist yet -CLI cannot determine the schema.
npx @better-auth/cli generate --output schema.sql

# ✅ Complete Step 4 first, then generate.
npx @better-auth/cli generate --config src/lib/server/auth.ts --output schema.sql

Importar la Instancia del Servidor de Auth en Código del Navegador

// ❌ auth.ts holds a database connection.
//    That connection does not exist in the browser.
//    SvelteKit will refuse to build this.
import { auth } from '$lib/server/auth.js'

// ✅ Use the browser client from Step 10.
import { authClient } from '$lib/client/auth.js'

Llamar a getSession Nuevamente Dentro de las Funciones Load

// ❌ The hook already validated this session for this exact request.
//    This runs a redundant database query on every page load.
export const load: PageServerLoad = async ({ request }) => {
	const session = await auth.api.getSession({ headers: request.headers })
	if (!session) redirect(303, '/login')
	return { user: session.user }
}

// ✅ The hook already did this work. Read from locals.
export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) redirect(303, '/login')
	return { user: locals.user }
}

Olvidar invalidateAll Después del Inicio o Cierre de Sesión

La carga del servidor del layout se ejecuta una vez cuando la página carga. Después de cualquier cambio en el estado de autenticación, el resultado en caché todavía contiene el valor del usuario anterior hasta que le indiques a SvelteKit que lo descarte. Esto aplica tanto al inicio como al cierre de sesión.

// ❌ The cookie is set, but page.data.user is still null from before
//    sign-in. The dashboard sees the unauthenticated state.
async function handleSignIn() {
	await authClient.signIn.email({ email, password })
	goto('/dashboard')
}

// ✅ Invalidate first so the layout load re-runs and picks up locals.user.
async function handleSignIn() {
	await authClient.signIn.email({ email, password })
	await invalidateAll()
	goto('/dashboard')
}

// ❌ The cookie is cleared, but page.data.user is still the cached
//    authenticated value. The nav stays stuck showing the user as signed in.
async function handleLogout() {
	await authClient.signOut()
	goto('/')
}

// ✅ Same fix — invalidate before navigating.
async function handleLogout() {
	await authClient.signOut()
	await invalidateAll()
	goto('/')
}

Usar localStorage como Almacén de Sesión

La cookie de sesión es HttpOnly y JavaScript no puede leerla, y eso es intencional. Los datos del usuario solo deben llegar al código del navegador a través de una función load del servidor, lo que significa que fueron validados por el hook antes de salir del servidor.

// ❌ Any script on the page can read localStorage.
//    Svelte 5 note: $effect replaces onMount for reactive side-effects,
//    but localStorage is the wrong store regardless of which lifecycle you use.
let user = $state(null)
$effect(() => {
	const stored = localStorage.getItem('user')
	if (stored) user = JSON.parse(stored)
})

// ✅ Read from page.data — it came from a server load function
//    validated by the hook before it left the server.
import { page } from '$app/state'
let user = $derived(page.data.user)

Consideraciones de Rendimiento y Escalabilidad

auth.api.getSession se ejecuta en cada solicitud que pasa por el hook. Para SQLite en un único servidor, esto es una búsqueda indexada contra una base de datos en proceso, típicamente bien por debajo de un milisegundo. Hay dos situaciones de escalado que vale la pena conocer antes de necesitarlas.

Ir más allá de un único servidor. SQLite es un archivo en disco. Si ejecutas múltiples procesos de servidor, escalado horizontal, funciones serverless, cada proceso tiene su propia copia y las sesiones escritas en uno son invisibles para los demás. Cambia a una base de datos compartida a través de su adaptador. El cambio es el campo database en auth.ts y la configuración de conexión en db.ts. El hook, el cliente y la UI no cambian.

Cortocircuitar para rutas públicas de alto tráfico. Si tienes rutas que nunca requieren autenticación y sirven tráfico muy alto, puedes omitir la búsqueda de sesión para ellas:

// src/hooks.server.ts

import { auth } from '$lib/server/auth.js'
import type { Handle } from '@sveltejs/kit'

const PUBLIC_PATHS = new Set(['/', '/about', '/pricing', '/blog'])

export const handle: Handle = async ({ event, resolve }) => {
	if (PUBLIC_PATHS.has(event.url.pathname)) {
		event.locals.user = null
		event.locals.session = null
		return resolve(event)
	}

	const session = await auth.api.getSession({
		headers: event.request.headers
	})

	event.locals.user = session?.user ?? null
	event.locals.session = session?.session ?? null

	return resolve(event)
}

Agrega esto solo después de haber medido que la búsqueda de sesión es realmente un cuello de botella. Para la mayoría de las aplicaciones no lo es.

Cuándo NO Usar Este Patrón

better-auth con email/contraseña es una base sólida, pero no es la opción correcta para todas las situaciones.

Si tus usuarios se autentican a través de un proveedor de identidad externo, Google Workspace, GitHub, un sistema SAML empresarial, puede que no necesites contraseñas locales en absoluto. better-auth soporta proveedores OAuth como plugins adicionales agregados al array plugins en el Paso 4. Los usuarios se autentican contra el proveedor externo; tu base de datos solo almacena la sesión resultante. El hook, el cliente y el cableado del contexto de este artículo permanecen sin cambios.

Si estás construyendo una SPA puramente del lado del cliente sin servidor SvelteKit (adapter-static, sin rutas de servidor), la autenticación basada en cookies de sesión no aplica. Validarías tokens en un servidor API separado y almacenarías el access token en memoria en el cliente, no en localStorage.

Si necesitas autorización compleja — seguridad a nivel de fila, control de acceso basado en atributos, árboles de permisos multi-tenant — la interfaz del contexto del Paso 14 es el punto de extensión correcto, pero este artículo solo conecta el usuario. Lee Arquitectura de Autenticación con Contexto para un tratamiento completo de los permisos basados en roles construidos sobre la misma base.

Conclusión

Los quince pasos de este artículo siguen un orden de dependencia estricto: cada paso crea algo de lo que depende el siguiente. Primero los paquetes, luego las variables de entorno, luego la conexión a la base de datos, luego la configuración de auth (que el CLI lee para generar el esquema), luego el esquema en sí, luego las rutas y hooks que lo usan, luego el cliente del navegador, luego la UI, luego el puente de contexto que conecta todo al árbol de componentes.

Cuando la secuencia es correcta, cada pieza encaja en la siguiente sin fricción. La capa de base de datos es un único punto de sustitución. El hook son tres líneas. El cliente del navegador es una llamada a factory. La UI es el manejo de formularios ordinario de Svelte 5. Ninguno de estos requiere novedad, todos usan las herramientas que SvelteKit ya provee.

Puntos Clave

Instala better-auth y better-sqlite3 como dependencias, y @types/better-sqlite3 como dependencia de desarrollo. No instales @better-auth/cli como dependencia, ya que arrastra Prisma a través de la resolución de peers de pnpm.

Ejecuta pnpm approve-builds better-sqlite3 inmediatamente después de la instalación. better-sqlite3 compila un binario nativo y no funcionará hasta que la compilación sea aprobada.

Crea src/lib/server/auth.ts antes de ejecutar el CLI. El CLI lee la configuración para determinar el esquema. Ejecútalo como npx @better-auth/cli generate --config src/lib/server/auth.ts --output schema.sql.

Declara locals.user y locals.session en src/app.d.ts antes de escribir hooks.server.ts. TypeScript necesita la declaración ambient antes de aceptar las asignaciones.

sveltekitCookies(getRequestEvent) no es opcional, y debe ser el último plugin en el array plugins. Sin él, las cookies de sesión se descartan silenciosamente y el inicio de sesión parece fallar sin ningún mensaje de error. Sin getRequestEvent, obtienes un error de TypeScript y el mismo fallo silencioso de cookies en tiempo de ejecución.

El hook se ejecuta una vez por solicitud y popula locals. Cada función load en esa solicitud lee desde locals, nunca llames a getSession una segunda vez dentro de una función load.

Llama a invalidateAll() después del logout antes de navegar. Sin ello, SvelteKit sirve los resultados de carga en caché y la UI queda atascada mostrando al usuario como autenticado.

createAuthContext() no importa better-auth. La capa de contexto y la biblioteca de auth están deliberadamente desacopladas en el límite User | null, cualquiera de los dos lados puede reemplazarse sin tocar el otro.

Lectura Adicional

Documentación de better-auth - referencia completa de plugins, configuración de OAuth y todos los adaptadores de base de datos disponibles
Documentación de hooks de SvelteKit - la API completa de handle y cómo componer múltiples hooks con sequence()
Documentación de better-sqlite3 - API sincrónica de SQLite, modo WAL y orientación de rendimiento