Por que better-auth para SvelteKit

Todo aplicativo web sério eventualmente enfrenta o desafio da autenticação. O ecossistema tem opções de sobra, como Lucia, Auth.js, Clerk e Supabase Auth, onde cada uma traz sua própria opinião sobre onde as sessões ficam armazenadas, como o schema do banco de dados se parece e quão fortemente ela se acopla ao seu framework. O better-auth adota uma posição refrescantemente prática: é ciente do framework, mas não está preso a ele, gera seu schema como SQL simples via CLI, expõe uma API TypeScript limpa e inclui um plugin para SvelteKit que conecta cookies ao modelo de resposta do SvelteKit corretamente.

Uma coisa que o better-auth não exige é um ORM. Ele funciona diretamente com clientes de banco de dados brutos e gerencia suas próprias consultas internamente. Você fornece uma conexão; ele cuida de tudo relacionado à autenticação a partir daí. Suas próprias consultas de domínio continuam sendo suas para escrever da maneira que preferir.

Este artigo usa better-sqlite3 como driver de banco de dados concreto — ele requer configuração zero, roda em processo e é a maneira mais rápida de ter uma configuração funcional diante de você. A camada de banco de dados é deliberadamente uma zona de substituição: se você usa PostgreSQL, MySQL ou Turso, apenas essa seção muda. Todas as outras partes — o hook, o cliente, a UI, a conexão de contexto — são idênticas independentemente do banco de dados utilizado.

Ao final, você terá um sistema de autenticação completo e funcional construído nesta sequência exata:

Passo	O que faz	Arquivo(s)
1	Instala pacotes e aprova o build nativo	—
2	Define variáveis de ambiente	`.env`
3	Abre a conexão com o banco de dados	`src/lib/server/db.ts`
4	Configura o better-auth	`src/lib/server/auth.ts`
5	Declara os locals do TypeScript	`src/app.d.ts`
6	Gera o schema do banco de dados	`npx @better-auth/cli`
7	Aplica o schema	`sqlite3` ou `db.exec()`
8	Monta a rota de API catch-all	`src/routes/api/auth/[...all]/+server.ts`
9	Valida sessões no hook	`src/hooks.server.ts`
10	Cria o cliente do navegador	`src/lib/client/auth.ts`
11	Constrói a página de login	`src/routes/login/+page.svelte`
12	Constrói a página de cadastro	`src/routes/register/+page.svelte`
13	Constrói o botão de logout	`src/lib/components/LogoutButton.svelte`
14	Conecta `locals.user` ao contexto	`src/routes/+layout.server.ts` + `+layout.svelte`
15	Constrói a página do dashboard	`src/routes/dashboard/+page.svelte`

Cada passo cria algo do qual o próximo passo depende. A sequência importa — em particular, auth.ts deve existir antes de você executar o CLI, e app.d.ts deve declarar os locals antes de o hook atribuir valores a eles. Siga os passos em ordem e você não encontrará erros evitáveis.

Uma vez que locals.user esteja preenchido, ele se encaixa diretamente no padrão createAuthContext() abordado em Arquitetura de Autenticação com Context. Aquele artigo explica por que o contexto é o mecanismo de distribuição correto. Este explica como alimentá-lo com dados reais de sessão.

O Espaço do Problema

Implementar sua própria autenticação do zero é uma das maneiras mais confiáveis de introduzir vulnerabilidades de segurança. Hash de senhas, geração de tokens de sessão, proteção CSRF, atributos de cookie (HttpOnly, Secure, SameSite), rotação de tokens — cada um é uma peça sutil e estrutural. Errar qualquer uma delas pode expor silenciosamente seus usuários.

Ao mesmo tempo, muitas soluções de autenticação "totalmente gerenciadas" tiram o controle de suas mãos exatamente nos momentos errados. Elas armazenam sessões em sua nuvem, impõem seu schema e tornam complicado inspecionar um registro de sessão no seu próprio banco de dados ou executar uma migration específica.

