installing-posthog-in-a-codebase

コードベースへの PostHog のインストール

ユーザーのコードを読み取り、編集できる場合にこのスキルを使用します。 ChatGPT on the web や Claude on the web でよくあるように、コードにアクセスできない場合は、installing-posthog-from-chat を使用します。

各 SDK のセットアップでは、PostHog のドキュメントを正としてください。 初期化オプション、ファイルの場所、推奨設定は SDK のリリースによって変わるため、コードを書く前にフレームワークのドキュメントページを読み、記憶に頼らず、その内容に従ってください。

1. フレームワークを特定してドキュメントを読む

マニフェストファイル（package.json、pyproject.toml、requirements.txt、Gemfile、composer.json、go.mod など）とアプリのエントリーポイントから、フレームワークを特定します。 通常、独自のバックエンドを持つウェブアプリにはクライアント SDK とサーバー SDK の両方が必要なため、両方のページを読みます。

フレームワーク	ドキュメントページ
JavaScript ウェブ（すべてのフレームワーク）	https://posthog.com/docs/libraries/js.md
React（Vite アプリを含む）	https://posthog.com/docs/libraries/react.md
Next.js	https://posthog.com/docs/libraries/next-js.md
Vue.js	https://posthog.com/docs/libraries/vue-js.md
Nuxt	https://posthog.com/docs/libraries/nuxt-js.md
Svelte と SvelteKit	https://posthog.com/docs/libraries/svelte.md
Angular	https://posthog.com/docs/libraries/angular.md
Astro	https://posthog.com/docs/libraries/astro.md
Remix	https://posthog.com/docs/libraries/remix.md
React Router	https://posthog.com/docs/libraries/react-router.md
TanStack Start	https://posthog.com/docs/libraries/tanstack-start.md
Node.js（Express を含む）	https://posthog.com/docs/libraries/node.md
Python（FastAPI を含む）	https://posthog.com/docs/libraries/python.md
Django	https://posthog.com/docs/libraries/django.md
Flask	https://posthog.com/docs/libraries/flask.md
Ruby	https://posthog.com/docs/libraries/ruby.md
Ruby on Rails	https://posthog.com/docs/libraries/ruby-on-rails.md
PHP	https://posthog.com/docs/libraries/php.md
Laravel	https://posthog.com/docs/libraries/laravel.md
Go	https://posthog.com/docs/libraries/go.md
Java	https://posthog.com/docs/libraries/java.md
.NET	https://posthog.com/docs/libraries/dotnet.md
Elixir	https://posthog.com/docs/libraries/elixir.md
Rust	https://posthog.com/docs/libraries/rust.md
React Native	https://posthog.com/docs/libraries/react-native.md
Flutter	https://posthog.com/docs/libraries/flutter.md
iOS	https://posthog.com/docs/libraries/ios.md
Android	https://posthog.com/docs/libraries/android.md

一覧にないフレームワークの場合は、フレームワーク名を指定して docs-search を呼び出します。

2. 最新の SDK をインストールする

プロジェクトで使用しているパッケージマネージャーを使い、バージョンを指定せずに各パッケージを追加します。例：npm install posthog-js、pnpm add posthog-node、uv add posthog、bundle add posthog-ruby。 これにより、最新リリースが解決されます。 古いリリースに固定されるため、記憶を頼りにマニフェストへバージョンを入力しないでください。

モノレポでは、ワークスペースのルートではなく、アプリを実行するパッケージにインストールします。

3. トークンとホストを取得する

ID を指定せずに project-get を呼び出します。 api_token をプロジェクトトークンとして、api_host を SDK のホストオプションとして使用します。

• コード内では環境変数から両方を読み込み、ドキュメントページで使われている名前を使用します（例：NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN と NEXT_PUBLIC_POSTHOG_HOST）。
• 実際の値は、フレームワークが読み込む環境変数ファイル（.env.local や .env など）に記述します。プロジェクトに環境変数のサンプルファイルがある場合は、そこに変数名を空の値で追加します。
• ソースファイルにトークンやホストをハードコードしないでください。また、コード内でフォールバックのデフォルト値として使用しないでください。

4. ドキュメントの手順に従って初期化する

• SDK はドキュメントページで指定された場所で一度だけ初期化します。別の場所で二重に初期化しないでください。
• posthog-js の場合は、defaults にドキュメントページに記載された日付を設定します。これにより、最新の推奨設定セットが選択されるため、記憶に頼って日付を指定しないでください。
• 長時間稼働するサーバー上のバックエンド SDK では、プロセスごとにクライアントを 1 つ作成して再利用し、プロセスの終了時にシャットダウンします。リクエストごとにクライアントを作成しないでください。
• サーバーレスまたはエッジのハンドラー（Vercel 上の Next.js ルートハンドラーや AWS Lambda など）では、レスポンス送信直後にランタイムがフリーズすることがあり、キューに入ったイベントが失われる可能性があります。ハンドラーが戻る前にフラッシュしてください。再利用したクライアントで flush() を await するか、ドキュメントページの説明に従ってプラットフォームの waitUntil を使用します。
• サーバーサイドレンダリングのアプリ（Django、Rails、Laravel など）では、ブラウザスニペットに加えてサーバー SDK も追加します。

5. ユーザーを識別する

アプリにログイン機能がある場合は、ログイン後に identify を呼び出し、メールアドレスや表示名ではなく、データベース ID など認証システムの安定したユーザー ID を指定します。 ログアウト時には reset() を呼び出します。 クライアント側とサーバー側のイベントが同じユーザーに紐付くように、サーバー側のイベントには同じ distinct ID を送信します。

6. 検証する

プロジェクトのビルド、型チェック、またはテストを実行し、変更によって発生した問題を修正します。 アプリを実行できる場合は、ページを読み込み、read-data-schema または execute-sql でイベントが届いていることを確認します。 デプロイ前にホスティングプロバイダーで追加する環境変数をユーザーに伝えます。