Construindo Endpoints de API

Toda rota no SvelteKit que possui um arquivo +page.svelte é uma rota de página — ela renderiza HTML para humanos. Mas algumas URLs não devem retornar HTML. Elas devem retornar JSON para um aplicativo móvel, dados binários para download de arquivos, ou uma resposta 204 vazia para confirmação de webhook. É para isso que serve o +server.js (ou +server.ts).

Um arquivo +server.js em um diretório de rota faz com que aquela URL responda a métodos HTTP diretamente, sem renderizar HTML. O mesmo roteamento baseado no sistema de arquivos se aplica: src/routes/api/posts/+server.ts se torna o handler para GET /api/posts, POST /api/posts, e assim por diante. Você exporta uma função nomeada para cada método HTTP que deseja tratar.

Isso significa que o SvelteKit é um framework full-stack completo. Sua API backend fica em src/routes/api/, suas páginas ficam em src/routes/, e elas compartilham código de src/lib/. Uma base de código, um deploy, sem configuração de CORS entre seu frontend e backend.

A capacidade de co-locar endpoints de API com seu frontend é um ganho significativo de produtividade — sem repositório backend separado, sem cabeçalhos CORS para configurar, tipos TypeScript compartilhados entre cliente e servidor. A restrição: arquivos +server.js devem conter lógica de handler HTTP, não lógica de negócios. Mantenha a lógica de domínio em $lib/server/, onde pode ser compartilhada e testada de forma independente.

Quando Usar `+server.js`

Use +server.js quando precisar:

Retornar dados JSON — Para requisições fetch no lado do cliente
Construir uma API REST — Operações CRUD para seus dados
Tratar webhooks — Receber dados de serviços externos
Gerar arquivos — PDFs, imagens, exportações CSV
Fazer proxy de requisições — Encaminhar requisições para APIs externas

Handlers de Método HTTP

Em um arquivo +server.js, você exporta funções nomeadas de acordo com os métodos HTTP:

// src/routes/api/posts/+server.ts
import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

// Handle GET requests
export const GET: RequestHandler = async () => {
	const posts = await db.posts.findMany()
	return json(posts)
}

// Handle POST requests
export const POST: RequestHandler = async ({ request }) => {
	const data = await request.json()
	const post = await db.posts.create({ data })
	return json(post, { status: 201 })
}

// Handle PUT requests
export const PUT: RequestHandler = async ({ request }) => {
	const data = await request.json()
	const post = await db.posts.update({
		where: { id: data.id },
		data
	})
	return json(post)
}

// Handle DELETE requests
export const DELETE: RequestHandler = async ({ request }) => {
	const { id } = await request.json()
	await db.posts.delete({ where: { id } })
	return new Response(null, { status: 204 })
}

O Helper `json`

Endpoints de API devem retornar objetos Response, não valores simples. O helper json é um wrapper de conveniência que serializa seus dados com JSON.stringify, define o cabeçalho Content-Type: application/json automaticamente e encapsula o resultado em um Response adequado. Você poderia construir isso manualmente, mas json() resolve em uma linha:

import { json } from '@sveltejs/kit'

// Equivalent to: new Response(JSON.stringify({ message: 'Hello' }), {
//   headers: { 'Content-Type': 'application/json' }
// })
return json({ message: 'Hello' })

// With a custom status code
return json({ error: 'Not found' }, { status: 404 })

// With additional headers
return json(data, {
	status: 200,
	headers: {
		'Cache-Control': 'max-age=3600'
	}
})

Quando você precisa retornar algo que não é JSON — um arquivo, texto simples, um stream — você constrói o Response diretamente, como mostrado na seção "Retornando Outros Tipos de Resposta" abaixo.

Parâmetros do Handler de Requisição

Cada handler recebe parâmetros úteis:

export const POST: RequestHandler = async ({
	request, // The Request object
	params, // Route parameters
	url, // URL object with searchParams
	cookies, // Read/write cookies
	locals, // Data from hooks
	fetch, // Server-side fetch
	platform, // Platform-specific context
	setHeaders // Set response headers
}) => {
	// Your handler logic
}

Lendo Dados da Requisição

Corpo JSON

export const POST: RequestHandler = async ({ request }) => {
	const data = await request.json()
	// data is the parsed JSON body
	return json({ received: data })
}

Dados de Formulário

export const POST: RequestHandler = async ({ request }) => {
	const formData = await request.formData()
	const name = formData.get('name')
	const email = formData.get('email')

	return json({ name, email })
}

Parâmetros de Busca da URL

