Gatsby × Electron 最小構成スターターを作った話（TypeScript対応）

はじめに

Gatsby-desktop-kitはGatsby をフロントエンドに、Electron をバックエンドとして組み合わせ、クロスプラットフォームにwebとデスクトップアプリを同時に構築できるスターターキットを作成しました。目的は、最小構成かつ拡張性が高く、即座に開発を始められるテンプレートを用意することです。

GitHubで公開しています。誰でもすぐに使えます。

• GitHub: gatsby-desktop-kit-template
• Netlifyにデプロイ: https://gatsby-desktop-kit.netlify.app/

---

特徴

• Gatsby をフロントエンドに、Electron をバックエンドに採用
• 必要最小限の構成で、すぐに開発を開始できる
• TypeScript 対応ですが、JavaScript で開発しても問題なく動作します。
• Web用ビルドとデスクトップアプリビルドの両方に対応
• gatsby/src/index.tsx を編集するだけで、すぐにアプリ開発に入れる構成
• Gatsby 側は Netlify などのサービスにそのままデプロイ可能

---

対応環境・注意点

• 現在のところ、Windows でのみ動作確認済みです
• macOS / Linux のサポートは未検証ですが、PR歓迎です 集

開発におけるtips集

• Electron アプリが起動したままの場合、ビルド時にファイルがロックされて失敗することがあります
  タスクマネージャー等でプロセスを終了してください
• Electron ビルド後に画面表示が正しく行われない場合は、Gatsby が生成した minify（難読化）済みの HTML や JavaScript を dirtyMarkup などの整形ツールで整えて、構造を読み解くことで原因特定できることがあります。
• データの保存はlocalStorageがお勧め　web版とapp版の動作を同じにできるから

---

クローンと起動方法

git clone https://github.com/tatsuoNakano/gatsby-desktop-kit-template
cd gatsby-desktop-kit-template
npm install
cd gatsby
npm install
cd ../
npm run dev:web

Gatsby の開発サーバーのみを起動したい場合は dev:web
Electron アプリと同時に起動したい場合は dev を使用してください
dev:web使うのが一番軽いので開発向きです。

ディレクトリ構成

このプロジェクトは、Gatsby をフロントエンドとした Electron アプリです。

gatsby-desktop-kit-template/
├── electron/              // Electron 関連コード
├── gatsby/                // Gatsby フロントエンド
│   └── .env.example       // Gatsby 用 .env テンプレート
├── .env.example           // Electron 全体用 .env テンプレート
├── docs/                  // 多言語対応ドキュメント (ja, zh, en)
└── scripts/               // 内部スクリプト群（編集非推奨）

利用可能な npm スクリプト一覧

開発用

npm run dev        # Gatsby と Electron を並列で起動
npm run dev:web    # Gatsby の開発サーバーを起動
npm run dev:app    # Electron を ts-node 経由で起動

ビルド関連

npm run build        # Gatsby ビルド → Electron にコピー → デスクトップアプリ化
npm run build:web    # Gatsby の静的ビルド（パスプレフィックス有効）
npm run build:app    # electron-builder によるパッケージ作成

アセット同期

npm run copy         # Gatsby の public ディレクトリを Electron 側にコピー

クリーンアップ

npm run clean        # Gatsby と Electron のビルド成果物を削除
npm run clean:web    # Gatsby の .cache, public を削除
npm run clean:app    # Electron の dist, public を削除

.env ファイルについて

.env.example を元に .env を作成して設定を行います。

ELECTRON_PORT=9003
GATSBY_PORT=9000
GATSBY_SERVE_PORT=9001

必要に応じてポート番号などを調整してください。

アーキテクチャの補足

このプロジェクトでは electron-serve を使用しています。
Gatsby 側でビルドされた静的ファイルを Electron からも読み込むことで、Web版とデスクトップ版が共通の UI・ルーティング・localStorage を共有する構成です。

この設計により、開発とテストの一貫性が保たれ、メンテナンス性も高くなります。

貢献・フィードバック

macOS / Linux 対応や改善提案、README の翻訳など、幅広く歓迎しています。
お気軽に Issue や Pull Request をお送りください。

ライセンス

MIT License
(c) 2025 tatsuoNakano

宣伝

この構成で開発したアプリDevKitBaseの解説記事です。OSSの開発支援ツールです。良かったら併せてご覧ください。
https://qiita.com/tatsuoNakano/items/5c09a6a67baeebbd53dd