mixpanel-js: the browser client for Mixpanel, and the loader choices behind it

A global object you call, not a class you construct

mixpanel-js is the official Mixpanel JavaScript library, and its central design choice is visible in the first line of the documentation: it is a set of methods attached to a global mixpanel object, meant for websites that want to send data to Mixpanel projects. That shape matters for evaluation. There is no plugin object to instantiate, no provider to register and no framework adapter to configure, so the library can be dropped into a server rendered page, a static site or a single page application with the same two lines. The full API reference is hosted separately, and the repository itself concentrates on installation, bundling and development rather than on an exhaustive method list. A full reference is not needed to use it, which is precisely why the loading story is where the real decisions sit.

init with a token, track with a name

The core usage pattern is short. You initialise the library with your project token and then track named events:

import mixpanel from 'mixpanel-browser';

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

The init call takes the token and an options object. Autocapture is one of those options, and it is the reason many sites adopt the library, since it collects interactions without every button handler calling track by hand. The browser module example in the documentation shows more of the option surface, with autocapture and debug enabled and persistence set to localStorage, which is what determines where the library keeps its state between page loads. The token in these examples is a placeholder for the value from your own Mixpanel project, and shipping the wrong one is the most common way to end up with an application that initialises cleanly and reports nothing.

Installing mixpanel-browser with npm

The library is published on NPM under the name mixpanel-browser, chosen specifically to distinguish it from Mixpanel's server side Node.js library, which is published as mixpanel. That naming detail prevents an entire class of mistake, but it also means the import name in your code and the package name in your manifest are the same string while the server side library lives under a different one. Installing into a project that uses a front end packager such as Vite or Webpack is a single command:

npm install --save mixpanel-browser

After that you import the default export and call init. The repository also ships prebuilt bundles at the top level, mixpanel.js and mixpanel.min.js, plus a snippet file mixpanel-jslib-snippet.js, for sites that would rather load a script tag than wire a bundler. The examples directory shows the four common consumption shapes, a CommonJS setup with browserify, an ES2015 setup with babelify, a TypeScript example and a UMD setup with webpack, which is a quick way to decide which build shape fits the codebase you are dropping this into.

The default bundle carries the session recorder with it

Here is the detail that should drive your install decision. The default mixpanel-browser bundle includes a bundled mixpanel-recorder SDK, the session replay component. The documentation provides two alternative loaders when you do not want that. To load the core SDK with no option of session recording:

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

And to load the core SDK while optionally pulling in the session recording and targeting bundles asynchronously through a script tag:

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

So the choice is between a smaller core, a core that defers the extras, and the default that ships everything up front. If you have no plan to use session replay, the default import is paying for bytes you will never trigger, and the core loader is a one line change.

Loading it as a browser module with an import map

If your site already uses browser JavaScript modules, the library can be pulled from the Mixpanel CDN through an import map, with no bundler involved:

<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>

Your own modules can then import mixpanel-browser by name. The application code is the same as in the bundler case:

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

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

This route is worth knowing about because it removes the dependency on the package manager entirely, which matters for a site that has no build step, and it also means the version you run is the one served by the CDN at that URL rather than the one pinned in your lock file. The package.json for the project points at dist/mixpanel.cjs.js as the main entry and dist/mixpanel.module.js as the module entry, so the bundler and the CDN path serve the same library in different formats.

Building, testing and generating the API reference locally

The repository is set up for contributors as well as consumers, and the scripts are all in package.json. Installing dependencies and building the distributable bundles is:

npm install
npm run build-dist

The build also writes dist/mixpanel-browser.cdx.json, a CycloneDX Software Bill of Materials covering the production dependency tree, and it ships with the published package. Regenerating just that file is npm run sbom, which runs cyclonedx-npm against the production dependencies and validates the result. Running the unit tests is npm test, which lints the source and then runs mocha over the unit test files, and the browser tests need a local server:

npm run integration_test

After that you browse to http://localhost:3001/tests/ and pick a scenario. The documentation notes that the last step is still manual, with a headless browser planned for the future, and that production releases are tested against a large matrix of browsers and operating systems. The API reference is generated with typedoc from the JSDoc in src/ and the types in src/index.d.ts, through npm run build-docs, and the same documentation is regenerated as part of the dist build.

Where the browser client stops and the server library begins

The limits of mixpanel-js come from its scope. It is a browser library, and Mixpanel's server side Node.js library is a separate package on NPM under the name mixpanel, so a project that needs to report events from a backend is looking at two libraries with two different names, two different lifecycles and two different token handling paths. There is also the design consequence of the global object approach. The library is convenient to call from anywhere, including inline script tags on a server rendered page, but it also means configuration is global state that a single page application with several embedded experiences has to coordinate, and there is no documented way to run two isolated instances side by side in one page. A second limitation is operational rather than technical: the browser tests still need a person to open a scenario in a browser, so a change in the library is verified by hand in that part of the pipeline. On maintenance, the release history is steady, with v2.82.1 on 2026-08-20, v2.83.0 on 2026-09-08 and v2.84.0 on 2026-10-06, the last of them adding an on_track hook and various fixes, and the previous one adding feature flag targeting operators. The last push was on 2026-10-06. The licence is Apache 2.0, so the notice and the licence text have to travel with any copy or fork you distribute.

Editorial conclusion

Adopt mixpanel-js when your site already sends product events to Mixpanel and you want the official browser client with autocapture rather than a hand rolled tracker, and when picking the loader variant matters for your bundle budget. Do not adopt it for server side event capture, since that is a separate package on NPM named mixpanel, and do not expect the browser library to be a full event pipeline on its own. Verify first which loader you import, since the default mixpanel-browser bundle includes mixpanel-recorder, and check the init options you need, such as persistence and autocapture, before you ship. The last push was on 2026-10-06 and the current release is v2.84.0 from the same day, under the Apache 2.0 licence.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mixpanel/mixpanel-js on GitHub
3. Project website
4. README
5. Releases