export const GET: RequestHandler = async ({ url }) => {
	const page = Number(url.searchParams.get('page')) || 1
	const limit = Number(url.searchParams.get('limit')) || 10

	const posts = await db.posts.findMany({
		skip: (page - 1) * limit,
		take: limit
	})

	return json({ posts, page, limit })
}

Rotas de API Dinâmicas

Assim como as páginas, as rotas de API podem ter parâmetros dinâmicos:

// src/routes/api/posts/[id]/+server.ts
import { json, error } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async ({ params }) => {
	const post = await db.posts.findUnique({
		where: { id: params.id }
	})

	if (!post) {
		error(404, 'Post not found')
	}

	return json(post)
}

export const DELETE: RequestHandler = async ({ params }) => {
	await db.posts.delete({
		where: { id: params.id }
	})

	return new Response(null, { status: 204 })
}

Tratamento de Erros

Use o helper error para retornar respostas de erro:

import { json, error } from '@sveltejs/kit'

export const GET: RequestHandler = async ({ params }) => {
	const post = await db.posts.findUnique({
		where: { id: params.id }
	})

	if (!post) {
		error(404, 'Post not found')
	}

	return json(post)
}

Para mais controle, retorne um Response diretamente:

export const POST: RequestHandler = async ({ request }) => {
	try {
		const data = await request.json()
		// ... process data
		return json({ success: true })
	} catch (e) {
		return json({ error: 'Invalid JSON' }, { status: 400 })
	}
}

Autenticação em Rotas de API

Acesse o usuário a partir de locals (definido pelos seus hooks):

// src/routes/api/user/profile/+server.ts
import { json, error } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async ({ locals }) => {
	if (!locals.user) {
		error(401, 'Unauthorized')
	}

	return json({
		id: locals.user.id,
		name: locals.user.name,
		email: locals.user.email
	})
}

export const PUT: RequestHandler = async ({ locals, request }) => {
	if (!locals.user) {
		error(401, 'Unauthorized')
	}

	const data = await request.json()

	const updated = await db.users.update({
		where: { id: locals.user.id },
		data: {
			name: data.name,
			bio: data.bio
		}
	})

	return json(updated)
}

Retornando Outros Tipos de Resposta

Texto Simples

export const GET: RequestHandler = async () => {
	return new Response('Hello, World!', {
		headers: {
			'Content-Type': 'text/plain'
		}
	})
}

HTML

export const GET: RequestHandler = async () => {
	const html = `
		<!DOCTYPE html>
		<html>
			<body><h1>Hello</h1></body>
		</html>
	`
	return new Response(html, {
		headers: {
			'Content-Type': 'text/html'
		}
	})
}

Download de Arquivos

export const GET: RequestHandler = async () => {
	const csv = 'name,email\nJohn,john@example.com'

	return new Response(csv, {
		headers: {
			'Content-Type': 'text/csv',
			'Content-Disposition': 'attachment; filename="users.csv"'
		}
	})
}

Respostas em Streaming

export const GET: RequestHandler = async () => {
	const stream = new ReadableStream({
		start(controller) {
			controller.enqueue('Hello ')
			setTimeout(() => {
				controller.enqueue('World!')
				controller.close()
			}, 1000)
		}
	})

	return new Response(stream, {
		headers: {
			'Content-Type': 'text/plain'
		}
	})
}

Consumindo Rotas de API

A Partir de Funções Load

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/posts')
	return {
		posts: await response.json()
	}
}

A Partir de Componentes

<script lang="ts">
	let posts = $state([])

	async function loadPosts() {
		const response = await fetch('/api/posts')
		posts = await response.json()
	}

	async function createPost(title: string) {
		const response = await fetch('/api/posts', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({ title })
		})

		if (response.ok) {
			const newPost = await response.json()
			posts = [...posts, newPost]
		}
	}
</script>

Configuração de CORS

Para APIs consumidas por domínios externos:

export const GET: RequestHandler = async () => {
	return json(data, {
		headers: {
			'Access-Control-Allow-Origin': '*',
			'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
		}
	})
}

// Handle preflight requests
export const OPTIONS: RequestHandler = async () => {
	return new Response(null, {
		headers: {
			'Access-Control-Allow-Origin': '*',
			'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
			'Access-Control-Allow-Headers': 'Content-Type, Authorization'
		}
	})
}

Quando Usar `+server.js` vs Form Actions

Tanto +server.js quanto form actions (em +page.server.js) lidam com mutações no servidor. A distinção se resume a quem está chamando e qual interface você deseja.