O better-auth mira no meio-termo: você é dono do banco de dados, você é dono do schema, você é dono da implantação. A biblioteca cuida da criptografia e do ciclo de vida da sessão. Seu trabalho é conectá-la ao modelo de requisição/resposta do SvelteKit, o que acaba sendo surpreendentemente mínimo quando você vê as peças individuais.

Passo 1 — Instalar Pacotes

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

Essa é a instalação completa. Dois pacotes, nada mais.

Após a conclusão da instalação, o pnpm exibirá um aviso:

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

Isso é esperado e é bloqueante — você deve resolver isso antes de continuar. better-sqlite3 é um addon nativo do Node.js que compila um pequeno binário C++ durante a instalação. Sem esse binário, o pacote simplesmente não funciona. A política de segurança do pnpm bloqueia scripts de build de dependências por padrão até que você os aprove explicitamente:

pnpm approve-builds better-sqlite3

O pnpm grava a aprovação no .npmrc do seu projeto para que persista em instalações futuras e seja seguro para commitar no repositório. Executar pnpm approve-builds sem argumento abre um seletor interativo caso você prefira revisar todas as aprovações pendentes de uma vez.

Um pacote que especificamente não deve ser adicionado aqui: @better-auth/cli. O CLI é necessário no Passo 6 para gerar o schema do banco de dados, mas não deve ser instalado como dependência do projeto. O @better-auth/cli lista @prisma/client como peer opcional, e a configuração auto-install-peers do pnpm resolve peers opcionais de forma agressiva por padrão, o que significa que instalar o CLI silenciosamente puxa o Prisma para o seu projeto.

Use npx em vez disso, que busca e executa o CLI em um local temporário isolado sem tocar no seu node_modules. Quando você executar o comando npx no Passo 6 pela primeira vez, verá um prompt como este:

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

Isso é normal — digite y e pressione Enter para continuar. O npx faz cache do download, então o prompt aparece apenas uma vez.

Passo 2 — Variáveis de Ambiente

O better-auth precisa de dois valores em tempo de execução que pertencem ao seu arquivo .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 é o valor mais sensível do ponto de vista de segurança nesta configuração. O better-auth o utiliza para assinar tokens de sessão criptograficamente — qualquer pessoa que tenha o segredo pode forjar um token de sessão válido sem tocar no banco de dados. Trate-o como uma senha root do banco de dados: nunca o commite, rotacione-o se vazar e injete-o a partir de um gerenciador de segredos em produção.

BETTER_AUTH_URL informa ao better-auth onde o aplicativo reside para que ele possa construir URLs absolutas. E-mails de redefinição de senha, URIs de redirecionamento OAuth e qualquer outra URL que o better-auth precise construir derivam desse valor.

PUBLIC_BASE_URL serve ao mesmo propósito para o cliente do navegador. O prefixo PUBLIC_ é a convenção do SvelteKit para variáveis de ambiente que são seguras para incluir nos bundles do navegador. Variáveis sem esse prefixo são exclusivas do servidor e não podem ser importadas em código do cliente.

O SvelteKit expõe variáveis exclusivas do servidor através de $env/static/private e variáveis públicas através de $env/static/public. O static em ambas significa que os valores são incorporados em tempo de build; o bundler se recusa a incluir variáveis private em qualquer código que possa chegar ao navegador.

Passo 3 — Abrir a Conexão com o Banco de Dados

Crie um módulo que abre uma única conexão better-sqlite3 para o processo do servidor. Este é o único arquivo específico de banco de dados em toda a integração — tudo o mais é o mesmo independentemente do banco de dados utilizado.

// 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 que o modo WAL

WAL (Write-Ahead Logging) permite leituras concorrentes durante escritas. O better-auth realiza uma busca de sessão em cada requisição autenticada, portanto, sem WAL uma operação de escrita — um login, uma atualização de sessão — bloquearia brevemente todas as leituras.

Uma coisa importante saber: db.pragma('journal_mode = WAL') não é executado na inicialização do servidor. O SvelteKit carrega módulos do servidor de forma lazy, então db.ts só é importado na primeira vez que uma requisição precisar dele — quando hooks.server.ts for executado para uma requisição recebida. Isso significa que local.db-wal e local.db-shm não aparecerão no disco até que você abra uma página no navegador pela primeira vez após iniciar o servidor de desenvolvimento. Esse é o comportamento esperado. Executar sqlite3 db/local.db < db/schema.sql sozinho nunca produzirá os arquivos auxiliares — apenas o aplicativo em execução pode fazer isso.

