Formulário de captação de leads8 min de leitura
Crie um formulário de leads com qualificação no TanStack Start
Um formulário de leads em TanStack Start: middleware de requisição global para UTMs de primeiro toque, uma server function com Zod e um redirect lançado para o seu agendador.
Registre as tags UTM e o referrer na primeira requisição de página com um middleware de requisição global em src/start.ts e guarde-os num cookie httpOnly. Valide o lead num handler createServerFn com Zod, encaminhe-o com a atribuição para o seu backend de formulários e lance redirect({ href }) para mandar leads qualificados ao seu agendador. Chame a server function via useServerFn para que o redirecionamento seja seguido por você.
A aba TanStack Start do guia principal envia um lead por uma server function e mostra uma frase de agradecimento. Esta página monta a versão de vendas: três perguntas de qualificação validadas no servidor, a campanha que trouxe o visitante e um redirecionamento direto para a sua agenda quando o lead se encaixa.
O que muda no TanStack Start
O Start não tem convenção de middleware baseada em arquivo. Tudo o que deve rodar em toda requisição vai em src/start.ts como middleware de requisição global, que roda antes de SSR, server routes e server functions. É ali que o primeiro toque é registrado.
O detalhe: o Start só instala automaticamente a proteção CSRF para server functions quando src/start.ts não existe. No momento em que você cria o arquivo para a atribuição, essa proteção passa a ser sua e você precisa adicionar createCsrfMiddleware() por conta própria. Esqueça disso e o seu endpoint de leads aceita envios de outros sites.
- Toda requisição passa primeiro pelo middleware CSRF; ele só confere chamadas de server function.
- Num GET ainda sem cookie, firstTouch lê as tags UTM e um referrer externo e os guarda.
- A página renderiza normalmente.
- No envio, useServerFn manda o FormData para a server function.
- O validator o transforma num objeto simples e o handler roda o Zod nele.
- Um lead válido vai ao Ikiform com a atribuição, o fit e o Origin do visitante.
- O handler lança um redirect para o Cal.com ou para a rota de agradecimento; useServerFn o segue. Os erros voltam como dados.
Configuração do projeto
Comece de um projeto TanStack Start com React e instale zod. Coloque a chave secreta no .env como IKIFORM_SECRET_KEY; as server functions a leem de process.env, e ela nunca chega ao bundle do cliente. Não há uma página específica do Start na documentação; enviar a partir de um servidor cobre a chave e o endpoint.
src/
start.ts
lib/lead.ts
routes/
contact-sales.tsx
contact-sales.thanks.tsx
vite.config.ts
.envDefina os campos na aba Fields do formulário, para que o Ikiform rejeite tudo o que não bater, inclusive chaves de atribuição que você não planejou.
| Id do campo | Tipo no Ikiform | Definido por |
|---|---|---|
name, email, company | Text, email, text | O visitante |
company_size | Select, com as opções 1_10, 11_50, 51_200, 201_1000, 1000_plus | O visitante |
budget | Select, com as opções under_10k, 10k_50k, 50k_plus, unsure | O visitante |
timeline | Select, com as opções this_quarter, next_quarter, later, researching | O visitante |
message | Textarea, opcional | O visitante |
utm_source, utm_medium, utm_campaign, referrer, landing_page | Text, opcional | Seu servidor, a partir da primeira visita |
fit | Select, com as opções qualified, nurture | Seu servidor, após a validação |
IKIFORM_SECRET_KEY em variáveis de ambiente só do servidor.Middleware global para o primeiro toque
import { createCsrfMiddleware, createMiddleware, createStart } from "@tanstack/react-start";
import { getCookie, setCookie } from "@tanstack/react-start/server";
const TAGS = ["utm_source", "utm_medium", "utm_campaign"];
const csrf = createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === "serverFn" });
const firstTouch = createMiddleware().server(({ request, next }) => {
if (request.method !== "GET" || getCookie("lead_source")) return next();
const url = new URL(request.url);
const referer = request.headers.get("referer") ?? "";
const from = URL.canParse(referer) ? new URL(referer) : null;
const external = from && from.host !== url.host ? from.href.slice(0, 300) : "";
const source = new URLSearchParams();
for (const tag of TAGS) source.set(tag, url.searchParams.get(tag)?.slice(0, 100) ?? "");
if (external || TAGS.some((tag) => source.get(tag))) {
source.set("referrer", external);
source.set("landing_page", url.pathname.slice(0, 200));
setCookie("lead_source", source.toString(), {
httpOnly: true,
sameSite: "lax",
path: "/",
maxAge: 60 * 60 * 24 * 30,
});
}
return next();
});
export const startInstance = createStart(() => ({
requestMiddleware: [csrf, firstTouch],
}));- O filtro mantém a verificação CSRF nas server functions, como a documentação do Start recomenda para uso global. Ele compara
Sec-Fetch-Site,OriginouReferercom a origem da requisição. firstTouchpula tudo o que não é GET, então os envios de server function nunca mexem no cookie.setCookieegetCookievêm de@tanstack/react-start/servere só rodam no servidor.- Um cookie definido durante uma requisição só fica legível por
getCookiena próxima. Aqui isso não é problema: o lead é enviado numa requisição posterior.
A server function
import { redirect } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getCookie, getRequestHeader } from "@tanstack/react-start/server";
import { z } from "zod";
const LeadSchema = z.object({
name: z.string().trim().min(1, "Tell us who to reply to.").max(120),
email: z.email("Enter a work email we can reply to."),
company: z.string().trim().min(1, "Which company is this for?").max(200),
company_size: z.enum(["1_10", "11_50", "51_200", "201_1000", "1000_plus"], { error: "Pick a company size." }),
budget: z.enum(["under_10k", "10k_50k", "50k_plus", "unsure"], { error: "Pick a budget range." }),
timeline: z.enum(["this_quarter", "next_quarter", "later", "researching"], { error: "Pick a timeline." }),
message: z.string().trim().max(5000).optional(),
_gotcha: z.string().optional(),
});
const SOURCE = ["utm_source", "utm_medium", "utm_campaign", "referrer", "landing_page"];
const FIT = { size: ["1_10"], budget: ["10k_50k", "50k_plus"], timeline: ["this_quarter", "next_quarter"] };
export type LeadResult = { errors: Record<string, string> };
export const submitLead = createServerFn({ method: "POST" })
.validator((data: unknown) => {
if (!(data instanceof FormData)) throw new Error("Expected form data");
return Object.fromEntries([...data].map(([key, value]) => [key, String(value)]));
})
.handler(async ({ data }): Promise<LeadResult> => {
const parsed = LeadSchema.safeParse(data);
if (!parsed.success) {
const { fieldErrors } = z.flattenError(parsed.error);
return { errors: Object.fromEntries(Object.entries(fieldErrors).map(([key, list]) => [key, list?.[0] ?? ""])) };
}
const lead = parsed.data;
const stored = new URLSearchParams(getCookie("lead_source") ?? "");
const qualified =
!FIT.size.includes(lead.company_size) && FIT.budget.includes(lead.budget) && FIT.timeline.includes(lead.timeline);
const origin = getRequestHeader("origin");
const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`,
...(origin ? { Origin: origin } : {}),
},
body: JSON.stringify({
...lead,
...Object.fromEntries(SOURCE.map((key) => [key, stored.get(key) ?? ""])),
fit: qualified ? "qualified" : "nurture",
}),
});
const result = await response.json().catch(() => null);
if (!result?.ok) {
const fields: Record<string, string[]> = result?.error?.fields ?? {};
const errors = Object.fromEntries(Object.entries(fields).map(([key, list]) => [key, list[0] ?? ""]));
return { errors: Object.keys(errors).length ? errors : { form: result?.error?.message ?? "Try again." } };
}
if (!qualified || lead._gotcha) throw redirect({ to: "/contact-sales/thanks" });
throw redirect({ href: `https://cal.com/acme/intro?${new URLSearchParams({ name: lead.name, email: lead.email })}` });
});.validator()só remodela oFormData; o Zod roda no handler comsafeParse, para que os erros de campo voltem como dados em vez de uma exceção que o componente não consegue ler por campo.fité decidido no servidor. Editar o formulário não promove um lead.getRequestHeader("origin")é repassado, porque um fetch no servidor não mandaOrigine o Ikiform detecta por ele os testes gratuitos emlocalhost.redirect({ href })é a forma externa;redirect({ to })fica dentro do app. Os dois são lançados.
A rota
import { createFileRoute } from "@tanstack/react-router";
import { useServerFn } from "@tanstack/react-start";
import { type FormEvent, useState } from "react";
import { submitLead } from "../lib/lead";
export const Route = createFileRoute("/contact-sales")({ component: ContactSales });
const SELECTS = {
company_size: ["Company size", [["1_10", "1 to 10"], ["11_50", "11 to 50"], ["51_200", "51 to 200"], ["201_1000", "201 to 1,000"], ["1000_plus", "More than 1,000"]]],
budget: ["Budget", [["under_10k", "Under $10k"], ["10k_50k", "$10k to $50k"], ["50k_plus", "More than $50k"], ["unsure", "Not sure yet"]]],
timeline: ["When do you want to start?", [["this_quarter", "This quarter"], ["next_quarter", "Next quarter"], ["later", "Later this year"], ["researching", "Researching for now"]]],
} as const;
function ContactSales() {
const send = useServerFn(submitLead);
const [errors, setErrors] = useState<Record<string, string>>({});
const [pending, setPending] = useState(false);
async function onSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
setPending(true);
try {
const result = await send({ data: new FormData(event.currentTarget) });
setErrors(result?.errors ?? {});
} catch {
setErrors({ form: "We couldn't send that. Email sales@example.com instead." });
} finally {
setPending(false);
}
}
const error = (key: string) => (errors[key] ? <p role="alert">{errors[key]}</p> : null);
return (
<form method="post" action={submitLead.url} encType="multipart/form-data" onSubmit={onSubmit}>
<label htmlFor="name">Name</label>
<input id="name" name="name" autoComplete="name" required />
{error("name")}
<label htmlFor="email">Work email</label>
<input id="email" name="email" type="email" autoComplete="email" required />
{error("email")}
<label htmlFor="company">Company</label>
<input id="company" name="company" autoComplete="organization" required />
{error("company")}
{Object.entries(SELECTS).map(([id, [label, options]]) => (
<div key={id}>
<label htmlFor={id}>{label}</label>
<select id={id} name={id} required defaultValue="">
<option value="" disabled>Choose one</option>
{options.map(([value, text]) => (
<option key={value} value={value}>{text}</option>
))}
</select>
{error(id)}
</div>
))}
<label htmlFor="message">Anything we should know?</label>
<textarea id="message" name="message" rows={4} />
<input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
{error("form")}
<button disabled={pending}>{pending ? "Sending" : "Talk to sales"}</button>
</form>
);
}O handler de envio impede o post padrão e chama a server function via useServerFn, que é quem segue um redirect lançado, inclusive para outro site. Como o formulário nunca é resetado, todos os valores ficam no lugar enquanto o visitante corrige um campo.
O atributo action={submitLead.url} é o caminho sem JavaScript. O Start documenta .url para formulários HTML, mas aí o navegador mostra a resposta bruta da server function em vez desta página. Teste com o JavaScript desligado e decida se isso é aceitável, ou coloque um link de e-mail simples para vendas abaixo do formulário.
Honeypot e verificação humana
Um honeypot preenchido ainda é enviado, então o Ikiform o armazena como spam, e o handler o manda para a rota de agradecimento em vez da sua agenda. A chave secreta pula a verificação humana do Ikiform; adicione uma verificação do Turnstile ao handler se bots encontrarem o formulário, seguindo Turnstile num formulário.
Renderização e deploy
As rotas renderizam no servidor por padrão, e o middleware roda em cada uma dessas requisições. Se você pré-renderizar páginas de marketing em arquivos estáticos, a CDN as serve sem rodar o middleware, então a atribuição precisa começar numa página que renderiza a cada requisição.
| Host | O que saber |
|---|---|
| Vercel | Adicione o plugin nitro/vite e faça o deploy. Defina IKIFORM_SECRET_KEY nas variáveis de ambiente do projeto. |
| Netlify | Adicione @netlify/vite-plugin-tanstack-start ao vite.config.ts. Defina a chave nas configurações do site. |
| Cloudflare | Adicione @cloudflare/vite-plugin e faça o deploy com o Wrangler. Guarde a chave com wrangler secret put e ative nodejs_compat para que process.env a tenha. |
Confira se funciona
Envios do servidor de desenvolvimento trazem a origem localhost. O Ikiform não tem plano gratuito. Testar é grátis: um workspace sem plano aceita 50 envios de teste por mês a partir de localhost. Para entrar no ar, escolha o Pro a partir de US$ 6/mês para 500 envios, ou pague uma vez: 10.000 envios por US$ 49 ou 50.000 envios por US$ 149, com créditos que nunca expiram. Veja os preços.
- Rode o servidor de desenvolvimento, abra
/?utm_source=test&utm_campaign=launche confira nas ferramentas de desenvolvedor que o cookielead_sourceé httpOnly. - Em
/contact-sales, escolha Under $10k e deixe Company vazio. O erro da empresa aparece e todos os outros valores continuam. - Envie como lead qualificado: 201 a 1.000 pessoas, $10k a $50k, este trimestre. O navegador vai para o Cal.com com nome e e-mail preenchidos.
- Envie como uma equipe de 1 a 10 pessoas. Você cai em
/contact-sales/thanks. - Abra Submissions no painel e confira
utm_source,landing_pageefit. - Confira a caixa de entrada de cada destinatário das notificações. Cada um recebe um e-mail com os campos, e Reply vai para quem enviou quando o formulário tem um campo
email.
Pegadinhas
| Problema | O que fazer |
|---|---|
403 da sua própria server function depois de adicionar src/start.ts | A verificação CSRF rejeitou a chamada. Requisições de outra origem pública, como atrás de um proxy, precisam de createCsrfMiddleware({ origin }). |
| Envios de outros sites chegam à server function | src/start.ts existe sem createCsrfMiddleware(). Adicione-o, como no exemplo. |
| A página não sai do lugar depois de um envio qualificado | A server function foi chamada diretamente, e não via useServerFn, então nada segue o redirect lançado. |
| Um erro sobre importar código de servidor no cliente | getCookie foi chamado fora de uma server function ou de um middleware. Mantenha-o dentro de .handler() ou .server(). |
422 validation_failed | O envio não corresponde à definição de campos do formulário. error.fields aponta cada campo e o motivo. Faça o name do input bater com o id do campo. |
Perguntas
Lance redirect({ href: 'https://...' }) de @tanstack/react-router dentro do handler e chame a server function via useServerFn no componente. useServerFn segue o redirect, inclusive para outro site.
O middleware de requisição global fica em src/start.ts, retornado por createStart como requestMiddleware. Ele roda antes de SSR, server routes e server functions. Criar esse arquivo significa adicionar createCsrfMiddleware() por conta própria.
Use .validator() para conferir que a entrada é FormData e transformá-la num objeto simples, e depois rode o safeParse do Zod no handler para poder devolver uma mensagem por campo.
Não, não há plano gratuito. Testar é grátis: você pode enviar 50 envios de teste por mês a partir de localhost antes de pagar. Para entrar no ar, o Pro começa em US$ 6/mês para 500 envios, ou você pode pagar uma vez 10.000 envios por US$ 49 ou 50.000 envios por US$ 149, com créditos que nunca expiram.
Travou em algum passo ou quer um guia para o seu caso? Envie um e-mail para hello@ikiform.com.