Migrate Eleventy (11ty) to Astro

Por que Migrar do Eleventy para Astro

Eleventy é um gerador de site estático sólido. É minimalista, rápido e respeita seu conteúdo mantendo-o em linguagens de template padrão. Se você vem rodando um site 11ty, provavelmente o escolheu exatamente por essas razões.

Então por que migrar?

Astro oferece tudo que Eleventy faz — zero JS por padrão, saída estática-first, builds rápidos — mais um modelo de componentes, otimização de assets integrada, coleções de conteúdo type-safe e suporte first-class para frameworks. Mesma filosofia, mas com uma experiência de desenvolvedor muito melhor.

Já migramos dezenas de sites Eleventy para Astro. É uma das transições mais suaves que fazemos porque os modelos mentais se alinham muito bem. Ambas as ferramentas respeitam a saída estática. Ambas enviam JavaScript mínimo. A diferença aparece quando você precisa de mais.

Os Pontos Críticos do Eleventy

Fragmentação de Linguagem de Template

Eleventy suporta HTML, Markdown, Nunjucks, Liquid, Handlebars, Mustache, EJS, Haml, Pug, WebC e linguagens customizadas. Isso é comercializado como flexibilidade. Na prática, cria fragmentação. Seus includes podem ser Nunjucks, seus layouts Liquid, seus arquivos de dados JavaScript. Novos desenvolvedores que entram no projeto gastam sua primeira semana apenas descobrindo qual linguagem de template faz o quê.

Nunjucks em si está efetivamente não mantido — o projeto Mozilla não vê atualizações significativas há anos. A implementação do Liquid no 11ty não suporta completamente argumentos nomeados. WebC foi introduzido como uma alternativa moderna mas não ganhou adoção ampla.

Pipeline de Assets Manual

Eleventy deliberadamente não lida com CSS, JavaScript ou otimização de imagens. Você configura seu próprio pipeline de build — tipicamente PostCSS, esbuild ou Vite, e o plugin eleventy-img. Poderoso se você sabe o que está fazendo, mas todo projeto começa com configuração significativa de tooling antes de você escrever uma única linha de conteúdo.

A Complexidade da Cascata de Dados

A cascata de dados do 11ty é poderosa mas opaca. Dados fluem de arquivos de dados globais, arquivos de dados de diretório, frontmatter de template, dados computados e arquivos de dados JavaScript — tudo se mesclando em uma ordem de prioridade específica. Debugar problemas de dados significa entender a cascata inteira. Causa confusão até em desenvolvedores experientes.

Nenhum Modelo de Componentes

Eleventy usa includes e shortcodes para UI reutilizável. Esses funcionam, mas não são componentes. Você não pode passar props tipadas, colocar estilos juntos ou progressivamente aprimorar elementos de UI específicos com interatividade client-side sem construir uma solução customizada do zero.

O que Astro Oferece

Componentes Reais, Zero Runtime

Componentes Astro parecem HTML com um bloco de script frontmatter. Suportam props tipadas, estilos com escopo e composição baseada em slots. Compilam para zero JavaScript por padrão — igual aos seus templates Nunjucks, mas com um modelo de componentes real por trás.

---
interface Props {
  title: string;
  date: Date;
}
const { title, date } = Astro.props;
---
<article>
  <h2>{title}</h2>
  <time datetime={date.toISOString()}>{title}</time>
  <slot />
</article>
<style>
  article { /* scoped automatically */ }
</style>

Coleções de Conteúdo com Type Safety

As coleções de conteúdo do Astro substituem a cascata de dados do 11ty com um sistema validado por schema, type-safe. Você define seu schema de conteúdo usando Zod, e Astro valida cada peça de conteúdo no tempo de build. Sem mais surpresas de campos de frontmatter faltantes descobertos em produção.

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

Isso substitui a cascata de dados implícita por schemas explícitos e validados. Seu IDE autocompleta campos de conteúdo. Erros de build capturam dados faltantes antes do deployment.

Otimização de Assets Integrada

Astro lida com bundling de CSS, processamento de JavaScript e otimização de imagens fora da caixa. O componente <Image /> gera imagens responsivas com srcset apropriado, converte para WebP/AVIF e lida com lazy loading — nenhuma configuração de plugin necessária.