Por que `process.cwd()` em vez de um caminho relativo

Uma string relativa simples como 'db/local.db' resolve contra qualquer diretório do qual o processo Node foi iniciado. Quando o SvelteKit executa o servidor de desenvolvimento, esse é sempre a raiz do projeto, então funciona. Mas quando o CLI do better-auth importa este arquivo via npx, ele pode usar um diretório de trabalho diferente e silenciosamente colocar o arquivo de banco de dados no lugar errado. process.cwd() está sempre ancorado na raiz do projeto quando invocado através de scripts pnpm ou npx executados a partir do diretório do projeto, então join(process.cwd(), 'db/local.db') é seguro em ambos os contextos.

Adicione os arquivos de banco de dados ao .gitignore — o diretório em si continua sendo rastreado já que schema.sql também reside lá:

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

Este é o único arquivo que muda quando você migra para PostgreSQL, MySQL ou Turso. O better-auth vem com adaptadores oficiais para cada um. Substitua a linha database: db em auth.ts (Passo 4) pelo adaptador apropriado — todo o resto deste artigo permanece igual.

Banco de Dados	Driver	Como passar para betterAuth()
SQLite	`better-sqlite3`	`database: db` - passe diretamente, sem adaptador necessário
Turso / libSQL	`@libsql/client`	`database: libsqlAdapter(client)` de `better-auth/adapters/libsql`
PostgreSQL	`pg` / `postgres`	`database: pgAdapter(pool)` de `better-auth/adapters/pg`
MySQL	`mysql2`	`database: mysqlAdapter(conn)` de `better-auth/adapters/mysql`
MongoDB	`mongodb`	`database: mongodbAdapter(client)` de `better-auth/adapters/mongodb`

Todos os passos após o Passo 3 são idênticos independentemente do adaptador escolhido. A configuração completa para cada alternativa comum está abaixo — iniciantes no SQLite podem pular para o Passo 4.

PostgreSQL com `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 na Edge

Turso é um serviço SQLite distribuído. Mesmo dialeto SQL que o better-sqlite3, mas funciona como banco de dados remoto gerenciado ou como réplica incorporada — adequado para implantações na edge e configurações multi-região.

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 desenvolvimento local sem uma conta Turso, aponte para um arquivo local em vez disso:

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

MySQL com `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"

Passo 4 — Configurar o better-auth

Agora que existe uma conexão com o banco de dados, crie a configuração central de autenticação. Todas as outras partes da integração ou alimentam esse objeto ou leem a partir dele.

O better-auth não possui estratégia de autenticação embutida — nada é habilitado por padrão. Você opta por cada estratégia explicitamente através do array plugins. Isso mantém o bundle enxuto: a biblioteca só inclui código para o que você realmente usa. A configuração base define as primitivas de segurança (segredo, URL base, conexão com o banco de dados, manipulação de cookies do SvelteKit) e então você adiciona estratégias de autenticação por cima.

Configuração Base

Comece com a conexão mínima que toda configuração requer, independentemente da estratégia de autenticação escolhida:

// 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) é o único plugin obrigatório. O modelo de resposta do SvelteKit exige que os cookies sejam escritos através de event.cookies.set(). Se o better-auth escrever um cabeçalho Set-Cookie diretamente no objeto Response — que é o comportamento HTTP padrão fora do SvelteKit —, o SvelteKit o descartará silenciosamente. O cookie de sessão nunca chega ao navegador, o login parece concluir com sucesso no servidor, mas o usuário está não autenticado na próxima requisição, sem nenhuma mensagem de erro para explicar o motivo.

getRequestEvent é importado de $app/server e fornece ao plugin acesso ao RequestEvent ativo do SvelteKit no momento da chamada — especificamente o objeto cookies de que ele precisa. Esse argumento passou a ser obrigatório em uma versão posterior do better-auth; chamar sveltekitCookies() sem ele é tanto um erro do TypeScript quanto uma falha silenciosa em tempo de execução.

