Aprofundamento do Astro 6.4: Pipeline Markdown conectável, Sätteri alimentado por ferrugem e revolução de implantação Cloudflare

Em 28 de maio de 2026, o Astro lançou o 6.4. Não é um recurso rotineiro nem uma simples coleção de correções de bugs - é um ponto de inflexão estrutural.

Três mudanças principais, cada uma seguindo uma linha de tendência profunda:

• Interface do processador Markdown — o fim do monopólio de uma década da unificada
• Sätteri — um processador Rust Markdown/MDX do zero, reduzindo o tempo de construção de CI de 120 para 55 segundos
• cf() helper — reunindo mais de 6 vinculações Cloudflare e injeções de contexto em uma única linha

Vamos nos aprofundar.

Processamento como interface

Bagagem histórica

Desde o primeiro dia, o pipeline Markdown do Astro foi conectado ao ecossistema unificado — especificamente remark (analisando Markdown AST) + rehype (transformando HTML AST) e seus milhares de plug-ins. Isso não é um problema em si – a unificação é vasta e flexível. O problema é que é codificado.

Você não pode trocá-lo. Mesmo que você precise apenas de GFM e âncoras de título, todo o pipeline JS de observação → rehype → stringify ainda é executado de ponta a ponta.

A API markdown.processor do 6.4 transforma isso de uma dependência fixa em uma interface trocável.

Mudança de arquitetura

graph TD
    subgraph "Before 6.4: Hard-coded pipeline"
        A1[astro.config] -->|fixed| B1[Unified engine]
        B1 --> C1[remarkPlugins]
        B1 --> D1[rehypePlugins]
        C1 --> E1[Markdown AST]
        D1 --> E1
    end

    subgraph "6.4+: Pluggable pipeline"
        A2[astro.config] -->|markdown.processor| B2[Processor interface]
        B2 --> C2[Unified
default processor]
        B2 --> D2[Sätteri
Rust processor]
        B2 --> E2[Custom engine]
        C2 --> F2[JS plugin ecosystem]
        D2 --> G2[Native Rust pipeline]
        E2 --> H2[User-defined AST]
    end

    style A1 fill:#ffcccc
    style A2 fill:#ccffcc
    style B2 fill:#e1f5fe

A principal mudança: astro.config não aceita mais remarkPlugins / rehypePlugins de nível superior diretamente. Em vez disso, há uma chamada processor() unificada.

Nova sintaxe de configuração

A sintaxe antiga ainda funciona no 6.4, mas agora está obsoleta e será removida no Astro 8.0:

// ❌ Deprecated (works in 6.4, removed in 8.0)
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    remarkPlugins: ['remark-toc'],
    rehypePlugins: ['rehype-slug'],
    smartypants: true,
    gfm: true,
  },
});

Nova sintaxe:

// ✅ Astro 6.4+ recommended
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeSlug],
      smartypants: true,
      gfm: true,
    }),
  },
});

A mudança é pequena, mas a implicação arquitetônica é grande — toda a configuração do Markdown agora está agrupada em uma única chamada processor, pronta para ser trocada no atacado por Sätteri ou outro mecanismo.

Cronograma de descontinuação

A janela de 6,4 a 8,0 é de aproximadamente 12 a 18 meses. Quanto mais tarde você migrar, mais dolorosa será a atualização:

[ \text{Risco de dívida técnica} = \int_{t_{6,4}}^{t_{8,0}} \text{config bloat}(t) , dt ]

Se o seu projeto adiciona novos plugins e novas páginas simultaneamente, a dívida acumulada cresce de forma superlinear. Comece a limpar agora.

Sätteri: Rust entra no pipeline de Markdown

O que é

@astrojs/markdown-sätteri é uma reescrita do zero de um processador Rust Markdown/MDX. Não é uma versão unificada acelerada por Rust - ele tem sua própria especificação AST, seu próprio analisador, seu próprio serializador. Isso significa que ele não executa plug-ins de observação mais rapidamente - simplesmente não executa plug-ins de observação.

Referências de desempenho

A equipe Astro executou benchmarks em dois sites do mundo real:

