StoryblokとAstro連携

Page content

Astroプロジェクトの立ち上げから、Storyblokを組み込んで実際にブラウザで確認するまでの全工程を解説します。

src/ ├ pages/ │ └ […slug].astro ← すべてのページを受ける │ ├ components/ │ ├ storyblok/ ← ★CMS用コンポーネント │ │ ├ Page.astro │ │ ├ Feature.astro │ │ ├ Grid.astro │ │ └ Teaser.astro │ │ │ └ ui/ ← 通常UI │ ├ Header.astro │ └ Footer.astro │ ├ layouts/ │ └ BaseLayout.astro │ └ lib/ └ storyblok.js ← API設定（任意）

import { defineConfig } from ‘astro/config’; import storyblok from ‘@storyblok/astro’; import tailwind from ‘@astrojs/tailwind’; // Tailwind等を使う場合

export default defineConfig({ // 1. インテグレーションの設定 integrations: [ storyblok({ // [必須] Storyblokの「Settings > Access Tokens」から取得したPreviewトークン accessToken: ‘YOUR_PREVIEW_TOKEN_HERE’,

  // [必須] Storyblokのコンポーネント名(Key)とAstroコンポーネントのパスを紐付け
  components: {
    page: 'src/storyblok/Page',
    feature: 'src/storyblok/Feature',
    grid: 'src/storyblok/Grid',
    teaser: 'src/storyblok/Teaser',
    // ネストされたディレクトリでも指定可能
    hero: 'src/components/storyblok/Hero',
  },

  // [任意] APIの基本設定
  apiOptions: {
    // リージョン指定（欧州以外、例えば米国データセンターを使う場合は 'us'）
    region: 'eu', 
    // データのキャッシュ設定など
    https: true,
  },

  // [任意] ライブプレビュー用のBridge設定
  bridge: true, // デフォルトでtrue。Visual Editorでのリアルタイム反映に必須
}),
tailwind(), // 他のツールと併用可能

],

// 2. 画像最適化の設定 (Storyblokの画像サービスを利用する場合) image: { domains: [‘a.storyblok.com’], // Storyblokの画像ドメインを許可 }, });

1. Astroプロジェクトの作成

まずはベースとなるAstroプロジェクトを作成します。ターミナルを開いて以下のコマンドを実行してください。

Bash

# プロジェクトの作成（対話形式で進みます）
npm create astro@latest my-astro-storyblok

# ディレクトリへ移動
cd my-astro-storyblok

# 依存パッケージのインストール
npm install

Tip: セットアップ中の質問では「Empty」テンプレートを選び、TypeScriptは「Strict」または「Recommended」にすることをおすすめします。

npm create astro@latest my-astro-storyblok で出てくるこの2つは、スタート地点の“完成度”の違いです。
Astro と Storyblok を組み合わせる前提で、実務目線で整理します。

結論（先に）

  • すぐ開発したい → Basic

  • 完全に自分で設計したい → Minimal

① A basic, helpful starter project

👉 最初から“サイトっぽい形”が出来ている

含まれるもの

  • レイアウト（Layout.astro）

  • サンプルページ（index.astro）

  • CSS（ある程度整っている）

  • コンポーネント例

  • ナビゲーションなどの構造

イメージ

👉 「すでに骨組みがある家」

src/
 ├ layouts/
 ├ components/
 ├ pages/
 │   └ index.astro
 └ styles/

メリット

  • すぐ画面がそれっぽくなる

  • 初心者でも迷わない

  • Storyblokのデータ差し込みだけに集中できる

デメリット

  • 不要なコードが混ざる

  • 構成を理解せず使うと後で詰まる

  • CMS設計とズレる可能性あり

② Use minimal (empty) template

👉 完全に空の状態からスタート

含まれるもの

  • ほぼ何もなし

  • index.astroのみ

イメージ

👉 「更地」

src/
 └ pages/
     └ index.astro

メリット

  • 完全に自由設計

  • Storyblok中心の構成にしやすい

  • 無駄がない（本番向き）

デメリット

  • 最初の構築コストが高い

  • レイアウトも全部自作

  • 初学者は迷いやすい

③ Storyblok連携視点での違い（重要）

ここが一番大事です👇

Basicの場合

  • 既存のHTML構造に
    → Storyblokのデータを“流し込む”

👉 テンプレ主導

Minimalの場合

  • Storyblokのblok設計に合わせて
    → Astro側を作る

👉 CMS主導（推奨）

④ 実務おすすめ

小規模・検証

