Langfuse に機能を追加してマージされるまで：日本語コントリビュートガイド

Yuto Toya
2025年12月18日
読了時間: 6分

LLM オブザーバビリティプラットフォーム「Langfuse」に機能を追加して、PR がマージされるまでの過程を紹介します。環境構築でハマったポイントや解決方法もまとめているので、日本語でのコントリビュートガイドとしてもお使いください。

この記事で得られること

Langfuse 開発環境のセットアップ手順
実際に遭遇したエラーと解決法
セルフホスト/クラウドモードの違いと切り替え方
PR 作成時のベストプラクティス

コントリビュートの背景

セルフホスト環境で Langfuse を使っていて、Vertex AI の認証に Application Default Credentials（ADC） を使いたかったのですが、その機能がありませんでした。AWS Bedrock には既に ADC 対応があったので、Vertex AI にも同様の機能を実装することにしました。

成果: PR #11039 がv3.140.0でマージされました 🎉 （私の PR #10915 が取り込まれたもの）

まずは公式ドキュメントを読もう

Langfuse には充実したコントリビュートガイドがあります。必要なツール、セットアップ手順、コミット規約、テスト方法まで丁寧に書かれているので、まずはこれを一読することを強くおすすめします。

この記事は公式ドキュメントを補足するもので、「読んだけどハマった」ポイントを中心に書いています。

必要なツール一覧

公式ドキュメントの内容を日本語で整理します。

ツール	バージョン	備考
Node.js	v24 推奨	v20 でも警告付きで動く。nvm 等でインストール
pnpm	9.5.0+	npm/yarn は不可。corepack や npm 経由でインストール
Docker 環境	最新	Docker Desktop、Rancher Desktop など。4 コンテナが起動
golang-migrate	最新	ClickHouse マイグレーション用
ClickHouse CLI	最新	デバッグ用（任意）

インストール方法は環境によって異なるので、各ツールの公式ドキュメントを参照してください。

Docker で起動するコンテナ

pnpm run dx を実行すると、以下の 4 つのコンテナが起動します。

コンテナ	用途	ポート
PostgreSQL	メイン DB（OLTP）	5432
ClickHouse	分析 DB（OLAP）	8123, 9000
Redis	キャッシュ、キュー	6379
MinIO	S3 互換ストレージ	9090, 9091

環境構築でハマったこと

1. pnpm not found

zsh: command not found: pnpm

原因: corepack が有効化されていない、または pnpm がインストールされていない

解決方法:

# 方法1: corepack を有効化
corepack enable

# 方法2: npm でグローバルインストール
npm install -g pnpm

2. golang-migrate がない

Error: migrate: command not found

原因: 公式ガイドに書いてあるが見落としがち

解決方法:

brew install golang-migrate

📝 補足: golang-migrate は ClickHouse のマイグレーションに使われます。PostgreSQL は Prisma を使いますが、ClickHouse は Prisma がサポートしていないため、別のツールが必要です。

3. ~/package-lock.json の罠

Error: Cannot find module '@langfuse/shared'

原因: ホームディレクトリ（~）に古い package-lock.json があると、Node.js のモジュール解決がおかしくなることがある

解決方法:

# ホームディレクトリの package-lock.json を削除
rm ~/package-lock.json

# node_modules もクリーン
cd ~/langfuse
pnpm run nuke  # 全ての node_modules と build ファイルを削除
pnpm install

4. ポート 5432 競合

Error: listen EADDRINUSE: address already in use :::5432

原因: 他のアプリケーション（Docker環境であるRancher Desktop）の PostgreSQL コンテナがポート 5432 を使用していた

解決方法: .env ファイルでポートを変更

# ポート番号を変更
POSTGRES_HOST_PORT=5433

# データベース URL も同じポートに
DATABASE_URL="postgresql://postgres:postgres@localhost:5433/postgres"
DIRECT_URL="postgresql://postgres:postgres@localhost:5433/postgres"

5. セルフホストとクラウドモード設定

これが一番のハマりポイントでした！

機能を実装したのに、UI に ADC のオプションが表示されない…

原因

環境変数 NEXT_PUBLIC_LANGFUSE_CLOUD_REGION でアプリの動作モードが決まります。.env.dev.example には以下の設定があります。

NEXT_PUBLIC_LANGFUSE_CLOUD_REGION="DEV"

この値が設定されていると、Boolean("DEV") は true になるため、クラウドモードとして動作します。

// 判定ロジック（fetchLLMCompletion.ts）
const isLangfuseCloud = Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION);
const isSelfHosted = !isLangfuseCloud;

クラウドモードでは、セルフホスト専用機能（ADC など）が UI に表示されません。

解決方法

.env でこの行をコメントアウトします。

# コメントアウトする
# NEXT_PUBLIC_LANGFUSE_CLOUD_REGION="DEV"

