posthog-js v1.178.0
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 pnpm test
.
Cypress: run pnpm start
to have a test server running and separately pnpm 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://us.i.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:
- Optional: rebuild array.js on changes:
nodemon -w src/ --exec bash -c "pnpm build-rollup"
. - Export browserstack credentials:
export BROWSERSTACK_USERNAME=xxx BROWSERSTACK_ACCESS_KEY=xxx
. - 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.
- Run
posthog
locally on port 8000 (DEBUG=1 TEST=1 ./bin/start
). - Run
python manage.py setup_dev --no-data
on posthog repo, which sets up a demo account. - Copy Project API key found in
http://localhost:8000/project/settings
and save it for the last step. - Run
cd playground/nextjs
. - Run
pnpm i
to install dependencies. - Run
pnpm run build-posthog-js
to buildposthog-js
locally. - Run
NEXT_PUBLIC_POSTHOG_KEY='<your-local-api-key>' NEXT_PUBLIC_POSTHOG_HOST='http://localhost:8000' pnpm dev
to start the application.
Tiers of testing
- 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
- 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.
- 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 pnpm to link a local version of posthog-js
in another JS project: npm install -g pnpm
Run this to link the local version
We have 2 options for linking this project to your local version: via pnpm link or via local paths
local paths (preferred)
- from whichever repo needs to require
posthog-js
, go to thepackage.json
of that file, and replace theposthog-js
dependency version number withfile:<relative_or_absolute_path_to_local_module>
- e.g. from the
package.json
withinposthog
, replace"posthog-js": "1.131.4"
with"posthog-js": "file:../posthog-js"
- run
pnpm install
from the root of the project in which you just created a local path
Then, once this link has been created, any time you need to make a change to posthog-js
, you can run pnpm build
from the posthog-js
root and the changes will appear in the other repo.
pnpm link
- In the
posthog-js
directory:pnpm link --global
- (for
posthog
this means:pnpm link --global posthog-js && pnpm i && pnpm copy-scripts
) - You can then remove the link by, e.g., running
pnpm link --global posthog-js
from withinposthog
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 forget to add the label, don't try to update the version locally as you won't be able to push that commit to the main branch. Instead, just make a new PR.
Prereleases
To release an alpha or beta version, you'll need to use the CLI locally:
CLI
Only one person is set as a collaborator on NPM, so they're the only person that can manually publish alphas
- Make sure you're a collaborator on
posthog-js
in npm (check here). - Make sure you're logged into the npm CLI (
npm login
). - Check out your work-in-progress branch (do not release an alpha/beta from
main
). 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
Enjoy the new prerelease version. You can now use it locally, in a dummy app, or in the main repo.
Automagically
Use the "release alpha" label on your PR to have an alpha version published automatically. This automation currently doesn't check whether an alpha exists for the version it will try to publish. If you need to publish two alphas from one PR you'll need to fix that
Remember that these versions are public and folk might use them, so make sure they're not too alpha 🙈
8 days ago
12 days ago
6 days ago
8 days ago
12 days ago
12 days ago
12 days ago
14 days ago
2 months ago
20 days ago
20 days ago
21 days ago
29 days ago
22 days ago
2 months ago
20 days ago
21 days ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
1 month ago
1 month ago
1 month ago
1 month ago
2 months ago
1 month ago
1 month ago
1 month ago
29 days ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
19 days ago
19 days ago
19 days ago
2 months ago
2 months ago
19 days ago
18 days ago
18 days ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
19 days ago
3 months ago
3 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
4 months ago
4 months ago
6 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
3 months ago
6 months ago
3 months ago
5 months ago
5 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
4 months ago
4 months ago
4 months ago
4 months ago
6 months ago
6 months ago
6 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
3 months ago
5 months ago
5 months ago
3 months ago
3 months ago
4 months ago
6 months ago
3 months ago
6 months ago
3 months ago
6 months ago
3 months ago
3 months ago
3 months ago
6 months ago
3 months ago
3 months ago
4 months ago
4 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago