installing-posthog-in-a-codebase
Install and configure a PostHog SDK in a repository you can read and edit, following PostHog's docs for the framework. Use when a user working in their codebase asks to add, install, or set up PostHog, product analytics, session replay, or a PostHog SDK. Covers finding the right docs page, installing the latest package, getting the project token and ingestion host from project-get, keeping them in the env file, server-side setup, identifying users, and verifying the change. If you can't access the user's code, as is common in ChatGPT on the web or Claude on the web, use installing-posthog-from-chat instead.
How do I install this agent skill?
npx skills add https://github.com/posthog/ai-plugin --skill installing-posthog-in-a-codebaseIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions for installing and configuring PostHog SDKs in a codebase. It follows security best practices by recommending the use of environment variables instead of hardcoded secrets and utilizes official PostHog packages and documentation.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Installing PostHog in a codebase
Use this skill when you can read and edit the user's code.
If you can't access their code, as is common in ChatGPT on the web or Claude on the web, use installing-posthog-from-chat.
PostHog's docs are the source of truth for each SDK's setup. Init options, file locations and recommended settings change between SDK releases, so read the docs page for the framework before you write code, and follow it rather than what you remember.
1. Find the framework and read its docs
Detect the framework from the manifest files (package.json, pyproject.toml, requirements.txt, Gemfile, composer.json, go.mod, and so on) and the app's entry points.
A web app with its own backend usually needs a client SDK and a server SDK, so read both pages.
For a framework that isn't listed, call docs-search with the framework name.
2. Install the latest SDK
Add each package with the project's own package manager and no version, for example npm install posthog-js, pnpm add posthog-node, uv add posthog or bundle add posthog-ruby.
That resolves the newest release.
Don't type a version into the manifest from memory, because that pins an old release.
In a monorepo, install into the package that runs the app, not the workspace root.
3. Get the token and host
Call project-get without an ID.
Use api_token as the project token and api_host as the SDK's host option.
- Read both from environment variables in code, using the names the docs page uses (for example
NEXT_PUBLIC_POSTHOG_PROJECT_TOKENandNEXT_PUBLIC_POSTHOG_HOST). - Write the real values to the env file the framework loads, such as
.env.localor.env. If the project has an example env file, add the variable names there with empty values. - Never hard-code the token or the host in source files, and never use them as fallback defaults in code.
4. Initialize as the docs show
- Initialize the SDK once, in the place the docs page names. Don't add a second initialization elsewhere.
- For
posthog-js, setdefaultsto the date the docs page shows. It selects the newest set of recommended settings, so don't take a date from memory. - For a backend SDK in a long-running server, create one client for the process, reuse it, and shut it down when the process exits. Don't create a client per request.
- In serverless or edge handlers (for example Next.js route handlers on Vercel, or AWS Lambda), the runtime can freeze as soon as the response is sent, so queued events are lost. Flush before the handler returns: await
flush()on a reused client, or use the platform'swaitUntil, as the docs page describes. - For a server-rendered app (Django, Rails, Laravel and similar), add the server SDK as well as the browser snippet.
5. Identify users
If the app has login, call identify after login with a stable user ID from the auth system, such as the database ID, not an email address or display name.
Call reset() on logout.
Send server-side events with the same distinct ID, so client and server events land on the same person.
6. Verify
Run the project's build, type check or tests, and fix anything your change broke.
If you can run the app, load a page and check that events arrive with read-data-schema or execute-sql.
Tell the user which environment variables to add in their hosting provider before they deploy.
7. Check if the app sends email
If the app's server code sends email, such as password resets, sign-in codes or receipts, read references/transactional-emails.md after setup. A manifest with an email sending package, such as resend, @sendgrid/mail, postmark, mailgun.js, @aws-sdk/client-ses, @aws-sdk/client-sesv2, nodemailer, sendgrid, or boto3 code that calls SES, is one sign.
If the app does not send email, skip this step.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/posthog/ai-plugin/installing-posthog-in-a-codebase">View installing-posthog-in-a-codebase on skillZs</a>