Documentação do YPY
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-*edata-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/.