既存の Astro プロジェクトに EmDash を追加する

このガイドは Astro プロジェクトに EmDash を追加し、1つの公開エントリで統合を検証します。 Node.js アダプター、SQLite、ローカルメディアストレージを使用するため、完全なパスが1台のマシンで動作します。

始める前に

Astro 6 以降と Node.js 22.16 以降を使用してください。プロジェクトで両方のバージョンを確認します：

node --version
npx astro --version

このガイドはサイトを Astro の server 出力に変更し、Node.js アダプターを設定します。これによりサイトのビルドとデプロイの方法が変わります。プロジェクトが既に別のサーバーアダプターを使用している場合、 2つ目を追加しないでください。そのアダプターを維持し、そのデプロイ要件に従ってください。Cloudflare の場合は Cloudflare Workers ガイドを使用してください。

設定を変更する前に、現在のプロジェクトをコミットまたは別の方法で保存してください。

EmDash をインストールする

EmDash、Node.js アダプター、React サポートをインストールします：
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
EmDash は公開サイトに React コンポーネントがなくても、管理パネルに React を使用します。

astro.config.mjs でアダプター、React、EmDash を登録します。ファイルに既に他のインテグレーションや設定がある場合、それらを維持しこの例から関連するエントリを追加してください：

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
    output: "server",
    adapter: node({ mode: "standalone" }),
    integrations: [
        react(),
        emdash({
            database: sqlite({ url: "file:./data.db" }),
            storage: local({
                directory: "./uploads",
                baseUrl: "/_emdash/api/media/file",
            }),
        }),
    ],
});

SQLite はコンテンツとコンテンツモデルを data.db に保存します。ローカルストレージアダプターはメディアを uploads/ に書き込み、EmDash のメディアルートを通じて提供します。両方のパスがまだ除外されていない場合は .gitignore に追加してください。

src/live.config.ts を作成して EmDash を Astro のコンテンツシステムに接続します：
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
プロジェクトに既に src/live.config.ts がある場合、ファイルを置き換えるのではなく、エクスポートされた collections オブジェクトに _emdash エントリを追加してください。ファイルベースのコレクション用の別の src/content.config.ts は引き続き並行して動作します。
ローカル暗号化キーを生成し .env に書き込みます：
```
npx emdash secrets generate --write .env
```
.env が .gitignore で除外されていることを確認してください。キーはデータベースに保存されたプラグインシークレットを保護します。キーを置き換えたり失ったりすると、暗号化された値が読めなくなるため、サイトをデプロイする前に保護されたバックアップを保持してください。

サイトとコンテンツのセットアップ

開発サーバーを起動します：
```
npm run dev
```
http://localhost:4321/_emdash/admin/ を開きます。初回訪問時にセットアップウィザードにリダイレクトされます。サイトの詳細を入力し、管理者アカウントを作成し、パスキーを登録します。

このプロジェクトにはシードファイルがないため、セットアップは EmDash の組み込みスタートモデルを適用します。 Posts と Pages コレクション、タイトルとコンテンツフィールド、カテゴリーとタグのタクソノミーを作成します。サンプルエントリは追加されません。
Posts を開き、New Post を選択し、タイトルとして EmDash is connected を入力します。Save を選択してエントリを作成し、次に Publish を選択します。

データベースには組み込み posts コレクションに1つの公開エントリが含まれています。次のステップでは Astro ページからそれを読み取ります。

エントリをクエリする

公開されたポストを一覧するサーバーレンダリングのテストページを作成します：

---
import { getEmDashCollection } from "emdash";

const { entries: posts, error } = await getEmDashCollection("posts");

if (error) {
	throw error;
}
---

<h1>EmDash posts</h1>
<ul>
	{posts.map((post) => <li>{post.data.title}</li>)}
</ul>

http://localhost:4321/emdash-test/ を開きます。ページには EmDash is connected と表示されます。管理パネルでタイトルを変更して再公開すると、このページを再読み込みすると更新されたタイトルが表示されます。

ローカル開発中、EmDash は現在のコンテンツモデルから emdash-env.d.ts も生成します。生成された宣言は TypeScript に posts コレクション名とその title フィールドを提供します。その生成ファイルを手動で編集しないでください。

検証が失敗した場合

アドミンが Loading EmDash… のまま止まる場合、Astro の integrations 配列に react() が含まれていることを確認してください。@astrojs/react をインストールしただけでは登録されたことになりません。
getEmDashCollection() がライブコレクションに関するエラーを返す場合、src/live.config.ts が emdashLoader() 付きの _emdash をエクスポートしていることを確認してください。
ページが開発では動作するがデプロイした編集が表示されない場合、ページがプリレンダリングされていないこと、デプロイされたアプリケーションがサーバー出力を使用していることを確認してください。
ビルドがインポートの1つを解決できない場合、インストールコマンドを再実行し、5つのパッケージが別のワークスペースディレクトリではなくこのプロジェクトに追加されたことを確認してください。

他のデータベース、ストレージアダプター、認証オプションについては設定を参照してください。コンテンツクエリガイドではフィルター、ページネーション、プレビュー、キャッシュヒントを扱います。