mirror
/
analytics
mirror of https://github.com/plausible/analytics.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
analytics/tracker/ARCHITECTURE.md

4.5 KiB
Raw Blame History

Architecture

This document describes the design goals informing the architecture of the Plausible tracker script codebase as well as a map to how the code is laid out.

Installation Support

The tracker subdirectory also includes site verification and pre-installation checks that are run in headless browser, via browserless.io. These files live under the /tracker/installation-support/ director and are meant to provide Plausible installation support - checking the site for what technologies to recommend and verifying whether Plausible has been installed correctly. Please see lib/plausible/installation_support/checks/installation.ex for the Elixir context and how this JS code ends up being used.

While this logic could be separated from the tracker script, it's convenient for installation support to reuse the Playwright test structure and JS compilation logic without introducing yet another subdirectory with its own dependencies.

Design goals

We want to provide users a javascript suite to capture page views and activities done on the web page.

Over time, the following key design goals have emerged:

1. Minimal script size

Smaller scripts lead to better user experience and reduce the amount of data we miss due to script download and runtime.

We minify our scripts using the speedy @swc/core library and track script size changes on every pull request.

2. Many targets, single codebase

Plausible provides a web 'snippet' users can include on their site, tooling for wordpress and other plugins as well as an npm package.

As Plausible doesn't have the workforce to maintain multiple code bases, everything is built from the same underlying source code.

This is achieved by:

  • Having a canonical list of compiled variants in tracker/compiler/variants.json
  • Using COMPILE globals to toggle certain functionality on/off depending on the variant.
  • Having the script minifier drop dead branches of the code from each variant.
  • Having compile.js compile all needed variants

3. Flexible user configuration

Rather than capturing everything, we want to provide configurability allowing Plausible users to toggle tracking features on/off.

To make life simpler for these users, we want to allow changing configuration on web without users needing to change their integration code or deploying.

Plausible tracker endpoints dynamically interpolate site-specific configuration into the minified plausible.js. For integrations such as the wordpress plugin, we provide tooling like the plugins API.

4. Legacy support

We want to avoid intentionally breaking existing installations of the script.

In a previous version of the script, Plausible allowed toggling features by changing their script extension. We still generate and serve each of these legacy variants.

5. Great development experience

To make sure development of the tracker works like a well-oiled machine, we:

  • Ensure compilation is snappy and done in parallel. Currently compiling over a 1000 variants around 3 seconds on a development machine.
  • Use a bundler (rollup) to split code into multiple files.
  • Use automated browser-based testing to cover new functionality and changes.
  • Leverage CI-based workflows for testing and releasing each new version

Code Map

This section provides a key overview of code that is relevant to understand the tracker codebase.

tracker/src/

Contains tracker code itself which is to be compiled. plausible.js is the entrypoint during compilation.

tracker/compiler/variants.json

Contains a list of variants and associated global COMPILE flags.

  • manualVariants are the main variants we need to care for, containing both the web snippet and npm package.
  • legacyVariants is a list of all the legacy variants we support, generated by tracker/compiler/generate-variants.js

tracker/compile.js and tracker/compiler/index.js

This script is responsible for bundling and minifying each variant in parallel.

Compilation adds code under priv/tracker/js

tracker/npm_package

Contains types, package.json, README.md, CHANGELOG.md and other related files to the npm package. Does not contain the actual code which is placed there during compilation.

tracker/test/

Playwright tests. These tests usually load a specific html fixture, configure the tracker script, emulate user behavior and check what events get sent.

lib/plausible_web/plugs/tracker_plug.ex and lib/plausible_web/tracker.ex

Elixir code responsible for serving tracker script, interpolating and managing site tracker script configuration.