Formulário de captação de leads

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.

Preet SutharFundador, Ikiform

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.

Como um lead passa pelo middleware e pela server function do TanStack Starttoda requisiçãoenviarcsrfsó serverfunctionsfirstTouchGET, definelead_sourcepáginaSSRou serverfunctionuseServerFnenviaFormDatacreateServerFnvalidator,depois ZodIkiformchavesecreta,Originthrowredirecthref: Cal.com{ errors }mostrado emcada camponext()next()POSTJSONokZod ou 422Como um lead passa pelo middleware e pela server function do TanStack Starttoda requisiçãoenviarcsrfsó server functionsfirstTouchGET, definelead_sourcepágina SSRou server functionuseServerFnenvia FormDatacreateServerFnvalidator, depoisZodIkiformchave secreta,Originthrow redirecthref: Cal.com{ errors}mostrado emcada camponext()next()POSTJSONokZod ou 422
  1. Toda requisição passa primeiro pelo middleware CSRF; ele só confere chamadas de server function.
  2. Num GET ainda sem cookie, firstTouch lê as tags UTM e um referrer externo e os guarda.
  3. A página renderiza normalmente.
  4. No envio, useServerFn manda o FormData para a server function.
  5. O validator o transforma num objeto simples e o handler roda o Zod nele.
  6. Um lead válido vai ao Ikiform com a atribuição, o fit e o Origin do visitante.
  7. O handler lança um redirect para o Cal.com ou para a rota de agradecimento; useServerFn o segue. Os erros voltam como dados.
Escrever src/start.ts substitui o middleware de requisição padrão do Start, então o CSRF volta à mão.

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.

arquivos
src/
  start.ts
  lib/lead.ts
  routes/
    contact-sales.tsx
    contact-sales.thanks.tsx
vite.config.ts
.env

Defina 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 campoTipo no IkiformDefinido por
name, email, companyText, email, textO visitante
company_sizeSelect, com as opções 1_10, 11_50, 51_200, 201_1000, 1000_plusO visitante
budgetSelect, com as opções under_10k, 10k_50k, 50k_plus, unsureO visitante
timelineSelect, com as opções this_quarter, next_quarter, later, researchingO visitante
messageTextarea, opcionalO visitante
utm_source, utm_medium, utm_campaign, referrer, landing_pageText, opcionalSeu servidor, a partir da primeira visita
fitSelect, com as opções qualified, nurtureSeu servidor, após a validação
As versões no servidor enviam com uma chave secreta, então o Ikiform pula Allowed domains e a verificação humana. Todo envio passa a vir do IP do seu servidor, e o limite Standard de 5 por minuto por visitante conta todos os seus visitantes juntos. Escolha o limite de taxa Relaxed ou Custom para um formulário que você envia por um servidor, e mantenha IKIFORM_SECRET_KEY em variáveis de ambiente só do servidor.

Middleware global para o primeiro toque

src/start.ts
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, Origin ou Referer com a origem da requisição.
  • firstTouch pula tudo o que não é GET, então os envios de server function nunca mexem no cookie.
  • setCookie e getCookie vêm de @tanstack/react-start/server e só rodam no servidor.
  • Um cookie definido durante uma requisição só fica legível por getCookie na próxima. Aqui isso não é problema: o lead é enviado numa requisição posterior.

A server function

src/lib/lead.ts
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 o FormData; o Zod roda no handler com safeParse, 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 manda Origin e o Ikiform detecta por ele os testes gratuitos em localhost.
  • redirect({ href }) é a forma externa; redirect({ to }) fica dentro do app. Os dois são lançados.

A rota

src/routes/contact-sales.tsx
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.

HostO que saber
VercelAdicione o plugin nitro/vite e faça o deploy. Defina IKIFORM_SECRET_KEY nas variáveis de ambiente do projeto.
NetlifyAdicione @netlify/vite-plugin-tanstack-start ao vite.config.ts. Defina a chave nas configurações do site.
CloudflareAdicione @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.

  1. Rode o servidor de desenvolvimento, abra /?utm_source=test&utm_campaign=launch e confira nas ferramentas de desenvolvedor que o cookie lead_source é httpOnly.
  2. Em /contact-sales, escolha Under $10k e deixe Company vazio. O erro da empresa aparece e todos os outros valores continuam.
  3. 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.
  4. Envie como uma equipe de 1 a 10 pessoas. Você cai em /contact-sales/thanks.
  5. Abra Submissions no painel e confira utm_source, landing_page e fit.
  6. 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

ProblemaO que fazer
403 da sua própria server function depois de adicionar src/start.tsA 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 functionsrc/start.ts existe sem createCsrfMiddleware(). Adicione-o, como no exemplo.
A página não sai do lugar depois de um envio qualificadoA 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 clientegetCookie foi chamado fora de uma server function ou de um middleware. Mantenha-o dentro de .handler() ou .server().
422 validation_failedO 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

Travou em algum passo ou quer um guia para o seu caso? Envie um e-mail para hello@ikiform.com.