E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

EmDash 1.0 へのアップグレード

このページ

EmDash 1.0 では、0.x の間に非推奨となった API が削除され、EmDash 自身だけが読み込むエントリポイントが emdash/internal/ 配下に移動します。このガイドでは、各破壊的変更と、サイトで更新すべき内容を説明します。

依存関係を更新する

emdash と、サイトで使用している他の EmDash パッケージを最新バージョンに更新し、再ビルドします。次の例は Cloudflare サイトを更新します。

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

デプロイで emdash migrate を実行している場合は、アップグレード後に行ったビルドで生成された .emdash/migrations.json に対して実行してください。このコマンドは、以前の EmDash バージョンが書き出したマニフェストを拒否します。

アップグレード後、追加の変更なしでサイトがビルドおよび実行できる場合もあります。ビルドが失敗したり、起動時に EmDash がエラーを報告したりする場合は、以下の破壊的変更を順に確認してください。

各パッケージの変更の完全な一覧は、リリースページのそのパッケージの項目を参照してください。

破壊的変更

削除：cloudflareCache()

以前のバージョンでは、@emdash-cms/cloudflare の cloudflareCache() が、Cloudflare REST API を通じてキャッシュされたページをパージするルートキャッシュプロバイダーを提供していました。

cloudflareCache() と、そのエントリポイント @emdash-cms/cloudflare/cache および @emdash-cms/cloudflare/cache/config は削除されました。これをインポートしているサイトはビルドに失敗します。

どうすればよいですか？

Workers Cache を使用する、Astro Cloudflare アダプターの cacheCloudflare() プロバイダーに置き換えてください。このプロバイダーを設定すると、アダプターは生成されるデプロイ設定で Workers Cache を有効にします。

次の例は、astro.config.mjs での変更を示しています。

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

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

Workers Cache は cloudflare:workers の cache.purge() でパージするため、Worker から CF_ZONE_ID と CF_CACHE_PURGE_TOKEN のシークレットを削除できます。KV のオブジェクトキャッシュ（kvCache()）は変更ありません。

削除：emdash/ui からの Comments と CommentForm

以前のバージョンでは、Comments コンポーネントと CommentForm コンポーネントは emdash/ui と emdash/ui/comments の両方からエクスポートされていました。

これらは emdash/ui/comments からのみエクスポートされます。どちらかのコンポーネントを emdash/ui からインポートしているサイトはビルドに失敗します。

どうすればよいですか？

インポートを更新してください。コンポーネント自体は変更されていません。

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

削除：emdash dev と emdash auth secret

以前のバージョンでは、emdash dev はローカルの ./data.db をバックエンドとする開発サーバーを起動し、emdash auth secret は EMDASH_AUTH_SECRET の値を生成していました。

どちらのコマンドも削除されました。実行すると Unknown command で終了します。

どうすればよいですか？

emdash dev は、pnpm dev などサイト独自の dev スクリプトに置き換えるか、astro dev を実行してください。サイトは、設定にあるデータベースアダプターを使用します。

package.json の emdash の下に url キーがある場合は削除してください。リモートサイトから型を生成するには、emdash types --url <site-url> を実行するか、EMDASH_URL を設定します。

スクリプトから emdash auth secret を削除してください。サイトにすでに EMDASH_AUTH_SECRET が設定されている場合は、そのまま残してください。保存済みのコメント投稿者の IP ハッシュを安定して保つため、EmDash は引き続きこの値を読み取ります。プラグインのシークレットを保存時に暗号化するには、emdash secrets generate で暗号化キーを生成します。

削除：experimental.registry

以前のバージョンでは、emdash() のオプションにある experimental.registry でプラグインレジストリを設定できました。

このオプションは、experimental オプション自体とともに削除されました。experimental.registry を設定したままのサイトは、トップレベルの registry オプションを示すエラーで起動に失敗します。

どうすればよいですか？

値は変更せず、トップレベルの registry オプションに移してください。同じ URL 文字列または設定オブジェクトを受け付けます。

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

空の experimental: {} ブロックが残った場合は削除してください。TypeScript の設定ではエラーとして報告されます。

変更：内部エントリポイントを emdash/internal/ に移動

以前のバージョンでは、emdash は emdash/routes/*、emdash/middleware/*、emdash/db/sqlite-migrations、emdash/plugin-test-runtime など、EmDash 自身だけが読み込むエントリポイントを公開していました。

これらのエントリポイントは emdash/internal/ 配下にあります。@emdash-cms/cloudflare の D1 および Hyperdrive のマイグレーション実行機能も同様で、@emdash-cms/cloudflare/internal/db/ 配下にあります。これらは公開 API ではなく、エクスポートはどのリリースでも変更される可能性があります。astro.config.mjs の emdash() で EmDash を設定しているサイトは影響を受けません。

どうすればよいですか？

プロジェクトがこれらのパスのいずれかを直接インポートしている場合は、公開 API に置き換えてください。

  • データベース、オブジェクトキャッシュ、メディアプロバイダーを設定するには、emdash/db の sqlite()、libsql()、postgres()、emdash/astro の memoryCache()、emdash/media の localMedia() を使用します。
  • プラグインをテストするには、emdash/plugin-test-runtime の代わりに @emdash-cms/plugin-test を使用します。
  • EmDash のミドルウェアより前に独自のミドルウェアを実行するには、emdash() の middleware.outer オプションを設定します。

内部の認証、セットアップ、リダイレクト、リクエストコンテキストのミドルウェアには、公開された代替手段はありません。

非推奨

非推奨：以前のプラグイン機能名

以前のバージョンでは、プラグインは read:content、network:fetch、page:inject などの名前で、警告なしに機能（capability）を宣言できました。

これらの非推奨の名前を宣言しているプラグインごとに、EmDash は起動時に警告をログに記録し、それぞれの現在の置き換え名（例：read:content → content:read）を示します。非推奨の名前は 1.x の間は引き続き動作します。

どうすればよいですか？

使用しているプラグインが警告を発生させる場合は、現在の名前を使用するバージョンに更新するか、作者にバージョンの公開を依頼してください。プラグインを自分で保守している場合は、マニフェスト内の機能名を変更してください。現在の名前については、機能とセキュリティを参照してください。