👉 Basic

  • とりあえず動かしたい

  • 学習目的

  • UIを気にしない

本番開発（かなり重要）

👉 Minimal（おすすめ）

理由：

  • Storyblokは「コンポーネント設計」が命

  • Astroもコンポーネントベース

つまり👇

👉 両方を合わせて設計した方が強い

⑤ 実務でよくある構成（Minimalベース）

src/
 ├ pages/
 │   └ [...slug].astro
 ├ components/
 │   ├ Page.astro
 │   ├ Feature.astro
 │   └ Grid.astro
 └ lib/
     └ storyblok.js

👉 Storyblokのblokと1対1対応させる

⑥ どっちを選ぶべきか（判断基準）

あなたの状態別👇

  • Astro初めて → Basic

  • CMS連携やる → Minimal

  • 将来拡張する → Minimal

  • とりあえず触る → Basic

まとめ

項目 Basic Minimal
初期状態 完成に近い 空
学習コスト 低い 高い
自由度 低い 高い
Storyblok相性 普通 ◎

一言でいうと

👉 Basic = 「完成された雛形」
👉 Minimal = 「プロ向けの土台」

2. Storyblokパッケージの導入

公式のインテグレーションを追加します。

Bash

npx astro add storyblok

実行すると、astro.config.mjs への自動追記とパッケージのインストールが行われます。

3. Storyblok側の準備

ブラウザで Storyblok にログインし、以下の設定を行います。

  1. Spaceの作成: 新しいSpaceを作成します。

  2. APIキーの確認: Settings > Access Tokens から Preview トークンをコピーします。

  3. コンポーネント作成: Block Library で page（既にあるはずです）と、新しく feature という名前のコンポーネントを作ります。

  4. Preview URLの設定: Settings > Visual Editor で、Locationを http://localhost:4321/ に設定します。

4. 設定ファイルとコンポーネントの記述

astro.config.mjs の編集

コピーしたAPIキーを貼り付け、Storyblokのコンポーネント名とAstroファイルを紐付けます。

JavaScript

import { defineConfig } from 'astro/config';
import storyblok from '@storyblok/astro';

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: 'ここに入力', 
      components: {
        page: 'src/storyblok/Page',
        feature: 'src/storyblok/Feature',
      },
    }),
  ],
});

コンポーネントファイルの作成

Storyblokから渡されるデータを表示するためのファイルを作ります。

src/storyblok/Page.astro

コード スニペット

---
import { storyblokEditable } from '@storyblok/astro';
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';

const { blok } = Astro.props;
---
<main {...storyblokEditable(blok)}>
  {blok.body?.map((nestedBlok) => (
    <StoryblokComponent blok={nestedBlok} />
  ))}
</main>

src/storyblok/Feature.astro

コード スニペット

---
import { storyblokEditable } from '@storyblok/astro';
const { blok } = Astro.props;
---
<section {...storyblokEditable(blok)} style="padding: 2rem; border: 1px solid #ccc;">
  <h2>{blok.name}</h2>
</section>

5. 動的なルーティングの設定

Storyblokの階層構造をそのままURLにするため、[...slug].astro ファイルを作成します。

src/pages/[…slug].astro を作成し、以下を記述：

コード スニペット

---
import { useStoryblokApi } from '@storyblok/astro';
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';

const { slug } = Astro.params;
const storyblokApi = useStoryblokApi();

const { data } = await storyblokApi.get(`cdn/stories/${slug === undefined ? 'home' : slug}`, {
  version: 'draft',
});

const story = data.story;
---

<html lang="ja">
  <head>
    <title>{story.name}</title>
  </head>
  <body>
    <StoryblokComponent blok={story.content} />
  </body>
</html>

6. 開発サーバーの起動

最後に、以下のコマンドでプレビューを開始します。

Bash

npm run dev

ブラウザで http://localhost:4321 を開きつつ、Storyblokの管理画面（Visual Editor）を開くと、Storyblokで追加した feature コンポーネントがリアルタイムで画面に反映されるはずです！

src/ ├ pages/ │ └ […slug].astro ← すべてのページを受ける │ ├ components/ │ ├ storyblok/ ← ★CMS用コンポーネント │ │ ├ Page.astro │ │ ├ Feature.astro │ │ ├ Grid.astro │ │ └ Teaser.astro │ │ │ └ ui/ ← 通常UI │ ├ Header.astro │ └ Footer.astro │ ├ layouts/ │ └ BaseLayout.astro │ └ lib/ └ storyblok.js ← API設定（任意）