Documentação do YPY

5 min read Updated 2026-11-15

O YPY é uma biblioteca hipermídia: um elemento HTML diz, em atributos, qual requisição fazer, quando, e onde colocar o HTML que o servidor responde. Sem etapa de build para você, sem dependências, uma tag <script>. Inglês: YPY documentation.

Esta página é o mapa. Ache a sua tarefa na tabela, siga o caminho recomendado (leia as páginas nessa ordem) e use as seções abaixo quando precisar da lista completa.

Idioma das páginas. As páginas traduzidas ficam em pt-BR/ e espelham os caminhos do inglês. Onde ainda não há tradução, o link leva à página em inglês e traz a marca "(em inglês)". O código e os identificadores ficam sempre em inglês.

Caminho recomendado, por tarefa

Eu quero... Leia, nesta ordem
experimentar o YPY em dez minutos Primeiros passos (HTML puro, ou Go e Arandu)
entender o modelo Conceitos centrais, Events (em inglês)
montar um formulário que valida Forms (em inglês), ypy-error-*, a receita da sua pilha
atualizar vários lugares com uma resposta Multiple targets, <ypy-partial> (em inglês)
fazer o botão voltar e o cache funcionarem History and caching, History (em inglês)
servir o YPY pelo meu backend a receita: Go, Arandu, Django, Rails ou Laravel (as três últimas em inglês)
levar um projeto existente para o YPY Guia de migração, depois ypy migrate e ypy check (em inglês)
publicar com segurança Checklist de segurança, Security, Accessibility (em inglês)
deixar rápido Performance, o plano de desempenho (em inglês)
receber atualizações ao vivo do servidor (SSE) Streaming, signals (em inglês)
ter autocompletar e tipos no meu editor Editor support (em inglês)
usar ou escrever uma extensão Extensions, Official extensions (em inglês)
usar uma biblioteca de componentes (Bootstrap, React, Alpine, Web Component) Third-party components, ypy-preserve (em inglês)
testar o meu servidor sem navegador Testing your app (em inglês)
trabalhar no próprio YPY Core map, ADRs (em inglês)

Começar

  • Primeiros passos: a primeira página com HTML puro, o primeiro servidor com Go, o Arandu.
  • Conceitos centrais: atributos, gatilhos, alvos, trocas e morph, parciais, cabeçalhos, herança, estilização dos estados com o Tailwind.

Conceitos

Página O que explica
Conceitos centrais o modelo inteiro numa página: atributos, gatilhos, trocas, cabeçalhos
Events (em inglês) a vida de uma requisição, todos os eventos, detail.ctx
Swap styles and morph (em inglês) como uma resposta entra, e o que as mudanças do próprio usuário preservam
Attribute inheritance (em inglês) :inherited explícito, :append
History (em inglês) a barra de endereço, voltar e avançar

Guias

Guia Para
Primeiros passos os primeiros dez minutos
Conceitos centrais o vocabulário
Checklist de segurança antes de publicar
Guia de migração de marcação legada para o YPY
Events, Forms, Multiple targets, History and caching, Accessibility, Third-party components, Extensions, Performance, Testing your app os demais guias, por enquanto só em inglês
ypy migrate, ypy check as duas ferramentas de migração (em inglês)

Referência

A referência está em inglês: atributos · <ypy-partial> · eventos de fila · eventos de alvo · offline e online · config.classes · segurança · signals · extensões oficiais · swap e morph · histórico · herança · streaming ypy-stream · suporte a editores. A lista completa, por assunto, está no índice em inglês.

Receitas

Cada receita é um servidor funcionando, com os cabeçalhos YPY-*, 422 e 303, Vary: YPY-Request, CSRF, marcação com Tailwind e um teste.

Pilha Receita
Go, net/http Go
Arandu (Hesape, Kyse) Arandu
Django Django (em inglês)
Rails Rails (em inglês)
Laravel Laravel (em inglês)

Migração

Guia de migração: o caminho, o passo a passo, o que muda no comportamento e as tabelas de equivalência de atributos, eventos, cabeçalhos, configuração, extensões e API JavaScript. As ferramentas: o ypy migrate converte, o ypy check lista o que se comporta de outro jeito no YPY. Há um só comportamento e nenhuma camada de compatibilidade (ADR-0019).

Segurança

Checklist de segurança (faça antes de publicar) · Security (os ajustes, callbacks, o portão por nonce, Trusted Types, a CSP recomendada) · Auditoria de 2026-11-15 · Accessibility.

Desempenho

Performance · Plano e medições · Linha de base · ypy bench.

Ferramentas Go: ypy

Um binário, subcomandos explícitos, sem Node. Rode go run ./cmd/ypy <comando> no repositório, ou instale.

Comando O que faz Leia
ypy build gera dist/: pacotes, arquivos minificados, extensões, cópias Brotli; --sizes impõe os orçamentos (núcleo 18 kB, extensão 6 kB) Primeiros passos
ypy test roda as suítes de navegador em Chrome, Firefox e Safari; --dist roda contra os arquivos compilados Testing your app (em inglês)
ypy ci roda todos os portões: nomes, licenças, SPDX, formatação, vet, testes, tamanhos, guia, navegadores, migração Testing your app (em inglês)
ypy bench mede o desempenho num navegador de verdade, compara dois resultados, faz perfil Performance (em inglês)
ypy check acha usos antigos que quebram ou mudam ypy check (em inglês)
ypy gen gera os dados de editor (VS Code, JetBrains, JSON Schema) a partir da tabela de nomes; --check falha se um arquivo estiver desatualizado Editor support (em inglês)
ypy migrate converte um projeto escrito antes do YPY ypy migrate (em inglês)

SDK Go

O lado do servidor do YPY para Go: github.com/ypy-develop/go. Ele lê a requisição (ypy.FromRequest, ypy.Middleware), responde fragmentos, elementos <ypy-partial>, redirecionamentos e os cabeçalhos de resposta YPY-*, lê e aplica patches de signals, transmite mudanças por eventos enviados pelo servidor a um cliente ou a muitos, e testa tudo isso sem navegador (ypytest). Só biblioteca padrão. Comece por Primeiros passos, pela receita Go e por Testing your app (em inglês); a documentação do próprio SDK é o README, as páginas do SDK Go e o spec/PROTOCOL.md dele.

Convenções destas páginas

  • Todo exemplo usa classes do Tailwind CSS; nada no YPY depende dele.
  • Os nomes são ypy-* e data-ypy-* (atributos), YPY-* (cabeçalhos), ypy:* (eventos), ypy (o objeto global).
  • Cada página abre com um front matter curto (id, type, status, updated, tags), como as notas do workspace, e liga às outras páginas por caminhos relativos.

  • A documentação é escrita em inglês e em português do Brasil; as páginas em português espelham os caminhos em pt-BR/.