Framework Islands Quando Você Precisa

Precisa de interatividade client-side — um widget de busca, um gráfico interativo, um formulário com validação? A arquitetura de ilhas do Astro deixa você dropar componentes React, Svelte, Vue ou Solid que hidratam independentemente. Com Eleventy, cada elemento interativo requer bundling de JavaScript customizado. Você constrói essa infraestrutura você mesmo.

Nosso Processo de Migração

Fase 1: Auditoria e Arquitetura (Semana 1)

Analisamos sua estrutura de projeto 11ty existente — linguagens de template em uso, dependências de cascata de dados, shortcodes, plugins e filtros customizados. Cada template Nunjucks/Liquid é mapeado para seu equivalente em componente Astro, e documentamos o fluxo de dados completo antes de escrever uma linha de novo código.

Fase 2: Migração de Conteúdo (Semana 1-2)

Seu conteúdo Markdown é transferido diretamente — Astro lê o mesmo formato de frontmatter. Definimos schemas Zod baseados em seus padrões de frontmatter existentes e configuramos coleções de conteúdo. Se você está usando dados computados do 11ty ou arquivos de dados JavaScript, convertemos para padrões de carregamento de dados do Astro.

A conversão de templates segue padrões previsíveis:

Eleventy	Astro
{% include "header.njk" %}	<Header />
{% block content %}{% endblock %}	<slot />
{{ variable | filter }}	{variable} com transformações JS
{% for item in collection %}	{collection.map(item => ...)}
Shortcodes	Componentes Astro
_data/ dados globais	Astro.glob() ou coleções de conteúdo

Fase 3: Design e Construção de Componentes (Semana 2-3)

Reconstruímos seus templates como componentes Astro com estilos com escopo. É aqui que a atualização compensa. Templates que eram includes Nunjucks desconfortáveis se tornam unidades limpas, tipadas e composáveis. Implementamos imagens responsivas, otimizamos fontes e adicionamos quaisquer ilhas interativas que seu site precise.

Fase 4: Testing e Verificação de SEO (Semana 3-4)

Auditorias completas de Lighthouse. Cada URL validada contra seu sitemap existente. Redirects testados. Dados estruturados verificados. Checamos que RSS feeds, meta tags sociais e URLs canônicas todos combinem seu setup existente antes de qualquer coisa ir live.

Estratégia de Preservação de SEO

Tanto Eleventy quanto Astro geram HTML estático, o que torna a migração de SEO muito mais simples que migrar de um framework client-rendered. Aqui está o que especificamente cuidamos:

• Paridade de URL: Mapeamos cada URL existente e garantimos caminhos idênticos em Astro. Se seu site 11ty usa estruturas de permalink customizadas, replicamos exatamente.
• Redirects 301: Para qualquer URL que deva mudar, configuramos redirects apropriados no nível de hosting.
• Geração de Sitemap: A integração @astrojs/sitemap do Astro gera um sitemap preciso automaticamente.
• Meta tags: Todas as title tags, meta descriptions, tags Open Graph e dados estruturados transferem para o gerenciamento <head> do Astro.
• Ganhos de Performance: A otimização de imagens integrada e o bundling de assets tipicamente melhoram Core Web Vitals, que alimenta rankings de busca.

Timeline e Preços

Migrações Eleventy para Astro estão entre as mais rápidas. Transferências de conteúdo com mudanças mínimas, e conversão de templates segue padrões mecânicos. As filosofias são próximas o suficiente que não há repensamento fundamental necessário.

• Sites pequenos (menos de 20 templates, blog/docs): 2-3 semanas, começando em R$ 20.000
• Sites médios (20-50 templates, múltiplos tipos de conteúdo): 3-5 semanas, começando em R$ 40.000
• Sites grandes (50+ templates, relacionamentos de dados complexos, recursos interativos): 5-8 semanas, começando em R$ 75.000

Cada migração começa com uma auditoria gratuita — avaliamos seu setup 11ty atual e produzimos um documento de escopo detalhado. Sem surpresas.