Mixpanel JavaScript Library

The Mixpanel JavaScript Library is a set of methods attached to a global mixpanel object intended to be used by websites wishing to send data to Mixpanel projects. A full reference is available here.

Alternative installation via NPM

This library is available as a package on NPM (named mixpanel-browser to distinguish it from Mixpanel's server-side Node.js library, available on NPM as mixpanel). To install into a project using NPM with a front-end packager such as Vite or Webpack:

npm install --save mixpanel-browser

You can then import the lib:

import mixpanel from 'mixpanel-browser';

mixpanel.init("YOUR_TOKEN", {autocapture: true});
mixpanel.track("An event");

NOTE: the default mixpanel-browser bundle includes a bundled mixpanel-recorder SDK. We provide the following options to exclude mixpanel-recorder if you do not intend to use session replay or want to reduce bundle size:

To load the core SDK with no option of session recording:

import mixpanel from 'mixpanel-browser/src/loaders/loader-module-core';

To load the core SDK and optionally load session recording and targeting bundles asynchronously (via script tag):

import mixpanel from 'mixpanel-browser/src/loaders/loader-module-with-async-modules';

Use as a browser JavaScript module

If you are leveraging browser JavaScript modules, you can use importmap to pull in this library.

<script type="importmap">
{
  "imports": {
    "mixpanel-browser": "https://cdn.mxpnl.com/libs/mixpanel-js/dist/mixpanel.module.js"
  }
}
</script>
<script type="module" src="main.js"></script>

Then you are free to import mixpanel-browser in your javascript modules.

// main.js
import mixpanel from 'mixpanel-browser';

mixpanel.init('YOUR_TOKEN', {autocapture: true, debug: true, persistence: 'localStorage'});

Building bundles for release

• Install development dependencies: npm install
• Build: npm run build-dist

npm run build-dist also writes dist/mixpanel-browser.cdx.json, a CycloneDX Software Bill of Materials (SBOM) covering the production dependency tree, so it ships with the published package. To regenerate just that file: npm run sbom.

Running tests

• Install development dependencies: npm install
• Run unit tests: npm test
• Start test server for browser tests: npm run integration_test
• Browse to http://localhost:3001/tests/ and choose a scenario to run

In the future we plan to automate the last step with a headless browser to streamline development (although Mixpanel production releases are tested against a large matrix of browsers and operating systems).

Generating documentation

• Generate Markdown with typedoc from the JSDoc in src/ and the types in src/index.d.ts: npm run build-docs (result is at doc/readme.io/javascript-full-api-reference.md, configuration in doc/typedoc.json)
• The docs are also regenerated as part of npm run build-dist

Thanks

For patches and support: @bohanyang, @dehau, @drubin, @D1plo1d, @feychenie, @mogstad, @pfhayes, @sandorfr, @stefansedich, @gfx, @pkaminski, @austince, @danielbaker, @mkdai, @wolever, @dpraul, @chriszamierowski, @JoaoGomesTW, @@aliyalcinkaya, @chrisdeely, @dylan-asos, @chrisknu, @pkuczynski, @sarmah-rup