1. 作ったもの
GitHubのプロフィールREADMEに埋め込める、カスタマイズ可能な統計カードを作成できるWebアプリを開発しました。
名前は RSCG - Readme Stats Canvas for GitHub です。
https://rscg.cy-an.net/
2. 開発した理由
既存のREADME Stats系ツールは、URLパラメータや用意されたテーマを使ってカードを生成するものが多く、デザインの自由度が限られていると感じていました。
そこで、自分らしいGitHubプロフィールカードを自由にデザインできるツールが欲しいと考え、RSCGを開発しました。
3. 主な機能
- GitHubの統計情報を表示
- ドラッグ＆ドロップによるカード編集
- バッジ、図形、アバター、進捗バーなどのカスタム要素
- 日本語、英語、中国語、韓国語に対応
- テンプレートの利用
- Undo / Redo
- カードサイズの自動調整
- 作成したカードの共有・公開
4. 技術スタック
フロントエンド
-
Next.js 16.2.9
- App Router
- standalone 出力
-
React 19.2.4
-
TypeScript 5
- strict mode
-
Tailwind CSS 4
- PostCSS
-
Lucide React
- UIアイコン
-
フォント
- Geist
- Geist Mono
- Noto CJK
バックエンド
-
Next.js Route Handlers
-
SQLite
-
better-sqlite3
-
Zod 3
- リクエストやカード設定の入力検証
-
独自SVG生成エンジン
- GitHub READMEに埋め込むSVGを生成
-
キャッシュ・アクセス制御
- ETag
- CDNキャッシュ
- レート制限
外部サービスとの連携
-
GitHub GraphQL API
@octokit/graphql
-
GitHub REST API
- GraphQL APIを利用できない場合のフォールバック
-
GitHub OAuth
-
Auth.js / NextAuth.js v5 beta
テスト・品質管理
-
Node.js組み込みテストランナー
-
Playwright
- E2Eテスト
-
ESLint 9
-
Prettier 3
-
TypeScriptによる型チェック
-
GitHub Actions
- テスト、型チェック、Lint、ビルド、E2Eテストを自動実行
実行・デプロイ
-
Node.js 24 Alpine
-
Docker
- マルチステージビルド
- ヘルスチェック
-
Next.js standalone 出力
-
GitHub ActionsからSSHでデプロイ
-
SQLiteデータの永続化
- ホスト側のデータディレクトリをコンテナにマウント
5. 実装で工夫した点
1. デザインツールのような操作性
専門的な知識がなくても直感的に編集できるよう、Canvaのようなデザインツールを意識したUIにしました。
要素をキャンバス上で移動・選択・リサイズできるほか、複数選択や8px単位のスナップにも対応しています。
2. 多言語対応
日本語だけでなく、英語、中国語、韓国語にも対応しました。
UIの翻訳だけでなく、生成するSVGのラベルやCJKフォントも言語に応じて切り替えています。
3. SVGを動的に生成
作成したカードは画像ファイルとして保存するのではなく、アクセス時にGitHubの最新データを取得してSVGを動的に生成します。
そのため、READMEに一度埋め込めば、カードに表示される統計情報を自動的に更新できます。
6. 苦労した点
1. ビジュアルエディタと最終的なSVGの整合性
特に難しかったのは、エディタ上のプレビューと、実際に公開されるSVGの表示を一致させることです。
主に次のような機能を実装しました。
- ドラッグ、複数選択、リサイズ、整列、8pxスナップ
- Undo / Redo と自動保存
- テキスト幅やCJK文字幅の疑似計測
- カードサイズの自動計算
- 16種類の要素を共通の設定モデルで管理
- エディタ上のプレビューと公開SVGの表示を統一
- GitHubの実データや言語、フォントの違いによる表示崩れへの対応
ブラウザ上のHTMLとSVGではテキストの描画方法が異なるため、文字幅の計算や要素の位置調整には特に苦労しました。
2. /[username] からのSVG配信
公開カードは、次のようなURLから配信します。
https://rscg.cy-an.net/[username]
このエンドポイントでは、SVGを生成するだけでなく、次の処理も行っています。
- GitHubユーザー名の厳密な検証
- GitHub GraphQL APIからの統計取得
- REST APIへのフォールバック
- APIタイムアウト処理
- 同一ユーザーに対する同時リクエストの排除
- GitHub統計と生成SVGのキャッシュ
- IP単位のレート制限
- ETagを利用した304 Not Modifiedの返却
- Accept-Languageに応じた多言語SVGの生成
- Acceptヘッダーに応じたHTMLとSVGの出し分け
GitHub APIの負荷を抑えつつ、READMEから安定して表示できるようにする必要があり、キャッシュ設計やエラー時のフォールバックに苦労しました。
7. リポジトリ
ソースコードはGitHubで公開しています。ライセンスは MIT License です。
8. おわりに
RSCGは、GitHubプロフィールをより自由にデザインできるツールを目指して開発しています。
実際に使ってみた感想や、不具合、追加してほしい機能などがあれば、GitHubのIssueから知らせてもらえるとうれしいです。
リポジトリへのStar、開発者アカウントのフォロー、GitHub Sponsorsでの支援も、今後の開発の励みになります。