posthog-js

What is posthog-js?

The posthog-js npm package is a JavaScript library for integrating PostHog analytics into web applications. It allows you to track user interactions, capture events, and analyze user behavior in real-time.

What are posthog-js's main functionalities?

Initialization

Initialize the PostHog library with your API key and optional configuration settings.

const posthog = require('posthog-js');
posthog.init('YOUR_API_KEY', { api_host: 'https://app.posthog.com' });

Capture Events

Capture custom events with properties to track user interactions and behaviors.

posthog.capture('event_name', { property1: 'value1', property2: 'value2' });

Identify Users

Identify users with unique IDs and associate them with properties like email and name.

posthog.identify('user_id', { email: '[e-mail]', name: 'John Doe' });

Set User Properties

Set properties for identified users to enrich user profiles with additional information.

posthog.people.set({ property1: 'value1', property2: 'value2' });

Feature Flags

Check if a feature flag is enabled for the current user to implement feature toggling.

const isEnabled = posthog.isFeatureEnabled('feature_flag_key');

Other packages similar to posthog-js

mixpanel-browser

Mixpanel is a powerful analytics tool that offers similar functionalities to PostHog, such as event tracking, user identification, and property setting. Mixpanel also provides advanced features like A/B testing and user segmentation.

amplitude-js

Amplitude is an analytics platform focused on product intelligence. It offers event tracking, user identification, and behavioral analytics. Amplitude provides advanced features like cohort analysis and user journey mapping, which can be more detailed than PostHog's offerings.

README

PostHog Browser JS Library

For information on using this library in your app, see PostHog Docs.
This README is intended for developing the library itself.

Testing

Unit tests: run yarn test. Cypress: run yarn start to have a test server running and separately yarn cypress to launch Cypress test engine.

Running TestCafe E2E tests with BrowserStack

Testing on IE11 requires a bit more setup. TestCafe tests will use the playground application to test the locally built array.full.js bundle. It will also verify that the events emitted during the testing of playground are loaded into the PostHog app. By default it uses https://app.posthog.com and the project with ID 11213. See the testcafe tests to see how to override these if needed. For PostHog internal users ask @benjackwhite or @hazzadous to invite you to the Project. You'll need to set POSTHOG_API_KEY to your personal API key, and POSTHOG_PROJECT_KEY to the key for the project you are using.

You'll also need to sign up to BrowserStack. Note that if you are using CodeSpaces, these variables will already be available in your shell env variables.

After all this, you'll be able to run through the below steps:

1. Optional: rebuild array.js on changes: nodemon -w src/ --exec bash -c "yarn build-rollup".
2. Export browserstack credentials: export BROWSERSTACK_USERNAME=xxx BROWSERSTACK_ACCESS_KEY=xxx.
3. Run tests: npx testcafe "browserstack:ie" testcafe/e2e.spec.js.

Running local create react app example

You can use the create react app setup in playground/nextjs to test posthog-js as an npm module in a Nextjs application.

1. Run posthog locally on port 8000 (DEBUG=1 TEST=1 ./bin/start).
2. Run python manage.py setup_dev --no-data on posthog repo, which sets up a demo account.
3. Copy posthog token found in http://localhost:8000/project/settings and then
4. cd playground/nextjsand run NEXT_PUBLIC_POSTHOG_KEY='<your-local-api-key>' yarn dev

Tiers of testing

1. Unit tests - this verifies the behavior of the library in bite-sized chunks. Keep this coverage close to 100%, test corner cases and internal behavior here
2. Cypress tests - integrates with a real chrome browser and is capable of testing timing, browser requests, etc. Useful for testing high-level library behavior, ordering and verifying requests. We shouldn't aim for 100% coverage here as it's impossible to test all possible combinations.
3. TestCafe E2E tests - integrates with a real posthog instance sends data to it. Hardest to write and maintain - keep these very high level

Developing together with another project

Install Yalc to link a local version of posthog-js in another JS project: npm install -g yalc

Run this to link the local version

• In the posthog-js directory: yalc publish
• In the other directory: yalc add posthog-js, then install dependencies
  (for posthog this means: yalc add posthog-js && pnpm i && pnpm copy-scripts)

Run this to update the linked local version

• In the other directory: yalc update, then install dependencies
  (for posthog this means: yalc update && pnpm i && pnpm copy-scripts)

Run this to unlink the local version

• In the other directory: yalc remove posthog-js, then install dependencies
  (for posthog this means: yalc remove posthog-js && pnpm i && pnpm copy-scripts)

Releasing a new version

Just put a bump patch/minor/major label on your PR! Once the PR is merged, a new version with the appropriate version bump will be released, and the dependency will be updated in posthog/PostHog – automatically.

If you want to release a new version without a PR (e.g. because you forgot to use the label), check out the master branch and run npm version [major | minor | patch] && git push --tags - this will trigger the automated release process just like the label.

Prereleases

To release an alpha or beta version, you'll need to use the CLI locally:

1. Make sure you're a collaborator on posthog-js in npm (check here).
2. Make sure you're logged into the npm CLI (npm login).
3. Check out your work-in-progress branch (do not release an alpha/beta from master).
4. Run the following commands, using the same bump level (major/minor/patch) as your PR:

   npm version [premajor | preminor | prepatch] --preid=beta
   npm publish --tag beta
   git push --tags
   

5. Enjoy the new prerelease version. You can now use it locally, in a dummy app, or in the main repo.

Changelog

1.83.2 - 2023-10-17

• chore: Make ratings start at 0 (#834)