E EmDash CMS Everything Guides, use cases, plugins, templates
Português

Atualizar para o EmDash 1.0

Nesta página

O EmDash 1.0 remove as APIs que foram descontinuadas durante a série 0.x e move para emdash/internal/ os pontos de entrada que somente o próprio EmDash carrega. Este guia lista cada mudança incompatível e o que atualizar no seu site.

Atualize suas dependências

Atualize emdash e qualquer outro pacote do EmDash que o seu site usa para as versões mais recentes e, em seguida, refaça o build. O exemplo a seguir atualiza um site Cloudflare:

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

Se a sua implantação executa emdash migrate, execute-o com o arquivo .emdash/migrations.json produzido por um build feito depois da atualização. O comando rejeita um manifesto escrito por uma versão anterior do EmDash.

Depois de atualizar, seu site pode compilar e executar sem mais alterações. Se o build falhar ou o EmDash relatar um erro na inicialização, percorra as mudanças incompatíveis abaixo.

Para a lista completa de mudanças de cada pacote, consulte a entrada dele na página de versões.

Mudanças incompatíveis

Removido: cloudflareCache()

Em versões anteriores, cloudflareCache() de @emdash-cms/cloudflare fornecia um provedor de cache de rotas que limpava as páginas em cache por meio da API REST da Cloudflare.

cloudflareCache() e seus pontos de entrada @emdash-cms/cloudflare/cache e @emdash-cms/cloudflare/cache/config foram removidos. Um site que o importe falha no build.

O que devo fazer?

Substitua-o pelo provedor cacheCloudflare() do adaptador Astro para Cloudflare, que usa o Workers Cache. O adaptador habilita o Workers Cache na configuração de implantação gerada quando esse provedor é definido.

O exemplo a seguir mostra a mudança em astro.config.mjs:

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

O Workers Cache limpa o cache com cache.purge() de cloudflare:workers, então você pode excluir os secrets CF_ZONE_ID e CF_CACHE_PURGE_TOKEN do seu Worker. O cache de objetos KV (kvCache()) não muda.

Removido: Comments e CommentForm de emdash/ui

Em versões anteriores, os componentes Comments e CommentForm eram exportados tanto de emdash/ui quanto de emdash/ui/comments.

Agora eles são exportados somente de emdash/ui/comments. Um site que importe qualquer um dos componentes de emdash/ui falha no build.

O que devo fazer?

Atualize a importação. Os componentes em si não mudam.

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

Removido: emdash dev e emdash auth secret

Em versões anteriores, emdash dev iniciava um servidor de desenvolvimento apoiado por um ./data.db local, e emdash auth secret gerava um valor para EMDASH_AUTH_SECRET.

Ambos os comandos foram removidos. Executar qualquer um deles encerra com Unknown command.

O que devo fazer?

Substitua emdash dev pelo script de desenvolvimento do seu próprio site, como pnpm dev, ou execute astro dev. O site passa então a usar o adaptador de banco de dados da sua configuração.

Se o seu package.json tiver uma chave url em emdash, exclua-a. Para gerar tipos a partir de um site remoto, execute emdash types --url <site-url> ou defina EMDASH_URL.

Remova emdash auth secret dos seus scripts. Se o seu site já tem EMDASH_AUTH_SECRET definido, mantenha-o: o EmDash ainda o lê para que os hashes de IP armazenados de quem comenta permaneçam estáveis. Para criptografar em repouso os secrets dos plugins, gere uma chave de criptografia com emdash secrets generate.

Removido: experimental.registry

Em versões anteriores, você podia configurar o registro de plugins com experimental.registry nas opções de emdash().

A opção foi removida, junto com a própria opção experimental. Um site que ainda defina experimental.registry falha na inicialização com um erro que menciona a opção registry de nível superior.

O que devo fazer?

Mova o valor, sem alterações, para a opção registry de nível superior. Ela aceita a mesma string de URL ou o mesmo objeto de configuração.

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

Se sobrar um bloco experimental: {} vazio, exclua-o. Configurações TypeScript o relatam como erro.

Alterado: pontos de entrada internos movidos para emdash/internal/

Em versões anteriores, o emdash expunha pontos de entrada como emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations e emdash/plugin-test-runtime, que somente o próprio EmDash carrega.

Esses pontos de entrada ficam em emdash/internal/. O mesmo vale para os executores de migração do D1 e do Hyperdrive em @emdash-cms/cloudflare, que ficam em @emdash-cms/cloudflare/internal/db/. Eles não fazem parte da API pública e suas exportações podem mudar em qualquer versão. Sites que configuram o EmDash por meio de emdash() em astro.config.mjs não são afetados.

O que devo fazer?

Se o seu projeto importa algum desses caminhos diretamente, substitua a importação pela API pública:

  • Para configurar um banco de dados, um cache de objetos ou um provedor de mídia, use sqlite(), libsql() ou postgres() de emdash/db, memoryCache() de emdash/astro ou localMedia() de emdash/media.
  • Para testar um plugin, use @emdash-cms/plugin-test em vez de emdash/plugin-test-runtime.
  • Para executar seu próprio middleware antes do middleware do EmDash, defina a opção middleware.outer de emdash().

Os middlewares internos de autenticação, configuração inicial, redirecionamento e contexto de requisição não têm substituto público.

Descontinuações

Descontinuado: nomes anteriores de capabilities de plugins

Em versões anteriores, os plugins podiam declarar capabilities com nomes como read:content, network:fetch e page:inject sem nenhum aviso.

O EmDash registra um aviso na inicialização para cada plugin que declara um desses nomes descontinuados, listando a substituição atual de cada um (por exemplo, read:content → content:read). Os nomes descontinuados continuam funcionando durante toda a série 1.x.

O que devo fazer?

Se um plugin que você usa dispara o aviso, atualize-o para uma versão que use os nomes atuais ou peça ao autor que publique uma. Se você mantém o plugin, renomeie as capabilities no manifesto dele. Consulte Capabilities e segurança para os nomes atuais.