mirror of https://github.com/hanzoai/insights-js.git synced 2026-10-30 18:34:19 +00:00

Files

T

zeekay 26a9531f7b merge: upstream/main (sync, brand preserved)

# Conflicts:
#	.github/workflows/check-insights-major-version.yml
#	.github/workflows/check-posthog-major-version.yml
#	.github/workflows/ci-security.yaml
#	.github/workflows/validate-versioning.yml
#	AGENTS.md
#	AGENTS.md~upstream_main
#	packages/ai/src/otel/capture.ts
#	packages/ai/src/otel/mappers/aiSdk.ts
#	packages/ai/src/otel/mappers/index.ts
#	packages/ai/src/otel/types.ts
#	packages/core/src/__tests__/posthog.init.spec.ts
#	packages/react-native/src/PostHogProvider.tsx
#	packages/react/src/context/PostHogContext.ts
#	packages/react/src/context/PostHogProvider.tsx
#	tooling/eslint-plugin-insights/no-unsafe-web-global.js

2026-06-02 10:52:56 -07:00

4.9 KiB

Raw Permalink Blame History

Hanzo Insights Browser JS Library

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

Dependencies

We use pnpm.

It's best to install using npm install -g pnpm@latest-9 and then pnpm commands as usual

Contributing

This package has the following optional peer dependencies:

@rrweb/types (2.0.0-alpha.17): Only required if you're using Angular Compiler and need type definitions for the rrweb integration.
rrweb-snapshot (2.0.0-alpha.17): Only required if you're using Angular Compiler and need type definitions for the rrweb integration.

These dependencies are marked as optional to reduce installation size for users who don't need these specific features.

Testing

Note

Run pnpm build at least once before running tests.

Unit tests: run pnpm test.
Cypress: run pnpm start to have a test server running and separately pnpm cypress to launch Cypress test engine.
Playwright: run e.g. pnpm exec playwright test --ui --project webkit --project firefox to run with UI and in webkit and firefox

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 Insights app. By default it uses https://us.i.insights.hanzo.ai and the project with ID 11213. See the testcafe tests to see how to override these if needed. For Insights internal users ask @benjackwhite or @hazzadous to invite you to the Project. You'll need to set INSIGHTS_PERSONAL_API_KEY to your personal API key (Personal API keys), and INSIGHTS_PROJECT_API_KEY to the key for the project you are using (Project API key).

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 packages/browser/playground/nextjs to test @hanzo/insights as an npm module in a Nextjs application.

Run insights locally on port 8000 (DEBUG=1 TEST=1 ./bin/start).
Run python manage.py setup_dev --no-data on insights 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 packages/browser/playground/nextjs.
Run pnpm install-deps to install dependencies.
Run NEXT_PUBLIC_INSIGHTS_KEY='<your-local-api-key>' NEXT_PUBLIC_INSIGHTS_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
Browser tests - run in real browsers and so 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 insights 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 @hanzo/insights 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)

run pnpm build and pnpm package in the root of this repo to generate a tarball of this project.
run pnpm -r update @hanzo/insights@file:[ABSOLUTE_PATH_TO_REPO]/target/@hanzo-insights.tgz in the root of the repo you want to link to.
run pnpm install in that same repo

Then, once this link has been created, any time you need to make a change to @hanzo/insights, run pnpm build && pnpm package from the root and the changes will appear in the other repo.

`pnpm link`

In the insights-js directory: pnpm link --global
You can then remove the link by running pnpm link --global @hanzo/insights from within the target repo

4.9 KiB Raw Permalink Blame History