De anos de trabalho com cliente a um kit inicial Next.js + Sanity | Codrops

Nota do Editor: Na Codrops, adoramos celebrar desenvolvedores talentosos que transformam anos de experiência em ferramentas que ajudam outros a construir melhor. Estamos entusiasmados em apoiar o lançamento de Edo e esperamos que você goste da história por trás do que ele criou.

A primeira semana de cada construção de CMS que fiz parecia a mesma. Aumente o front-end, conecte o Studio, modele o construtor de páginas do zero, reconstrua a camada de SEO, refaça a revalidação do webhook, reestilize o mesmo formulário de contato pela quarta vez. Quando o trabalho para o qual o cliente realmente me contratou começou, três dias do orçamento haviam se esgotado e eles não tinham visto um único pixel que importasse.

Durante anos tratei isso como o custo do headless. Os primeiros dias desaparecem no encanamento e você faz as pazes com isso. O que quebrou essa história foi ver os mesmos insetos voltarem. Não semelhantes. Os mesmos. Uma migração do Sanity que destruiu um conjunto de dados. Um CDN que exibiu uma imagem OG obsoleta por três semanas enquanto um cliente presumia que eu a havia enviado errado. Um webhook que disparou duas vezes e corrompeu um mapa do site. Cada projeto, uma nova instância de um problema que já havia resolvido no último e deixado para trás em um repositório que nunca mais abriria.

Então comecei a manter as correções. Um projeto, depois dois, depois dez, cada patch dobrado em um padrão em vez de em um repositório de cliente que eu abandonaria. Esse padrão agora é A arquitetura de conteúdo , um iniciador de Next.js e Sanity no qual envio todos os projetos de clientes.

Esta é a história do que ele resolve e por que, após anos de refinamento, decidi colocá-lo nas mãos de outros engenheiros.

Se quiser construir sobre a mesma base que uso para todos os projetos de clientes, você pode obtê-lo pelo preço inicial de lançamento até 16 de julho de 2026.

O trabalho para o qual ninguém cita

A parte cara de uma construção headless nunca é a parte que você define. Os clientes pagam pela página inicial, pelos estudos de caso, pela animação, pelo que podem ver. O que eles não podem ver, e contra o qual nunca coloco um item de linha, é o construtor de páginas modelado para que os editores não possam quebrá-lo, o modo de rascunho e a visualização ao vivo conectados e quebrados silenciosamente até que você descubra o porquê, o bug de cache onde o conteúdo publicado fica obsoleto e o cliente jura que o site está errado, um estúdio em que seus editores podem navegar sem enviar um e-mail para você. Nada disso aparece em uma captura de tela. Tudo isso custa dias.

A solução para um trabalho como esse não é uma pilha de recursos. É um conjunto de decisões tomadas uma vez e comprometidas, então você inicia cada projeto além delas, em vez de relitigar cada uma delas. A diferença aparece no momento em que você inclui um agente de codificação.

Por que uma base decidida supera uma pilha de recursos

Peça a Claude Code ou Cursor para construir uma configuração headless do zero e você terá um arquitetura diferente a cada execução. Tudo plausível, nenhum decidido. O campo do link lida com referências internas uma vez e esquece o email na próxima. O construtor de páginas tem grades de proteção na terça e nenhuma na quarta. A camada de busca armazena em cache corretamente até a execução onde isso não acontece. O agente não está errado. Não tem opinião a defender, por isso inventa uma de cada vez e você herda a tendência.

Pegue a camada de busca, a parte que silenciosamente causa o bug de conteúdo obsoleto na maioria dos projetos. A decisão reside em um único auxiliar, com o raciocínio incorporado:

// One fetch helper, two caches, decided once.
//
// Production: useCdn = false
//   → reads hit Sanity's live API and return current content
//   → the Next.js Data Cache fronts every fetch (force-cache + tags)
//   → so the live API is touched only when a webhook busts a tag,
//     not once per visitor
//
// Development: useCdn = true
//   → the CDN is the cheaper read while iterating locally
//   → a few seconds of edge lag costs nothing during a build
//
// Publish → GROQ webhook → /api/revalidate → revalidateTag(tag)
//   → Data Cache drops the tag → next request is fresh

O CDN está desativado onde a atualização é importante, o cache de dados carrega a carga e um webhook invalida as tags exatas na publicação. O bug de conteúdo obsoleto deixa de ser um problema noturno porque o limite entre os dois caches é de propriedade, em vez de deixado indefinido. Essa é a forma de cada decisão do kit: tomada uma vez, anotada, da mesma forma em todos os projetos.

Isso também significa que os agentes trabalham a seu favor e não contra você. Um AGENTS.md e uma dúzia de habilidades com escopo entregam a Claude Code ou Cursor as convenções, para que eles construam dentro da arquitetura em vez de inventar uma nova a cada execução. Você mantém a estrutura, o agente cuida da digitação e a deriva desaparece.

Problemas que não resolvo mais duas vezes

Tudo no kit ganhou seu lugar por ser um problema que encontrei no trabalho de um cliente real e me recusei a consertar mais de uma vez. Alguns dos que custam mais tempo:

Os três campos ninguém acerta na primeira vez. Um campo de link que lida com referências internas, URLs externos, e-mail e parâmetros em um só lugar. Um campo de mídia que normaliza imagem, Mux, Rive e Lottie em uma única forma, cada um retornando dimensões para que a mudança de layout nunca entre na conversa. Um construtor de páginas com grades de proteção em vez de um vale-tudo. Digitado, reutilizável, composto em qualquer lugar.

O bug de conteúdo obsoleto desapareceu. A camada de busca acima, novas leituras na produção, o cache de dados fazendo o trabalho, webhooks invalidando na publicação, modo rascunho e visualização conectados e funcionando.

Editores enviando e-mail para perguntar onde está seu conteúdo. Um estúdio onde cada tipo de documento fica onde os editores esperam. As páginas possuem suas rotas, os singletons permanecem bloqueados, ninguém procura a página inicial.

SEO disparou na semana anterior ao lançamento. Metadados por página do esquema, um mapa do site conduzido pelo Sanity, OpenGraph com imagens cortadas automaticamente, robots.txt, tudo desde o primeiro commit.

Sites que os agentes de IA leem mal. Os agentes veem o site do seu cliente como um HTML com muitos tokens e o citam de forma errada. O kit vem com um llms.txt de propriedade do editor, elaborado pela IA com um clique, e Markdown por página servido no mesmo URL por meio de negociação de conteúdo, para que um agente solicitando Markdown obtenha conteúdo limpo enquanto um navegador ainda obtém HTML. O raciocínio completo está em um artigo dedicado .

Além dessas partes você para de pensar: autenticação básica para teste, formulários protegidos contra spam com Reenviar, redirecionamentos gerenciados no Sanity, transições de visualização e um script de configuração que provisiona o projeto Sanity, cria os tokens, adiciona CORS, registra o webhook e grava seu .env. A primeira execução é tratada, não documentada em um README que você deve seguir.

A arquitetura é fixa. As ferramentas na parte superior, Tailwind, Biome, Mux, Rive, Lottie, são padrões conectados de forma limpa para que saiam limpos. Não quer Tailwind, prefira ESLint, sem Mux nesta compilação? Puxe-os. O que você mantém é a parte que está por baixo: como o conteúdo é modelado, obtido e composto.

Por que uma pessoa, não uma equipe

A arquitetura é consistente porque uma mente a manteve desde o primeiro arquivo de esquema até a última revalidação gancho. Ninguém ignorou a opinião. Ninguém adicionou um campo porque uma parte interessada pediu com educação. Essa não é uma limitação disfarçada de virtude. É por isso que ele se mantém unido.

Eu também sou o usuário mais pesado. O kit é executado sob o trabalho do meu cliente, então o bug que encontrei na sexta-feira é o patch que será enviado na segunda-feira, e um problema que você enfrenta é aquele que meus próprios projetos estão prestes a resolver. Os usuários pagantes no repo são uma função forçada em meu próprio trabalho: não posso deixar o esquema apodrecer, pular uma atualização do Next.js ou fazer uma alteração significativa em um plug-in Sanity. Você compra o repo e é seu proprietário. Sem painel, sem assentos, sem telemetria.

Não vou afirmar que esta é a pilha perfeita para todos. Tal coisa não existe. O que posso dizer é que cobre 99% do meu próprio trabalho, os sites de clientes com muitas animações e orientados a conteúdo que construo semana após semana. Isso por si só valida isso para mim. Se o seu trabalho se parece com o meu, é provável que cubra o seu também.

O que foi enviado

Este não é um projeto paralelo preparado para venda. É a base de sites de clientes reais, daqueles que ganham prêmios.

Alguns deles: Bom companheiro , Casa de mel , Aspen Search , Anuc Home , Servir Robótica , Muralia , piscar , WASL , Vidas criativas em andamento , meu próprio site e o próprio site de arquitetura de conteúdo . O trabalho construído sobre esta base foi reconhecido por Awwwards , FWA e CSSDA . As horas que eu costumava perder com encanamento iam para as partes desses locais que um júri notifica. Agora, outros engenheiros também recuperam essas horas, e o kit continua crescendo na mesma direção: menos encanamento, mais trabalho que vale a pena fazer.

O que você recebe de volta

Nos próximos três dias de cada projeto, aqueles que costumavam desaparecer antes que o cliente visse um único pixel que valesse a pena olhar. Em cada construção a partir daqui, esse tempo é seu desde o início, livre para gastar no trabalho criativo para o qual o cliente está assinando o cheque.

O raciocínio por trás de cada decisão é escrito na íntegra, de leitura gratuita, em quatro partes em Estrutura do CMS , modelos de conteúdo , composição da página e primitivas de conteúdo . Leia o pensamento primeiro e decida se ele se encaixa.

Quando você estiver pronto para pular a reconstrução, A arquitetura de conteúdo é o repositório em que envio. Um pagamento, atualizações vitalícias, suas para manter. Se você não tem certeza se ele se adapta à sua maneira de trabalhar, escreva para mim e eu lhe direi francamente, às vezes isso significa dizer que não é o ajuste certo.