Mais uma restrição fácil de ignorar: sveltekitCookies deve sempre ser o último plugin no array. O better-auth executa os plugins em ordem, e sveltekitCookies intercepta operações de cookie dos plugins que rodaram antes dele. Se outro plugin for listado depois dele, as escritas de cookie desse plugin acontecem após o ponto de interceptação e são descartadas silenciosamente.

Escolhendo uma Estratégia de Autenticação

Com a configuração base no lugar, adicione um ou mais plugins de estratégia de autenticação ao array plugins. Cada estratégia é uma importação independente — adicione apenas o que seu aplicativo precisa.

E-mail e senha é o ponto de partida mais comum. emailAndPassword é uma opção de nível superior em betterAuth(), não um plugin. Adicione-o junto à configuração 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 (login social) autentica via um provedor externo — GitHub, Google, Discord e outros. Nenhuma senha local é armazenada. Configure os provedores via o objeto de nível superior socialProviders e então adicione as credenciais ao .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 envia uma URL de login único para o e-mail do usuário — sem senha armazenada. Ele fica no array plugins (antes de sveltekitCookies) e precisa de um transporte de e-mail:

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 estratégias é simples, pois emailAndPassword e socialProviders são ambos opções de nível superior e coexistem livremente. O restante deste artigo usa e-mail/senha como exemplo concreto. Tudo a partir do Passo 5 em diante é idêntico independentemente da estratégia escolhida.

Passo 5 — Declarar Locals do TypeScript

Antes de escrever o hook que atribui valores a event.locals, você precisa informar ao TypeScript o que event.locals contém. O SvelteKit usa uma declaração de ambiente global para isso em src/app.d.ts — sem ela, o TypeScript não sabe que as propriedades user e session existem, e o hook produzirá erros 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 {}

Os tipos User e Session vêm das exportações inferidas que você criou no Passo 4. Isso mantém tudo sincronizado — se o better-auth alterar o formato do usuário ao adicionar um plugin, a mudança fluirá automaticamente pelo tipo inferido para app.d.ts e para cada função load que lê locals.user.

Passo 6 — Gerar o Schema do Banco de Dados

O better-auth precisa de quatro tabelas: user, session, account e verification. A CLI as gera como SQL puro com base na sua configuração em auth.ts. Este é o momento correto para executá-la — a configuração precisa existir primeiro, razão pela qual ela foi o Passo 4 e este é o Passo 6.

Execute a CLI com npx. O flag --config é obrigatório porque a CLI procura por auth.ts na raiz do projeto por padrão e não encontrará o seu dentro de src/lib/server/ sem ser informada sobre onde procurar:

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

O flag -p no mkdir faz o comando ser uma operação nula se db/ já existir, então é seguro executá-lo a qualquer momento. Se esta for sua primeira vez executando o comando, o npx solicitará que você confirme o download; digite y para prosseguir. A CLI não é instalada no seu projeto; ela é executada a partir de um cache temporário. Consulte o Passo 1 para entender por que npx é preferível a instalar a CLI como dependência.

O schema.sql gerado para SQLite tem esta aparência:

-- 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
);

A tabela account é onde ficam as senhas com hash ao usar o plugin emailAndPassword. A tabela verification lida com tokens de verificação de e-mail e tokens de redefinição de senha. O better-auth gerencia todas as leituras e gravações nessas tabelas — você nunca as consulta diretamente.

O schema gerado reflete sua configuração atual de plugins. Adicionar `twoFactor()` requer uma tabela `twoFactor`. Adicionar `organization()` requer várias novas tabelas. Re-execute a CLI após alterar sua lista de plugins e, em seguida, aplique o novo SQL.

Para garantir que a versão da CLI corresponda à versão instalada do better-auth, especifique-a explicitamente:

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

Substitua 1.x.x pela sua versão instalada; verifique em node_modules/better-auth/package.json. Versões incompatíveis podem gerar um schema que não corresponde ao que a biblioteca espera em tempo de execução.

Passo 7 — Aplicar o Schema