Form actions são a escolha certa quando a mutação vem de um formulário HTML no seu app SvelteKit. Elas funcionam com JavaScript desabilitado, suportam aprimoramento progressivo com use:enhance, e invalidam e re-renderizam automaticamente a página atual. Elas são um padrão SvelteKit de primeira classe para interações baseadas em formulários HTML.

+server.js é a escolha certa quando você precisa de um endpoint HTTP de propósito geral: apps mobile chamando sua API, webhooks do Stripe ou GitHub, chamadas programáticas de fetch a partir de componentes, ou qualquer consumidor que não seja um envio de formulário HTML.

Use `+server.js` quando...	Use Form Actions quando...
Clientes externos precisam chamar a URL	O chamador é sempre seu app SvelteKit
Retornando respostas não-HTML (JSON...)	Processando um envio de formulário HTML
Construindo uma API REST ou RPC	Você quer aprimoramento progressivo
Lidando com webhooks de serviços externos	Você quer revalidação automática de página

Padrões Comuns

// src/routes/api/newsletter/+server.ts
import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

export const POST: RequestHandler = async ({ request }) => {
	const { email } = await request.json()

	// Validate email
	if (!email || !email.includes('@')) {
		return json({ error: 'Invalid email' }, { status: 400 })
	}

	// Check if already subscribed
	const existing = await db.subscribers.findUnique({
		where: { email }
	})

	if (existing) {
		return json({ error: 'Already subscribed' }, { status: 409 })
	}

	// Subscribe
	await db.subscribers.create({
		data: { email }
	})

	return json({ success: true }, { status: 201 })
}

Endpoint de Health Check

// src/routes/api/health/+server.ts
import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async () => {
	const dbHealthy = await checkDatabase()

	return json(
		{
			status: dbHealthy ? 'healthy' : 'degraded',
			timestamp: new Date().toISOString(),
			version: '1.0.0'
		},
		{
			status: dbHealthy ? 200 : 503
		}
	)
}

Conclusão

O arquivo +server.js transforma rotas SvelteKit de mecanismos puramente de renderização de páginas em endpoints de API completos, permitindo que você construa APIs RESTful, webhooks e serviços de dados diretamente dentro da estrutura de rotas da sua aplicação. Ao exportar handlers de métodos HTTP em vez de componentes de página, esses arquivos criam endpoints que retornam JSON, arquivos ou qualquer tipo de resposta que você precisar.

Essa co-localização da lógica de API com o código frontend elimina a divisão tradicional frontend/backend para muitas aplicações, tornando o desenvolvimento full-stack algo fluido e natural.

Dominar o +server.js significa entender toda a superfície da Web Fetch API — construir objetos Response, definir headers, lidar com streams e implementar a semântica HTTP adequada. Combinado com acesso a cookies para autenticação, params para roteamento dinâmico e a capacidade de lançar erros que se propagam pelo sistema de tratamento de erros do SvelteKit, os endpoints de servidor fornecem tudo o que é necessário para construir APIs de nível produtivo.

Seja construindo endpoints internos de busca de dados, APIs REST públicas ou receptores de webhooks, o padrão +server.js torna a lógica de backend uma extensão natural do seu sistema de roteamento.

Pontos Principais

+server.js cria endpoints de API exportando handlers de métodos HTTP (GET, POST, PUT, DELETE) em vez de renderizar páginas
Retorne objetos Response usando helpers como json() para respostas JSON, text() para texto simples, ou new Response() para tipos customizados
Acesse parâmetros de rota via objeto params, parâmetros de busca de URL via url.searchParams, e cookies para autenticação
Use error() para erros estruturados que fluem pelo tratamento de erros do SvelteKit com códigos de status HTTP adequados
Co-localize a lógica de API com o frontend — posicione endpoints ao lado de páginas na sua estrutura de rotas para funcionalidades relacionadas
Suporte a qualquer tipo de resposta — JSON, texto, arquivos, streams ou tipos MIME customizados via o construtor Response
Perfeito para webhooks e integrações — receba requisições POST de serviços externos, valide assinaturas, processe dados no servidor
Acesse contexto exclusivo do servidor via locals para dados com escopo de requisição, cookies para gerenciamento de sessão, e platform para o ambiente de implantação

Veja Também

Documentação Oficial do SvelteKit - +server.js
Tipo RequestHandler - Assinatura de função para handlers
Helper json() - Utilitário de resposta JSON
Web Fetch API - Objetos Response e Request padrão
Padrões de Rotas de API - Design de API REST com SvelteKit
Respostas em Streaming - Eventos enviados pelo servidor e dados em streaming