サーバーを再起動すると、ADC オプションが表示されるようになります。

モードの違い

機能	セルフホスト（未設定）	クラウド（DEV/US/EU）
ADC 認証	✅ 使える	❌ 使えない
レート制限	無効	有効
UI メッセージ	"your database"	"our servers"

見分け方

ログイン画面を見れば、どちらのモードで動いているかすぐわかります。

クラウドモード: 「Data Region」セレクターが表示される
セルフホストモード: シンプルなログインフォームのみ

開発の始め方

1. Fork & Clone

git clone https://github.com/YOUR_NAME/langfuse.git
cd langfuse

2. 依存関係のインストール

pnpm install

3. 環境変数の設定

cp .env.dev.example .env

.env を編集します。

NEXT_PUBLIC_LANGFUSE_CLOUD_REGION をコメントアウト（セルフホスト機能をテストする場合）
必要ならポート番号を変更

4. 開発サーバーの起動

# 初回（DB リセットあり、時間がかかる）
pnpm run dx

# 2回目以降
pnpm run dev

5. 動作確認

http://localhost:3000 を開き、テストユーザーでログインします。

Email: demo@langfuse.com
Password: password

プロジェクト構造

Langfuse は pnpm + Turborepo のモノレポ構成です。

langfuse/
├── web/              # Next.js フロントエンド + API
├── worker/           # 非同期処理ワーカー
├── packages/
│   └── shared/       # 共有コード（スキーマ、ユーティリティ）
├── ee/               # Enterprise 機能
└── fern/             # OpenAPI 仕様

技術スタック

カテゴリ	技術
フレームワーク	Next.js 14（Pages Router）
API	tRPC
DB（OLTP）	PostgreSQL + Prisma
DB（OLAP）	ClickHouse
UI	Tailwind CSS + shadcn/ui
認証	NextAuth.js

PR 作成時に気をつけること

Conventional Commits を使う

feat(llm): add ADC support for Vertex AI
fix(security): prevent projectId specification
refactor(llm): rename useADC to shouldUseDefaultCredentials

提出前チェックリスト

# コード整形
pnpm format

# Lint チェック
pnpm run lint

CI について

PR を作成すると、以下のチェックが自動実行されます。

CLA assistant: 初回は Contributor License Agreement への署名が必要
depthfirst-app bot: AI による自動コードレビュー
dosubot: 自動ラベル付け

全てパスすると、メンテナーによるレビューに進みます。

PR の流れ（実体験）

私の PR は以下の流れで進みました。

PR 作成 → 3 つの自動チェックが走る
CLA 署名 → CLA assistant が署名を要求
AI レビュー → depthfirst-app bot がレビュー（ここで弾かれた場合は修正 or コメントを残す）
人間レビュー → メンテナーから changes requested
修正 → フィードバック対応
--------ここからはメンテナーが対応-------
マージ → 作業ブランチへマージ
本番マージ → メンテナーが main へマージする PR を作成

まずは3.のAI レビューのCIが通るまでが我々が行う作業です。

ここまで行けたら、メンテナーに知らせたりすると良いと思います！

その他知っておくと良いこと

今回の PR では使わなかったものもありますが、参考までに。

大きな変更は Issue を先に立てる: 公式ガイドにも記載されています
Discord で質問できる: 困ったことがあれば Discord で質問可能
good first issue から始める: 初コントリビュートなら good first issue ラベルがおすすめ

まとめ

Langfuse へのコントリビュートは、充実した公式ドキュメントのおかげでスムーズに進められました。環境構築では特に NEXT_PUBLIC_LANGFUSE_CLOUD_REGION の設定に注意が必要です。

レビューはとても丁寧で、変数名の改善やセキュリティの考慮点など建設的なフィードバックがもらえます。厳しく詰められるようなことはないので、安心して PR を出してみてください。

日本からも OSS にどんどん貢献していきましょう！

Langfuse に機能を追加してマージされるまで：日本語コントリビュートガイド

この記事で得られること

コントリビュートの背景

まずは公式ドキュメントを読もう

必要なツール一覧

Docker で起動するコンテナ

環境構築でハマったこと

1. pnpm not found

2. golang-migrate がない

3. ~/package-lock.json の罠

4. ポート 5432 競合

5. セルフホストとクラウドモード設定

原因

解決方法

モードの違い

見分け方

開発の始め方

1. Fork & Clone

2. 依存関係のインストール

3. 環境変数の設定

4. 開発サーバーの起動

5. 動作確認

プロジェクト構造

技術スタック

PR 作成時に気をつけること

Conventional Commits を使う

提出前チェックリスト

CI について

PR の流れ（実体験）

その他知っておくと良いこと

まとめ

参考リンク

最新記事

コメント

ガオ株式会社 (GAO, Inc.)