Aplique o SQL gerado ao seu banco de dados SQLite:

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

db/local.db será criado caso ainda não exista. A cláusula IF NOT EXISTS em cada instrução CREATE TABLE torna este comando seguro para re-execução — aplicar o schema em um banco de dados que já possui as tabelas é uma operação nula.

Se você quiser que o banco de dados inicialize automaticamente na inicialização — útil para que um clone recém-criado funcione sem etapas manuais —, você pode aplicar o schema a partir de db.ts:

// 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)

Ambas as abordagens funcionam. O comando sqlite3 é explícito e fácil de auditar; a abordagem de inicialização automática é conveniente durante o desenvolvimento. Em produção com um banco de dados real, normalmente você aplicaria mudanças de schema por meio de um gerenciador de migrações adequado com arquivos versionados.

Reiniciando o Banco de Dados

Durante o desenvolvimento, você ocasionalmente precisará de um estado limpo — para testar o registro com um banco de dados novo, limpar contas de teste ou recuperar-se de um estado corrompido. Exclua todos os três arquivos SQLite e re-aplique o schema:

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

Os arquivos auxiliares do WAL (local.db-wal e local.db-shm) devem ser excluídos junto com o arquivo principal. Deixá-los como órfãos causa erros no SQLite na próxima inicialização porque eles fazem referência a um log de transações de um arquivo de banco de dados que não existe mais.

Se você estiver usando a abordagem de inicialização automática (db.exec(schema) em db.ts), ignore o segundo comando — basta excluir os arquivos e reiniciar o servidor de desenvolvimento. O schema é re-aplicado automaticamente na próxima inicialização.

Passo 8 — Montar a Rota de API Catch-All

O better-auth gerencia todos os seus próprios endpoints — sign-in, sign-out, sign-up, atualização de sessão, verificação de e-mail — por meio de um único manipulador de requisições. Monte-o na localização 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)
}

Se o TypeScript reportar Cannot find module './$types', a geração de tipos do SvelteKit ainda não foi executada. O SvelteKit gera os arquivos $types automaticamente quando o servidor de desenvolvimento inicia ou quando você executa o sync explicitamente:

pnpm exec svelte-kit sync

Execute isso uma vez — o erro desaparece e RequestHandler é resolvido corretamente. O servidor de desenvolvimento executa o sync a cada inicialização, portanto, em desenvolvimento normal, você só encontrará esse problema ao criar arquivos antes de iniciar o servidor pela primeira vez.

O segmento dinâmico [...all] captura todos os caminhos sob /api/auth/. Quando o navegador envia POST /api/auth/sign-in/email, o SvelteKit redireciona para este arquivo e auth.handler o despacha para a lógica de sign-in por e-mail/senha. Quando o navegador envia POST /api/auth/sign-out, o mesmo manipulador o redireciona para o sign-out. Você nunca escreve rotas individuais para operações de autenticação individuais — o manipulador cobre todas elas, incluindo quaisquer operações adicionadas por plugins futuros.

O manipulador retorna um Response padrão. O plugin sveltekitCookies() do Passo 4 intercepta a escrita do cookie de sessão dentro do manipulador e a redireciona por event.cookies.set() antes que a resposta seja retornada, razão pela qual esse plugin era necessário.

Passo 9 — Validar Sessões no Hook

O hook é onde cada requisição obtém sua identidade autenticada. Ele é executado antes de qualquer função load ou action de formulário na sua aplicação, o que significa que, no momento em que suas páginas são executadas, event.locals.user já está resolvido.

// 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 lê o cookie de sessão dos cabeçalhos da requisição, valida o token criptograficamente usando BETTER_AUTH_SECRET, verifica que a sessão não expirou e retorna os objetos completos de sessão e usuário — ou null se qualquer validação falhar. Todo o processo é local: seu arquivo SQLite, seu segredo, sem chamadas de rede externas.

event.locals tem escopo por requisição. O SvelteKit cria um objeto locals novo para cada requisição recebida e o descarta após o envio da resposta. Não há estado mutável compartilhado entre requisições, nenhum risco de dados de um usuário vazarem para a requisição de outro, e nenhuma contaminação de SSR.

