インタラクティブStripeドキュメントを作ったので技術紹介
まえがき
開発者による開発者のための Stripe ガイド大募集に応募すべくStripeビギナーズガイドを作りました。
コンセプト
実装の全体像を直感的に掴めること
をコンセプトにしています。決済機能は Stripe、クライアント、サーバーサイドの3者が連携して実装されます。その3者が各ステップで何をしなければならないのかが俯瞰的に分かるチュートリアルがあれば初学者の理解につながると思い作成しました。
対象
このドキュメントは以下のペルソナで設計されています。
- Stripeの概要が大雑把にわかっているが、実装はまだしたことがない方
- Firebase や Next.js などの最低限の開発知識がある方
サンプルプロジェクトの採用技術
Stripeに用意された3つのメイン機能をカバーしています。 Stripe Payments、 Stripe Billing、 Stripe Connectです。また実装方法は比較的簡易に実装できる以下の構成を採用しました。
- Next.js
- Firebase
- Run Payments with Stripe
特徴
グリッドレイアウト
各ステップでStripe、クライアント、サーバーサイドが何をしなければならないのか分かるようドキュメントをグリッドで並べました。
また、各ドキュメントはモーダルで開くのでドキュメントサイトにありがちなページの行ったり来たりで消耗することもありません。
完了機能
どこまで実装（学習）したのかメモしながら進める初学者も多いので完了機能をつけました。状態はローカルストレージで管理されているのでログインなど不要です。
すべてのドキュメントにショートクリップを添付
Stripeを使う決済システムの実装はクライアントやサーバーが複雑に絡み合うため、テキストだけだと実際の実装や動作イメージが掴みづらいと思います。各ドキュメントに実際の実装シーンをキャプチャした動画を添付しました。動画は再生速度を変えたり全画面表示にすることができるので効率的に閲覧することができます。
インフォグラフィックムービー
Stripe は Webhook などを使い Stripe とサーバーサイド、クライアントが複雑に絡み合うのでそれぞれがどのようなタイミングでどのような関係性で動くのかを視覚的に説明するインフォグラフィックムービーを作成しました。
モダンなUI
Next.jsによるSG、CSRの恩恵を受けるので高速でドキュメントの切り替えができます。またダークモードにも対応しています。
オープンソース
コードはすべて公開されています。
また、各ドキュメントの報告、編集リンクからGitHubのIssueや修正Pull Requestを直感的に作成できます。ドキュメントはマークダウンで編集できます。
ちなみにローカル環境の場合編集リンクをクリックするとVisual Studio Codeの該当ファイルが立ち上がります。
開発ノート
ここからが本題です。本プロダクトを公開するにあたり詰まった点、工夫した点をご紹介します。
使用技術
以下の技術を使っています。
- Next.js (TypeScript)
- Tailwind CSS
- Headless UI - モーダル等
- react-hot-toast - ポップアップ
- react-markdown - マークダウン
- next-seo - meta
- next-themes - ダークモード
工数
期間的には2週間ほどですが実稼働の工数としては以下のイメージです。
- システム開発: 1.5人日
- ドキュメンテーション（動画含む）: 3人日
計4.5人日 = 36時間
開発コンセプト
- GitHub Pagesで自己完結すること（外部APIやサーバーサイド処理に依存しない）
- マークダウン&オープンソースでドキュメント管理できること
- 軽量であること
軽量さを実現するためにすべての動画を ffmpeg で圧縮しました。画質が犠牲になりますがさまざまな環境を考慮して圧縮率を優先した結果、31.5MBの動画が884KB程度になりました。
開発のポイント、トラブル
Visual Studio Codeのスキーマリンクがかなり便利
こちらのツイートをたまたま発見して取り入れたところローカルでのドキュメント管理がかなり楽になりました。
また、GitHub にも直接ファイルを編集できるURLが用意されているのでオンラインでも直感的にPRが出せるようになっています。この辺りは個人的に気に入っています。
インフォグラフィックアニメーションは Keynote で作成
各ページヘッダのインフォグラフィックアニメーションは Keynote で作っています。あの手のアニメーションを共有した際に作成方法を聞かれることが多いので開発とは逸れますがご紹介しました。それぞれ30分ほどで作ることができました。
重すぎてpushできなかった
動画があったため git push が通りませんでした。こちらの記事のおかげでで解決しました。🙏🏻
GitHub Pages公開がめんどくさかった
GitHub Pages は一階層下がった位置に公開されるので next.config.js の調整にはじまりリンクやアセットのパスを環境変数を使って切り替える対応が必要でちょっと面倒でした。
やりきれなかったこと
技術選択機能
本当はクライアントサイド、サーバーサイドの技術部分をセレクタする予定でしたがスケジュールの都合で断念しました。たとえばクライアントサイドを Nuxt.js や バニラJSにしたりサーバサイドを Firebase 以外にするイメージです。
機能的には実装可能なのですがさしずめ私がドキュメントを作る必要があり、掛け算的に工数が増えるので断念しました。オープンソースなので今後リクエストがあれば機能だけ実装しようと思います。
Stripe Connectのカバー範囲
これはコンテンツに関することですが Stripe Connect はかなり浅くなってしました。 3つのアカウントタイプと2つの支払い方法（ダイレクト、デスティネーション）があるのですが今回は最も汎用性が高いExpress with デスティネーションのみを解説しています。
リファクタリング
ドキュメント管理のスキームを破壊と創造を繰り返しながら走り書きした感じなので型を types ディレクトリにまとめるなどの整理整頓がおざなりになっています。また、階層を多くまたがないのでContextすら使わずpropsのみを使うという極めてベーシックな世界観となっています。
さいごに
今回のドキュメントのスキームはStripeガイドに限らず
- Algolia ガイド
- Webアプリケーション開発ガイド
など、クライアントやサーバーサイド、SaaSが絡み合う実装の解説に流用できそうに感じたので Algoliaビギナーズガイドとか作ってみようかなと思います。
こんな感じで何かしら作って公開していくので興味のある方はフォローをお願いします🦉
Discussion
↑ 私のPCのディスプレイサイズだとモーダル内のコンテンツ量が多い場合、モーダルの下が欠けました。
videoタグ以下をスクロールできるとよさそうですね。
すごい分かりやすい感じだったので応援してます。
ありがとうございます！Mac Chromeの場合モーダル内でスクロールすると下まで閲覧できますが、お使いの環境だとスクロールできない状態でしょうか？その場合、お手数ですが環境を教えていただけるとありがたいですm()m
Windows 10 Chrome 98.0.4758.82です。
ちなみにキー入力だとスクロールできました。
失礼しました。
よくみるとモーダルの後ろの薄暗い背景の下にスクロールバーが出てました。
ただ、このスクロールバーは薄暗い背景の下にあるので、私の環境だと動かせないです。
詳細ありがとうございます！Mac Chromeだと薄暗い背景ではなくモーダルの上でスクロールするとスクロールできますが、Windowsだと無理かもしれません。この辺りはTailwind UIママですがUI的によろしくないので調整します。ご指摘ありがとうございました m()m
追記: 修正しました ✅