A aceleração do Sätteri é mais significativa em grandes sites de documentação. O motivo é simples: cada plug-in no pipeline unificado executa uma passagem AST completa; mais plugins significam mais travessias. Sätteri oferece recursos comuns do GFM (tabelas, listas de tarefas, links automáticos, tachados) opções de tempo de compilação, completando tudo em uma única passagem:

xychart-beta
    title "Build time: Unified vs Sätteri"
    x-axis ["Unified (baseline)", "Sätteri (Rust)"]
    y-axis "Build time (seconds)" 0 --> 150
    bar [120, 55]

Para cenários de CI/CD, as economias cumulativas somam:

[ \text{Economia total} = n_{\text{compilações diárias}} \times \Delta T \times d_{\text{dias úteis}} ]

50 compilações diárias × 65 segundos cada = 54 minutos economizados por dia. Isso representa cerca de 230 horas de CI por ano.

Mas a compatibilidade é o problema

Sätteri não é compatível com plug-ins de observação/rehype. Isso não é um bug – é uma necessidade arquitetônica do pipeline Rust AST. MDAST (Markdown AST) e HAST (HTML AST) são estruturas de dados JavaScript; um pipeline Rust nativo não pode executar plug-ins JS diretamente:

graph LR
    subgraph "Plugin compatibility matrix"
        direction TB
        P1[remark-toc] -->|❌ not supported| S[Sätteri]
        P2[remark-gfm] -->|✅ native support| S
        P3[rehype-slug] -->|❌ not supported| S
        P4[rehype-autolink-headings] -->|❌ not supported| S
        P5[custom remark plugin] -->|⚠️ needs porting| S
        P6[custom rehype plugin] -->|⚠️ needs porting| S
    end

    style S fill:#fff3e0
    style P2 fill:#e8f5e9
    style P1 fill:#ffebee
    style P3 fill:#ffebee
    style P4 fill:#ffebee

O roteiro do Astro 6.4 afirma explicitamente que Sätteri se tornará o processador padrão em uma versão principal futura. Isso significa duas opções agora:

1. Avalie e faça a portabilidade agora — se você tiver poucas dependências de plug-in, poderá mudar imediatamente
2. Permaneça unificado até o ecossistema amadurecer — mas você precisará migrar antes da versão 8.0

Fórmula de decisão:

[ \text{Ganho líquido} = \alpha \cdot \text{ganho de velocidade} - \beta \cdot \text{custo de migração do plugin} ]

Sites de documentação (poucos plugins, muito conteúdo): (\alpha \gg \beta), mude agora. Blogs com muitos plug-ins (toc + slug + autolink + matemática + diagrama): (\beta) pode superar (\alpha).

O que Sätteri suporta nativamente| Recurso | Unificado | Sätteri | Notas |

|———|———|———|—––| | GFM (tabelas, listas de tarefas, etc.) | Plug-in ✅ | ✅ nativo | Grátis | | Smartypants (citações inteligentes) | Plug-in ✅ | ✅ nativo | Grátis | | Sintaxe directive | ⚠️ precisa de remark-directive | ✅ nativo features: { directive: true } | Limpador | | Plug-ins MDAST/HAST | ✅ todos | ❌ | Limitação principal | | Componentes personalizados | ✅MDX | ✅MDX | Sätteri suporta MDX | | Fórmulas matemáticas | ⚠️ precisa de remark-math | ❌ precisa de um substituto unificado | Modo misto viável |

Implantação da Cloudflare: seis ligações compactadas em uma

O antigo trabalho manual

Antes da versão 6.4, a implantação no Cloudflare a partir do Astro exigia tratamento manual:

// ❌ 6.3 and earlier — every binding manually injected
export async function onRequest(context) {
  const { request, env, ctx } = context;
  const sessionKV = env.SESSION_KV;
  const assets = env.ASSETS;
  const clientIP = request.headers.get('cf-connecting-ip');
  const waitUntil = ctx.waitUntil.bind(ctx);

  // Then finally reach Astro's request handling
  return await handleRequest(request, {
    sessionKV, assets, clientIP, waitUntil
  });
}

Seis ligações comuns e valores de contexto precisam ser injetados: SESSION KV, ASSETS, cf-connecting-ip, waitUntil, locals.cfContext, roteamento de página de erro. Perca um e você obterá misteriosos 500 em produção.

A abstração cf()

cf(state, env, ctx) reúne todos os seis em uma única chamada:

sequenceDiagram
    autonumber
    participant C as Client
    participant F as Fetch Handler
    participant CF as cf(state, env, ctx)
    participant KV as SESSION KV
    participant AS as ASSETS
    participant IP as cf-connecting-ip
    participant WU as waitUntil
    participant A as Astro render

    C->>F: HTTP request
    F->>CF: call cf() helper
    CF->>KV: inject KV binding
    CF->>AS: resolve static assets
    CF->>IP: extract real client IP
    CF->>WU: register background task
    alt static resource hit
        CF-->>F: return resource
        F-->>C: 200 OK + resource
    else needs rendering
        CF->>A: forward to Astro
        A-->>F: HTML response
        F-->>C: 200 OK + HTML
    end

Aqui está a configuração real:

// ✅ Astro 6.4+
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    advancedRouting: {
      cf: true,  // one line to enable cf() helper
    },
  }),
});

advancedRouting.cf: true injeta automaticamente todas as ligações. Não é necessária nenhuma costura de contexto manual.

Integração de middleware Hono

Para equipes que usam Hono, cf() é exposto como middleware Hono:

import { Hono } from 'hono';
import { cf } from '@astrojs/cloudflare/hono';
import { actions, middleware, pages, i18n } from 'astro/hono';

const app = new Hono<{ Bindings: Env }>();

app.use(cf());          // ← one line injects all Cloudflare bindings
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());

export default app;

Complexidade da interface após abstração:

[ \text{Complexidade de integração}{antes} = \sum{i=1}^{6} \text{binding}_i \times \text{boilerplate}i ] [ \text{Complexidade de integração}{depois} = 1 \times \text{cf()} ]

Em outras palavras, quanto mais ligações você tiver, maior será a simplificação. Se o seu projeto usar apenas uma ligação KV, o benefício será modesto. Mas se você estiver usando KV + D1 + R2 + Queue + AI Gateway, essa abstração é enorme.

Paridade entre desenvolvimento e produção

Uma melhoria sutil, mas importante: o servidor de desenvolvimento local wrangler na versão 6.4 se comporta muito mais próximo do tempo de execução do Cloudflare Edge. Uma categoria de bug comum — funciona localmente, interrupções na produção — foi causada em grande parte por incompatibilidades de resolução vinculativa:

flowchart TB
    subgraph "Before 6.4"
        D1[Local dev] -->|behavior divergence| P1[Cloudflare Edge]
        D1 -->|Bugs only catchable in production| D1
        style D1 fill:#ffebee
        style P1 fill:#ffebee
    end

    subgraph "Astro 6.4+"
        D2[Local dev
wrangler + cf()] -->|high fidelity| P2[Cloudflare Edge]
        style D2 fill:#e8f5e9
        style P2 fill:#e8f5e9
    end

Especificamente, estas lacunas diminuíram significativamente em 6.4:

• Os caminhos de resolução do namespace KV correspondem à produção
• O comportamento de vinculação de ativos estáticos ASSETS é sincronizado
• cf-connecting-ip tem um valor simulado localmente
• O roteamento de páginas de erro não precisa mais de configuração manual

Caminho de atualização seguro

Migração trifásica

A atualização para o Astro 6.4 pode ser dividida em três fases:

flowchart LR
    A[Phase 1: Upgrade CLI] -->|npx @astrojs/upgrade| B[Phase 2: Update config]
    B -->|wrangler.jsonc
single entry point| C[Phase 3: Audit & test]
    C -->|Check Markdown rendering
verify plugin compatibility| D[Go to production]

    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#f3e5f5

Fase 1: Atualização

npx @astrojs/upgrade
# or
bunx @astrojs/upgrade

Isso lida com alterações de versão e reinstalação de dependências automaticamente. Se você estiver usando @astrojs/cloudflare, o adaptador também será atualizado.

Fase 2: migração de configuração

# Verify new config file format
npx astro sync

Se o seu projeto usa src/env.d.ts, o Astro 6.4 recomenda migrar para novas declarações de tipo:

/// <reference types="astro/client" />
/// <reference types="@astrojs/cloudflare" />

Configuração de wrangler.jsonc:

{
  "name": "my-astro-site",
  "compatibility_date": "2026-05-28",
  "compatibility_flags": ["nodejs_compat"],
  "pages_build_output_dir": "./dist"
}

