Um Guia para Iniciantes sobre Remote Functions no SvelteKit

Você construiu aplicações SvelteKit com endpoints +server.ts e form actions. Eles funcionam, mas você está escrevendo código repetitivo: analisando corpos de requisição, validando entradas manualmente e mantendo definições de tipo separadas para cliente e servidor. As Remote Functions do SvelteKit oferecem uma abordagem diferente—chamadas de servidor type-safe sem a cerimônia dos endpoints de API tradicionais.

Este guia explica o que são remote functions, quando usar cada tipo e as compensações que você deve entender antes de adotá-las.

O Que São Remote Functions do SvelteKit?

Remote functions permitem que você escreva código do lado do servidor que os clientes chamam como funções regulares. Nos bastidores, o SvelteKit compila estas em endpoints HTTP e gera wrappers fetch para o cliente. Você obtém type safety de ponta a ponta sem construir ou manter rotas de API tradicionais.

Pense nisso como o SvelteKit cuidando da infraestrutura entre seu frontend e backend. Você escreve uma função em um arquivo .remote.ts, e o SvelteKit cuida da serialização, geração de endpoints e inferência de tipos.

Se você quiser a referência oficial, este recurso está documentado na documentação do SvelteKit em Remote Functions: https://kit.svelte.dev/docs/remote-functions

Habilitando o Recurso Experimental

Remote functions requerem opt-in explícito via kit.experimental.remoteFunctions no seu svelte.config.js:

const config = {
  kit: {
    experimental: {
      remoteFunctions: true
    }
  }
};

export default config;

Se você quiser usar await diretamente em componentes Svelte, você também precisará habilitar o suporte async experimental do Svelte separadamente. Isso não é obrigatório—remote functions funcionam sem ele—mas simplifica o código dos componentes.

Os Quatro Tipos de Server Functions do SvelteKit

Remote functions vêm em quatro variações, cada uma projetada para casos de uso específicos.

Query: Buscando Dados Dinâmicos

Use query ao ler dados de bancos de dados, APIs ou qualquer recurso do servidor. Queries podem executar durante a renderização do componente e são deduplicadas e agrupadas dentro do mesmo ciclo de vida de renderização.

import { query } from '$app/server';
import { db } from '$lib/db';
import { posts } from '$lib/schema';

export const getPosts = query(async () => {
  return await db.select().from(posts);
});

Para cenários críticos de performance, query.batch agrupa múltiplas chamadas simultâneas em uma única requisição—resolvendo o problema n+1 sem otimização manual.

Form: Mutações de Dados com Progressive Enhancement

A função form lida com submissão de entrada do usuário. Sua principal vantagem é o progressive enhancement. Formulários funcionam sem JavaScript, voltando à submissão tradicional quando necessário.

Espalhe o objeto retornado no seu elemento <form>, e o SvelteKit lida automaticamente com submissões aprimoradas e não aprimoradas.

Command: Mutações Flexíveis

command funciona como form, mas não está vinculado a elementos de formulário. Use-o para cliques de botão, ações de arrastar e soltar, ou qualquer mutação acionada fora de um contexto de formulário.

Diferente de forms, commands requerem JavaScript. Escolha form quando progressive enhancement importa. Escolha command quando você precisa de flexibilidade.

Prerender: Dados Estáticos em Tempo de Build

prerender busca dados durante o build, não em tempo de execução. Os resultados são armazenados em cache no momento do build e servidos via cache da plataforma ou CDN. Use isso para configuração, conteúdo de CMS que muda apenas no deployment, ou quaisquer dados que não precisam de atualizações em tempo real.

Restrição importante: você não pode usar query em páginas totalmente pré-renderizadas, já que queries são inerentemente dinâmicas.

Segurança: Cada Remote Function É um Endpoint Público

Isso é crítico entender: cada remote function se torna um endpoint HTTP que qualquer pessoa pode chamar. Validação de entrada não é opcional—é essencial.

O SvelteKit espera que você valide argumentos usando bibliotecas Standard Schema como Zod ou Valibot (a iniciativa “Standard Schema” está documentada em https://standardschema.dev):

import { query } from '$app/server';
import * as v from 'valibot';
import { db } from '$lib/db';
import { posts } from '$lib/schema';

const Params = v.object({
  slug: v.string()
});

export const getPost = query(Params, async ({ slug }) => {
  return await db.select().from(posts).where(eq(posts.slug, slug));
});

Sem validação, atacantes podem enviar dados arbitrários para seus endpoints. O SvelteKit normalmente retorna erros de nível 400 para falhas de validação, evitando vazamento de informações.

Mantenha o SvelteKit Atualizado

Versões anteriores tinham vulnerabilidades de segurança afetando remote functions, incluindo problemas de DoS. Mantenha-se atualizado com os lançamentos, especialmente enquanto o recurso permanece experimental (a partir do SvelteKit 2.x).

Compensações a Considerar

Remote functions reduzem código repetitivo, mas não são mágica. Considere estas restrições:

• Localização do arquivo importa: arquivos .remote.ts vão em qualquer lugar em src, exceto src/lib/server
• Cache de prerender: Cache do navegador e CDN significa dados desatualizados até o próximo deployment
• Status experimental: APIs podem mudar e bugs são esperados

Remote functions funcionam melhor quando você quer comunicação cliente-servidor type-safe sem manter definições de endpoint separadas. Elas não são uma substituição para todo arquivo +server.ts—fluxos de autenticação complexos ou manipuladores de webhook de terceiros ainda podem justificar endpoints tradicionais.

Quando Usar Cada Tipo de Função

Conclusão

Remote Functions do SvelteKit simplificam a fronteira entre código cliente e servidor. Elas eliminam a manutenção manual de endpoints enquanto fornecem validação integrada e type safety. Comece com query para busca de dados, adicione form para entrada do usuário, e recorra a command ou prerender quando esses padrões específicos se adequarem às suas necessidades.

O recurso é experimental—espere mudanças. Mas para desenvolvedores SvelteKit cansados de código repetitivo de endpoints, remote functions oferecem uma alternativa convincente que vale a pena explorar.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.