Com locals.user preenchido pelo hook, proteger uma rota dentro de uma função load é uma única verificação:

// 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 }
}

Passo 10 — Criar o Cliente do Navegador

O objeto auth de src/lib/server/auth.ts não pode ser importado em código do navegador — ele mantém uma conexão com o banco de dados que não existe no navegador, e o SvelteKit impõe o limite de $lib/server/ em tempo de build. Para operações no lado do navegador, o better-auth fornece um cliente tipado separado que se comunica com o servidor via 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

Nenhum plugin é necessário no cliente para e-mail/senha. Os métodos signIn.email() e signUp.email() estão disponíveis por padrão porque emailAndPassword foi habilitado no servidor no Passo 4. Plugins do cliente só são necessários para plugins do servidor que estendem a superfície da API — por exemplo, adicionar twoFactor() no servidor implica adicionar twoFactorClient() ao array de plugins do cliente aqui, para que os métodos de dois fatores estejam disponíveis e corretamente tipados.

Colocar o cliente em src/lib/client/ em vez de src/lib/server/ é intencional. O limite de server/ é imposto em tempo de build — qualquer tentativa de importar um módulo de $lib/server/ em código do navegador é um erro de compilação. O cliente apenas realiza chamadas fetch e pertence fora desse limite.

Com toda a infraestrutura no lugar, o sign-in é um tratamento de formulário direto com Svelte 5:

<!-- 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() envia as credenciais para POST /api/auth/sign-in/email. A rota catch-all do Passo 8 a trata. O better-auth valida as credenciais em relação à senha com hash na tabela account, cria um registro de sessão na tabela session, e o plugin sveltekitCookies() escreve o cookie de sessão HttpOnly antes que a resposta saia do servidor. A partir deste ponto, cada requisição feita pelo navegador inclui esse cookie, e o hook do Passo 9 o resolve em locals.user.

Passo 12 — Construir a Página de Cadastro

O cadastro segue o mesmo padrão que o sign-in, com um campo adicional para o nome:

<!-- 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>

O better-auth lida com o hashing de senha internamente — você nunca vê ou armazena senhas em texto puro. O plugin emailAndPassword() usa bcrypt. Um registro user é gravado na tabela user, um registro account correspondente com a senha com hash é gravado na tabela account, e uma sessão é criada na mesma resposta. No momento em que goto('/dashboard') é executado, o usuário já está autenticado.

Passo 13 — Construir o Botão de Logout

O logout limpa a sessão no lado do servidor e, em seguida, ressincroniza o estado do lado do cliente. A chamada invalidateAll() é fácil de esquecer e causa um bug sutil quando 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() chama POST /api/auth/sign-out, que exclui o registro de sessão do banco de dados e limpa o cookie. Isso conclui o lado do servidor. invalidateAll() cuida do lado do cliente — ele descarta o cache das funções load do SvelteKit e aciona uma nova execução. A nova execução lê null de locals.user através do hook, retorna-o através da função load do layout, e a cadeia reativa atualiza tudo que está abaixo dela.

Passo 14 — Conectar locals.user ao Context

O passo final torna locals.user disponível para a árvore de componentes. A função de carregamento do servidor do layout lê de locals e retorna o usuário para que ele faça parte de page.data — acessível ao componente de layout e a todas as páginas abaixo dele.

// 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
	}
}

O componente de layout recebe page.data.user e precisa disponibilizá-lo para o restante da árvore de componentes. A abordagem mais simples é ler page.data.user diretamente em qualquer componente — mas isso acopla cada componente a page.data e dificulta a substituição da fonte de autenticação posteriormente. A API de contexto do Svelte é mais adequada: defina o usuário uma vez no layout raiz, e qualquer componente em qualquer lugar da árvore pode lê-lo sem prop drilling.

Aqui está uma configuração de contexto mínima, mas completa, que funciona 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)
}

Defina o contexto uma vez no layout raiz e, em seguida, inclua um componente Nav que o lê para exibir o estado de autenticação:

<!-- 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 chama getAuthContext() para ler o usuário atual e renderiza controles de login ou logout conforme necessário. O botão de logout chama authClient.signOut() seguido de invalidateAll() — o mesmo padrão do Passo 13 — para que o contexto seja atualizado imediatamente sem um recarregamento completo da 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>

Com isso no lugar, você pode verificar o fluxo completo de autenticação em um só lugar: faça login em /login, observe a navegação mudar para o estado autenticado exibindo o nome do usuário, depois saia e observe ela reverter — tudo sem um recarregamento de página.

Quando o usuário faz logout, invalidateAll() do Passo 13 re-executa o carregamento do servidor do layout, page.data.user torna-se null, e o $state reativo dentro do contexto propaga essa mudança para cada componente que lê auth.user ou auth.isAuthenticated — sem necessidade de sincronização manual.

Esta versão mínima cobre as necessidades mais comuns. O artigo complementar Arquitetura de Autenticação com Context estende essa base com verificação de permissões baseada em funções, padrões multi-tenant, e a justificativa completa de por que o contexto é o mecanismo de distribuição correto para o estado de autenticação no SvelteKit.

Passo 15 — Construir a Página do Dashboard

O dashboard é uma página protegida que lê o usuário autenticado de locals via carregamento do servidor e o exibe. Este também é o destino de redirecionamento após o login e o 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>

O carregamento do servidor redireciona visitantes não autenticados para /login antes que qualquer HTML seja renderizado. A página em si só recebe dados que vieram através de locals.user — validados no servidor a cada requisição pelo hook.

Testando o Fluxo Completo

Com todos os 15 passos concluídos, verifique se tudo funciona nesta ordem:

Inicie o servidor de desenvolvimento: pnpm dev
Abra http://localhost:5173/register e crie uma conta
Você deve ser redirecionado para /dashboard e a navegação deve exibir seu nome e um botão de logout
Clique em sair — a navegação deve reverter para os links de login e registro imediatamente
Abra http://localhost:5173/login e faça login com as credenciais que acabou de registrar
Você deve estar de volta ao estado autenticado

O erro mais comum neste ponto é ir para /login antes de fazer qualquer registro, o que produz User not found nos logs do servidor. Não há usuários de seed — o banco de dados começa vazio e toda conta deve ser criada através de /register primeiro.

Erros Comuns e Anti-Padrões

Executar o CLI Antes de auth.ts Existir

O CLI lê auth.ts para determinar quais plugins estão ativos e quais tabelas eles precisam. Executá-lo antes que o Passo 4 esteja completo produz 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 a Instância de Auth do Servidor em Código do 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'

Chamar getSession Novamente Dentro de Funções 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 }
}

O carregamento do servidor do layout é executado uma vez quando a página carrega. Após qualquer mudança de estado de autenticação, o resultado em cache ainda mantém o valor anterior do usuário até que você diga ao SvelteKit para descartá-lo. Isso se aplica tanto ao login quanto ao logout.

// ❌ 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 Armazenamento de Sessão

O cookie de sessão é HttpOnly e o JavaScript não pode lê-lo, e isso é intencional. Os dados do usuário só devem chegar ao código do navegador através de uma função load do servidor, o que significa que foram validados pelo hook antes de sair do 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)

Considerações de Desempenho e Escalabilidade

auth.api.getSession é executado a cada requisição que passa pelo hook. Para SQLite em um único servidor, isso é uma busca indexada em um banco de dados em processo, tipicamente bem abaixo de um milissegundo. Duas situações de escalabilidade valem a pena serem conhecidas antes que você precise delas.

Indo além de um único servidor. SQLite é um arquivo em disco. Se você executar múltiplos processos de servidor, escalabilidade horizontal, funções serverless, cada processo tem sua própria cópia e as sessões gravadas em um são invisíveis para os outros. Mude para um banco de dados compartilhado via seu adaptador. A mudança é o campo database em auth.ts e a configuração da conexão em db.ts. O hook, o cliente e a UI permanecem inalterados.

Curto-circuito para rotas públicas de alto tráfego. Se você tem rotas que nunca requerem autenticação e servem tráfego muito alto, você pode ignorar a busca de sessão para elas:

// 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)
}