Fase 3: Lista de verificação de auditoria

Matriz de decisão de migração

quadrantChart
    title "Sätteri Migration Strategy Matrix"
    x-axis Low Plugin Dependency --> High Plugin Dependency
    y-axis Low Build Time Sensitivity --> High Build Time Sensitivity
    quadrant-1 "Migrate Now"
    quadrant-2 "Evaluate & Port"
    quadrant-3 "Stay on Unified"
    quadrant-4 "Benchmark First"
    "Documentation site": [0.2, 0.9]
    "Marketing blog": [0.4, 0.6]
    "Plugin-heavy blog": [0.8, 0.3]
    "E-commerce content pages": [0.6, 0.7]
    "Technical tutorial site": [0.3, 0.85]
    "Corporate website": [0.5, 0.4]

Os projetos no quadrante superior esquerdo (sites de documentação, sites de tutoriais técnicos) — poucos plug-ins, longos tempos de construção — obtêm o máximo benefício de uma migração imediata. Aqueles no canto inferior direito (blogs com muitos plug-ins, sites de marketing altamente personalizados) devem fazer benchmark primeiro e esperar que o ecossistema de plug-ins amadureça.

Escotilha de fuga: uso misto

Se o seu projeto precisar da velocidade do Sätteri e de certos plug-ins de observação, há uma solução alternativa - configuração por diretório:

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { sätteri } from '@astrojs/markdown-sätteri';

export default defineConfig({
  markdown: {
    processor: unified(),
    // Use Sätteri for specific content collections
    contentCollections: {
      docs: { processor: sätteri() },
      blog: { processor: unified() },  // retain plugin support
    },
  },
});

Este recurso ainda é experimental (requer experimental.contentCollectionProcessorRouting: true), mas oferece um caminho intermediário pragmático: unificado para conteúdo com muitos plug-ins, Sätteri para conteúdo de desempenho crítico.

Migração para o mundo real: um site ativo

Executei um experimento de migração real em um site de documentação de médio porte. Aqui estão os dados:

Perfil do site

Etapas de migração1. Atualizar CLI: npx @astrojs/upgrade, sem erros

2. Migração de configuração: remarkPlugins / rehypePlugins movido para processor: unified({...})
3. Avaliar Sätteri: executou npx astro check --processor sätteri, encontrou dois plug-ins personalizados incompatíveis
4. Plugins personalizados de porta:
   • Plugin de destaque de sintaxe → Suporte nativo Sätteri (features: { syntaxHighlight: true })
   • Texto explicativo personalizado → Reescrito com a API transforms de Sätteri (35 linhas Rust → ligação JS)
   • Âncoras personalizadas → Descartadas, alteradas para IDs manuais
5. Ativar cf(): Adicionado advancedRouting: { cf: true } na configuração do adaptador cloudflare, código de ligação manual removido

Resultados

Conclusão: Velocidade vs Ecossistema

O Astro 6.4 faz uma pergunta que todo framework SSG acabará enfrentando: vale a pena sacrificar a velocidade nativa da compatibilidade do plugin?

A resposta de Astro é pragmática — sem pressa, mas a direção está definida. Sätteri é opcional, unificado está obsoleto, mas ainda não foi removido. Esta janela de transição dá tempo ao ecossistema para se ajustar.

Três coisas para levar:

1. O pipeline Markdown agora é conectável – o que significa que pode haver processadores Python, processadores Go ou processadores nativos de navegador no futuro
2. Projetos com muito conteúdo podem mudar para Sätteri hoje e reduzir metade do tempo de construção
3. Os usuários do Cloudflare quase não têm motivos para não usar cf() — ele compacta seis linhas de vinculações em uma, sem nenhum efeito colateral

Mais um sinal subtil: Sätteri é uma palavra sueca que significa “classificar/organizar”. A equipe Astro não escolheu um termo chamativo de marketing de desempenho. Eles escolheram uma palavra artesanal. Isso não é uma coincidência.

Referências

• Blog de lançamento do Astro 6.4
• Markdown nativo/RFC MDX
• pacote @astrojs/markdown-sätteri npm
• Documentos do adaptador @astrojs/cloudflare
• Exemplo de integração Hono + Astro