データ可視化向けSSG「Observable Framework」のプロジェクト作成〜 GitHub Pages で公開するまで

はじめに

この記事は何？

この記事では、Observable Framework のプロジェクトを作成し、GitHub Pages で公開するまでの手順をまとめました。

詳細は 公式ドキュメント をご覧ください。

※本記事の内容は執筆時点のもののため、うまくいかない場合は最新情報をご確認ください。

対象読者

• Observable Framework を試してみたい人
• データ可視化を目的とした静的サイトを作って公開したい人
• 英語の公式ドキュメントを読むのが億劫、またはある程度の手順がわかれば十分な人

Observable Framework とは？

Observable Framework は、データアプリ（データを可視化したダッシュボードやレポートなど、主にデータの表示を目的としたアプリケーション）を静的サイトとして作るための静的サイトジェネレータ（SSG）です。

オープンソースであり、無料で使えます。

きっかけ

データ可視化・分析ツール Observable を使って社内データの可視化を試してみる機会があったのですが、Notebooks や Canvases はブラウザ上で動かすクラウドベースのツールのため、お試しで社内データをそこに載せるのは不安がありました。

Observable Framework であれば ローカルで動かしたり 任意の場所にホスティングできるということで、こちらを使いました。

事前準備

node のインストール

npx や npm を使うので、node が入っていなければインストールします。

brew でインストールできます。

$ brew -v
Homebrew 4.5.11
$ brew install node

バージョン確認

$ node -v
v24.9.0
$ npm -v
11.6.0
$ npx -v
11.6.0

Observable Framework は Node.js 18 以降が必要です。

Observable Framework プロジェクトの作成

プロジェクトを作りたいディレクトリで次のコマンドを実行。

npx @observablehq/framework@latest create

するといくつか質問されるので回答していきます。

質問内容は次の通りです。（公式ドキュメント より引用 & 補足）

◇  Where should we create your project?（どこにプロジェクトを作る？）
│  デフォルト回答: ./hello-framework
│
◇  What should we title your app?（アプリのタイトルは？）
│  デフォルト回答: Hello Framework
│
◇  Include sample files to help you get started?（サンプルファイルを含める？）
│  デフォルト回答: Yes, include sample files
│
◇  Install dependencies?（依存パッケージをインストールする？）
│  デフォルト回答: Yes, via npm
│
◇  Initialize a git repository?（git リポジトリを初期化する？）
│  デフォルト回答: Yes

回答が完了すると、現在のディレクトリの下にプロジェクトディレクトリが作成されます。

ローカルプレビューサーバー

プロジェクトディレクトリに入り 次のコマンドを実行すると、ローカルプレビューサーバーが起動します。

npm run dev

自動でブラウザにページが開き、開発中のサイトをプレビューできます。

サーバーを起動しているターミナルで Ctr+C で停止できます。

GitHub Pages にデプロイ

GitHub Pages に GitHub Actions でデプロイできるようにします。

まず、GitHub リポジトリで Settings → Pages → Build and deployment の Source を GitHub Actions に変更します。

次に、プロジェクトリポジトリに .github/workflows/deploy.yml を作成し、中身を次のようにします。

name: Deploy

on:
  # Run this workflow whenever a new commit is pushed to main.
  push: {branches: [main]}
  # Run this workflow when triggered manually in GitHub’s UI.
  workflow_dispatch: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

ほとんど 公式の例 と同じですが、私は定期的な自動デプロイは不要だったため、schedule トリガーを削除しています。

この例では次のタイミングでデプロイされます。

• main ブランチにプッシュしたとき
• GitHub 上でこのワークフローを手動実行したとき（下図参照）

GitHub リポジトリの Actions → 対象のワークフロー（この例では Deploy）→ Run workflow からワークフローを手動実行できます。

おわりに

本記事では、データ可視化向けの静的サイトジェネレータ Observable Framework のプロジェクト作成と、静的サイトを GitHub Pages に GitHub Actions でデプロイする手順をまとめました。

参考までに、本記事の手順で作成したリポジトリとデプロイ先のサイトです。

• GitHub リポジトリ: https://github.com/ysng2p/observable-framework-sandbox
• デプロイ先サイト（GitHub Pages）: https://ysng2p.github.io/observable-framework-sandbox/

※記事で扱っていない内容が含まれます。

ページの作り方や可視化の例についても別途記事にする予定です。

ここまでお読みくださり、ありがとうございました！