Adicione isso apenas depois de medir que a busca de sessão é realmente um gargalo. Para a maioria das aplicações, não é.

Quando NÃO Usar Este Padrão

better-auth com email/senha é uma base sólida, mas não é a escolha certa para todas as situações.

Se seus usuários se autenticam por meio de um provedor de identidade externo, Google Workspace, GitHub, um sistema SAML empresarial, você pode não precisar de senhas locais. better-auth suporta provedores OAuth como plugins adicionais adicionados ao array plugins no Passo 4. Os usuários se autenticam no provedor externo; seu banco de dados armazena apenas a sessão resultante. O hook, o cliente e a configuração de contexto deste artigo permanecem inalterados.

Se você estiver construindo um SPA puramente client-side sem servidor SvelteKit (adapter-static, sem rotas de servidor), a autenticação baseada em cookie de sessão não se aplica. Você validaria tokens em um servidor de API separado e armazenaria o token de acesso na memória no cliente, não em localStorage.

Se você precisar de autorização complexa — segurança em nível de linha, controle de acesso baseado em atributos, árvores de permissão multi-tenant — a interface de contexto do Passo 14 é o ponto de extensão correto, mas este artigo apenas conecta o usuário. Leia Arquitetura de Autenticação com Context para um tratamento completo de permissões baseadas em funções construídas sobre a mesma base.

Conclusão

Os quinze passos deste artigo seguem uma ordem de dependência estrita: cada passo cria algo do qual o próximo passo depende. Pacotes primeiro, depois variáveis de ambiente, depois a conexão com o banco de dados, depois a configuração de autenticação (que o CLI lê para gerar o schema), depois o próprio schema, depois as rotas e hooks que o utilizam, depois o cliente do navegador, depois a UI, depois a ponte de contexto que conecta tudo à árvore de componentes.

Quando a sequência está correta, cada peça se encaixa na próxima sem atrito. A camada de banco de dados é um único ponto de substituição. O hook são três linhas. O cliente do navegador é uma chamada de fábrica. A UI é o tratamento de formulários Svelte 5 comum. Nada disso requer novidade, todos usam as ferramentas que o SvelteKit já fornece.

Principais Aprendizados

Instale better-auth e better-sqlite3 como dependências, e @types/better-sqlite3 como dependência de desenvolvimento. Não instale @better-auth/cli como dependência, ele puxa o Prisma via resolução de peers do pnpm.

Execute pnpm approve-builds better-sqlite3 imediatamente após a instalação. better-sqlite3 compila um binário nativo e não funcionará até que o build seja aprovado.

Crie src/lib/server/auth.ts antes de executar o CLI. O CLI lê a configuração para determinar o schema. Execute-o como npx @better-auth/cli generate --config src/lib/server/auth.ts --output schema.sql.

Declare locals.user e locals.session em src/app.d.ts antes de escrever hooks.server.ts. O TypeScript precisa da declaração ambiente antes de aceitar as atribuições.

sveltekitCookies(getRequestEvent) não é opcional, e deve ser o último plugin no array plugins. Sem ele, os cookies de sessão são descartados silenciosamente e o login parece falhar sem mensagem de erro. Sem getRequestEvent, você recebe um erro do TypeScript e a mesma falha silenciosa de cookie em tempo de execução.

O hook é executado uma vez por requisição e popula locals. Cada função load nessa requisição lê de locals, nunca chame getSession uma segunda vez dentro de uma função load.

Chame invalidateAll() após o logout antes de navegar. Sem isso, o SvelteKit serve os resultados de carregamento em cache e a UI fica travada mostrando o usuário como autenticado.

createAuthContext() não importa better-auth. A camada de contexto e a biblioteca de autenticação são deliberadamente desacopladas na fronteira User | null, qualquer lado pode ser substituído sem tocar no outro.

Leitura Adicional

Documentação do better-auth - referência completa de plugins, configuração de OAuth e todos os adaptadores de banco de dados disponíveis
Documentação de hooks do SvelteKit - a API completa de handle e como compor múltiplos hooks com sequence()
Documentação do better-sqlite3 - API SQLite síncrona, modo WAL e orientações de desempenho