Construcción de Endpoints de API

Cada ruta en SvelteKit que tiene un archivo +page.svelte es una ruta de página — renderiza HTML para las personas. Pero algunas URLs no deberían retornar HTML. Deberían retornar JSON para una aplicación móvil, datos binarios para una descarga de archivos, o una respuesta 204 vacía para el reconocimiento de un webhook. Para eso existe +server.js (o +server.ts).

Un archivo +server.js en un directorio de rutas hace que esa URL responda a métodos HTTP directamente, sin renderizar HTML. Se aplica el mismo enrutamiento basado en el sistema de archivos: src/routes/api/posts/+server.ts se convierte en el manejador para GET /api/posts, POST /api/posts, y así sucesivamente. Exportas una función con nombre por cada método HTTP que quieras manejar.

Esto significa que SvelteKit es un framework full-stack completo. Tu API backend vive en src/routes/api/, tus páginas viven en src/routes/, y comparten código de src/lib/. Un solo codebase, un solo despliegue, sin configuración de CORS entre tu frontend y backend.

La posibilidad de co-ubicar los endpoints de API con tu frontend es una ganancia de productividad significativa — sin repositorio backend separado, sin encabezados CORS que configurar, tipos de TypeScript compartidos entre cliente y servidor. La restricción: los archivos +server.js deben contener lógica de manejadores HTTP, no lógica de negocio. Mantén la lógica de dominio en $lib/server/ donde puede ser compartida y probada de forma independiente.

Cuándo Usar `+server.js`

Usa +server.js cuando necesites:

Retornar datos JSON — Para solicitudes fetch del lado del cliente
Construir una API REST — Operaciones CRUD para tus datos
Manejar webhooks — Recibir datos de servicios externos
Generar archivos — PDFs, imágenes, exportaciones CSV
Hacer proxy de solicitudes — Reenviar solicitudes a APIs externas

Manejadores de Métodos HTTP

En un archivo +server.js, exportas funciones con el nombre de los 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 })
}

El Helper `json`

Los endpoints de API deben retornar objetos Response, no valores simples. El helper json es un wrapper conveniente que serializa tus datos con JSON.stringify, establece el encabezado Content-Type: application/json automáticamente, y envuelve el resultado en un Response apropiado. Podrías construir esto manualmente, pero json() lo hace en una sola línea:

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

Cuando necesites retornar algo que no sea JSON — un archivo, texto plano, un stream — construyes el Response directamente, como se muestra en la sección "Retornando Otros Tipos de Respuesta" a continuación.

Parámetros de los Manejadores de Solicitudes

Cada manejador recibe parámetros útiles:

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
}

Lectura de Datos de la Solicitud

Cuerpo JSON

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

Datos de Formulario

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 Búsqueda de la 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 })
}

Rutas de API Dinámicas

Al igual que las páginas, las rutas de API pueden tener 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 })
}

Manejo de Errores

Usa el helper error para retornar respuestas de error:

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 mayor control, retorna un Response directamente:

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

Autenticación en Rutas de API

Accede al usuario desde locals (establecido por tus 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 Otros Tipos de Respuesta

Texto Plano

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

Descarga de Archivos

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"'
		}
	})
}

Respuestas en 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'
		}
	})
}

Consumir Rutas de API

Desde Funciones 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()
	}
}

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

Configuración de CORS

Para APIs consumidas por dominios 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'
		}
	})
}

Cuándo Usar `+server.js` vs Acciones de Formulario

Tanto +server.js como las acciones de formulario (en +page.server.js) manejan mutaciones en el servidor. La distinción radica en quién las llama y qué interfaz deseas.

Las acciones de formulario son la opción correcta cuando la mutación proviene de un formulario HTML en tu aplicación SvelteKit. Funcionan sin JavaScript habilitado, soportan mejora progresiva con use:enhance, e invalidan y vuelven a renderizar la página actual automáticamente. Son un patrón de primera clase en SvelteKit para interacciones basadas en formularios HTML.

+server.js es la opción correcta cuando necesitas un endpoint HTTP de propósito general: aplicaciones móviles que llaman a tu API, webhooks de Stripe o GitHub, llamadas fetch programáticas desde componentes, o cualquier consumidor que no sea el envío de un formulario HTML.

Usa `+server.js` cuando...	Usa Acciones de Formulario cuando...
Clientes externos necesitan llamar al URL	El que llama siempre es tu aplicación SvelteKit
Retornas respuestas no-HTML (JSON...)	Manejas el envío de un formulario HTML
Construyes una API REST o RPC	Quieres mejora progresiva
Manejas webhooks de servicios externos	Quieres revalidación automática de página

Patrones Comunes

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

Conclusión

El archivo +server.js transforma las rutas de SvelteKit de simples mecanismos de renderizado de páginas en endpoints de API completos, permitiéndote construir APIs RESTful, webhooks y servicios de datos directamente dentro de la estructura de rutas de tu aplicación. Al exportar manejadores de métodos HTTP en lugar de componentes de página, estos archivos crean endpoints que retornan JSON, archivos o cualquier tipo de respuesta que necesites.

Esta co-ubicación de la lógica de API junto al código frontend elimina la separación tradicional frontend/backend para muchas aplicaciones, haciendo que el desarrollo full-stack se sienta fluido y natural.

Dominar +server.js implica entender toda la superficie de la Web Fetch API: construir objetos Response, establecer encabezados, manejar streams e implementar una semántica HTTP adecuada. Combinado con acceso a cookies para autenticación, params para enrutamiento dinámico, y la capacidad de lanzar errores que se propagan a través del sistema de manejo de errores de SvelteKit, los endpoints de servidor proveen todo lo necesario para construir APIs de nivel productivo.

Ya sea que estés construyendo endpoints internos de obtención de datos, APIs REST públicas o receptores de webhooks, el patrón +server.js hace que la lógica de backend sea una extensión natural de tu sistema de enrutamiento.

Puntos Clave

+server.js crea endpoints de API exportando manejadores de métodos HTTP (GET, POST, PUT, DELETE) en lugar de renderizar páginas
Retorna objetos Response usando helpers como json() para respuestas JSON, text() para texto plano, o new Response() para tipos personalizados
Accede a parámetros de ruta mediante el objeto params, parámetros de búsqueda en la URL mediante url.searchParams, y cookies para autenticación
Usa error() para errores estructurados que fluyen a través del manejo de errores de SvelteKit con códigos de estado HTTP apropiados
Co-ubica la lógica de API con el frontend - coloca los endpoints junto a las páginas en tu estructura de rutas para funcionalidades relacionadas
Soporta cualquier tipo de respuesta - JSON, texto, archivos, streams o tipos MIME personalizados mediante el constructor Response
Ideal para webhooks e integraciones - recibe solicitudes POST de servicios externos, valida firmas y procesa datos del lado del servidor
Accede al contexto exclusivo del servidor mediante locals para datos con alcance de solicitud, cookies para gestión de sesiones, y platform para el entorno de despliegue

Ver También

Documentación Oficial de SvelteKit - +server.js
Tipo RequestHandler - Firma de función para manejadores
Helper json() - Utilidad para respuestas JSON
Web Fetch API - Objetos estándar Response y Request
Patrones de Rutas de API - Diseño de API REST con SvelteKit
Respuestas en Streaming - Eventos enviados por el servidor y datos en streaming