heimdallr-sdk is a pluggable front-end monitoring SDK built as a monorepo

The plugin split is the design, not a packaging detail

The project presents itself as the first plug-in, pluggable front-end tracking SDK, described as easy to-use, lightweight and extensible, and the repository layout is where that claim is made concrete. The top level is a pnpm workspace with four plugin directories and three package directories. browser_plugins/ holds the plugins that run in a browser, wx_plugins/ holds the ones for WeChat mini programs, clients/ holds the transports that report data, and libs/ holds the shared code. On top of those sit tools/, scripts/, a playground/, an e2e/ directory and docs/. The packages directory in the root package.json confirms the shape, with the build script filtering on ./libs, ./clients, ./browser_plugins, ./wx_plugins and ./tools in turn. So a plugin is a first-class unit that can be built and released on its own, and the SDK is the composition of them. That is the difference between this and a script tag you paste into your index.html.

The plugin set covers errors, performance and session recording

The end-to-end test suite doubles as a feature list, which is unusual and useful, because each line names a plugin and a test count. SDK Core and Manager Integration accounts for 9 tests. Error Capture has 5, and Page Crash Detection has 2. The Console Plugin has 4, the DOM Plugin 5, the Fetch Plugin 4 and the XHR Plugin 3, so network and browser instrumentation are covered by separate plugins rather than one catch-all. Customer Events has 6, so the SDK can carry your own business events rather than only technical ones. Performance Metrics has 5, Recording Plugin 3, Routing Plugin 5 and Vue Plugin 3. The Routing plugin is what lets the SDK follow single page application navigation, and the Vue plugin is framework specific instrumentation. The documentation notes that the end-to-end suite covers SDK core functionality, all plugins and manager integration, with detailed documentation in e2e/README.md.

A manager sits between the plugins and the client

The test coverage names SDK Core and Manager Integration as a single category with the largest number of tests, which tells you there is a manager component distinct from the plugins themselves. The client packages are separate from the plugin packages in the workspace layout, and the plugin set is described as pluggable, so the plausible architecture is that plugins register into a manager that decides what to collect and hands it to a client for transport. The repository does not spell out the manager interface, so the details of how a plugin is registered, how the manager selects one plugin over another and what a plugin receives as context are things you would read in the code or on the documentation site. What the repository does tell you is that the plugins are separate packages that build independently, and the client is a separate package as well, so swapping the transport is a package choice rather than a rewrite.

Running it locally means MySQL, RabbitMQ and Prisma

The preparation step is specific and worth noting before you start. Make sure MySQL and RabbitMQ are installed, and the local MySQL service should be started on host localhost and port 3306. The database is initialised through a Prisma script, and the documentation says this automatically creates a database named test_base for debugging:

pnpm run prisma

The root package.json shows what that script does, since it is a filtered call into the server package: pnpm --filter @heimdallr-sdk/server prisma. So there is a server package inside the workspace that owns the schema, and the MySQL requirement comes from the server side rather than from the browser SDK. RabbitMQ is the other piece of infrastructure, which is the queue between the SDK and the server, so an architecture with a broker in the middle rather than a direct browser to database path. The environment section pins node version 20.16.0 and pnpm as the script runner, and the root package declares packageManager [email protected], so a mismatched pnpm version is the first thing to get right.

The build produces one package at a time or all of them

The build section is a two-level arrangement that reflects the monorepo structure. Installation dependency is the same pnpm install command as the dev step, but pointed at the npmmirror registry, which is a Chinese mirror and a common choice for speed in that region. To build a single package you filter by name, and the example given is the browser package:

pnpm --filter @heimdallr-sdk/browser run build

To build everything you run the root build script, which the root package defines as cross-env NODE_ENV=production node ./scripts/run.js, a small Node script rather than a shell chain, and the dev script is the same with NODE_ENV=development. The compiled output is bundled with rollup, since the repository carries rollup.config.base.js as a shared base configuration, and the topics list includes rollup. The bundle format comes from the package metadata, with a main of index.js and a types of index.d.ts, and the files array excludes tests, scripts, src and config files from the published tarball so consumers get the built output rather than the sources.

End-to-end tests are Playwright driven and need a real database

The test setup is heavier than a typical library, and that is a direct consequence of the architecture. The prerequisites are MySQL running at localhost:3306 with the database test_base, Node.js 16 or newer and pnpm 9.7.1 or newer. First time setup installs dependencies, runs a test:setup script that generates the Prisma client from the playground server schema and installs the Chromium browser for Playwright, and creates the database if it does not exist:

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS test_base;"

The test scripts are separated into convenience wrappers around one Playwright config. The root test script runs setup and then the suite, test:e2e skips setup and is described as the one used by CI, and there are variants for the interactive UI, debug mode, headed mode and viewing the report. A project that wants to run this suite needs a database it can create and drop schemas in, which is a constraint on where continuous integration runs. The upside is that the tests exercise the plugins in a browser against a real backend rather than against mocks, which is what makes the end-to-end counts in the coverage list meaningful.

The repository is private-rooted and releases through changesets

A few packaging details tell you how this project is meant to be consumed. The root package.json carries the name heimdallr-sdk but also private set to true and version 0.1.4, so the root is a workspace container rather than a published artefact, and the version there tracks the workspace rather than a release. The repository has no GitHub releases. What it does have is a .changeset/ directory and a set of changeset scripts in the root package, cs for changeset, uc for changeset version and release for changeset publish with public access, so individual packages inside the workspace are published to npm with their own versions and their own changelog entries. There is also a .versionrc file and a gc script that calls a commit script, and commitlint with a configuration file plus a lint-staged setup and husky hooks for pre-commit. The .npmrc and pnpm-workspace.yaml sit alongside. The result is a release process where a single plugin can ship without the whole monorepo moving, which is the right shape for a plugin system but requires a workspace-aware release discipline.

Where heimdallr-sdk is the wrong choice

Three situations argue against it. The first is a team that wants a monitoring dashboard next week. What this repository provides is the SDK side of a monitoring system, and the E2E tests reference a mock app, a playground and a server package, so a complete deployment is a multi-service project with MySQL and RabbitMQ, not a dependency. A hosted error and performance service gives you the collection, the dashboards, the alerting and the retention, and the operational cost of running your own is where the time goes. The second is a project that only needs one thing. If the requirement is a global error handler and a performance beacon, a single tracking script or one of the many vendor SDKs covers it in an afternoon, and a monorepo with its own backend is a different order of undertaking. The third is a team that cannot run a broker. RabbitMQ in the middle is a deliberate choice for absorbing burst traffic from many clients, and it is a service to deploy, secure and monitor. There is also a maturity point to weigh. The root version is 0.1.4, the repository publishes no GitHub releases, and the last push was on 2026-08-22, so the code is recent but the versioning signals a project still finding its shape. The licence is MIT, which removes any obstacle to using it, and the documentation site is the place to check what the current package set actually offers before you commit to it.

Editorial conclusion

Adopt heimdallr-sdk if you want to run your own front-end monitoring stack with plugins you control and a backend you host, and pick a hosted error and performance service if you need dashboards and alerting on day one. Verify first which browser and mini program packages the current version publishes, since the repository is a monorepo with no GitHub releases and the root package is marked private, and read the documentation site before assuming the plugin set is stable.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. LucivHuang/heimdallr-sdk on GitHub
4. Project website
5. README