EmDash情報局

検索

相談する

このサイトは非公式の日本語訳です。Cloudflare・EmDashプロジェクトが運営するサイトではありません。

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

このページで分かること

  • Astro 6以上・Node.js 22.16以上のプロジェクトに、EmDash・Node.jsアダプター・Reactを入れ、astro.config.mjs と src/live.config.ts を設定する手順
  • 暗号化キーを .env に書き、セットアップウィザードで組み込みのコンテンツモデル（Posts・Pages、Category・Tag）を適用する流れ
  • テストページで公開済みのエントリーを取得して表示を確かめる方法と、確認に失敗したときの確認点
難易度
実践
読む時間
3分
前提知識
Astroとは／ターミナル・Node.js・npmの最低限／GitとGitHubの最低限
このページの目次

このガイドでは、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ガイドを使います。

設定を変更する前に、現在のプロジェクトをコミットするか、別の方法で保存します。

本サイトの補足 やさしい解説

Astroのサイトは、ビルド時にページを作っておく形（事前の描画）で作られていることがあります。EmDashは、ページが表示されるたびにデータベースからコンテンツを読み込むため、サイトを server 出力に切り替え、サーバーとして動かすためのアダプターを設定します。これはサイトのビルド方法とデプロイ方法を変える変更なので、始める前に今の状態をコミットして、元に戻せるようにしておきます。

EmDashのインストール

  1. 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

    公開するサイトにReactのコンポーネントがなくても、EmDashは管理画面にReactを使います。

  2. astro.config.mjs に、アダプター、React、EmDashを登録します。ファイルにすでに別のインテグレーションや設定がある場合は、それらを残したまま、この例から必要な項目を追加します。

    astro.config.mjs
    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 に追加します。

  3. EmDashをAstroのコンテンツの仕組みにつなぐため、src/live.config.ts を作成します。

    src/live.config.ts
    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 が別にあれば、それも引き続き一緒に動きます。

  4. ローカル用の暗号化キーを生成し、.env に書き込みます。

    npx emdash secrets generate --write .env

    .env が .gitignore で除外されていることを確認します。このキーは、データベースに保存されたプラグインの秘密情報を保護します。キーを置き換えたり失ったりすると、暗号化された値が読めなくなるため、サイトをデプロイする前に、保護された場所にバックアップを保管します。

本サイトの補足 やさしい解説

WordPressのプラグインは管理画面から追加できますが、EmDashを既存のAstroサイトに追加するときは、パッケージをインストールし、設定ファイルに登録します。astro.config.mjs には、データベース（ここではSQLiteの data.db）と、アップロードしたメディアの置き場所（uploads/）を指定します。src/live.config.ts は、Astroのページから getEmDashCollection() などでEmDashのコンテンツを取得できるようにするためのファイルです。data.db、uploads/、.env はGitにコミットしないよう、.gitignore に入っているかを確認します。

サイトとコンテンツの設定

  1. 開発サーバーを起動します。

    npm run dev

  2. http://localhost:4321/_emdash/admin/ を開きます。初回のアクセスでは、セットアップウィザードに移動します。サイトの情報を入力し、管理者のアカウントを作成して、パスキーを登録します。

    このプロジェクトにはシードファイルがないため、セットアップではEmDashに組み込まれた初期モデルが適用されます。PostsとPagesのコレクション、TitleとContentのフィールド、CategoryとTagのタクソノミーが作られます。サンプルのエントリーは追加されません。

  3. 「Posts」を開き、「New Post」を選択して、タイトルに EmDash is connected と入力します。「保存」を選択してエントリーを作成し、続けて「公開」を選択します。

これで、データベースの組み込みの posts コレクションに、公開済みのエントリーが1件入りました。次の手順では、それをAstroのページから読み込みます。

エントリーの取得

公開済みの投稿を一覧表示する、サーバーで描画するテスト用のページを作成します。

src/pages/emdash-test.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 をエクスポートしていることを確認します。
  • 開発中は動くのに、デプロイしたサイトで編集が反映されない場合は、そのページが事前に描画されていないこと、デプロイしたアプリケーションがサーバー出力を使っていることを確認します。
  • ビルドでいずれかのimportを解決できない場合は、インストールのコマンドを実行し直し、5つのパッケージが別のワークスペースのディレクトリではなく、このプロジェクトに追加されていることを確認します。

ほかのデータベース、ストレージアダプター、認証の選択肢については、設定リファレンスを読みます。コンテンツの取得ガイドでは、絞り込み、ページ分割、プレビュー、キャッシュのヒントを扱います。

訳の誤りを報告する