automattic / jetpack-premium-analytics

v0.9.0 2026-09-29 00:40 UTC

Requires

• php: >=7.4
• automattic/jetpack-admin-ui: ^0.14.1
• automattic/jetpack-assets: ^5.0.7
• automattic/jetpack-config: ^4.0.0
• automattic/jetpack-connection: ^9.8.0
• automattic/jetpack-feature-flags: ^0.2.0
• automattic/jetpack-stats: ^0.22.0
• automattic/jetpack-status: ^7.1.0
• automattic/jetpack-sync: ^5.3.0
• automattic/jetpack-wp-build-polyfills: ^0.6.0
• automattic/woocommerce-analytics: ^0.17

Requires (Dev)

• automattic/phpunit-select-config: ^1.0.11
• yoast/phpunit-polyfills: ^4.0.0

GPL-2.0-or-later

Published on Packagist.org on 2026-09-29 00:41 UTC

README

A portable analytics dashboard for WordPress sites with Jetpack connection. Renders as an SPA inside wp-admin using route-based code splitting.

How it works

 Analytics::init()
       │
       ├── loads build/build.php (generated by @wordpress/build)
       ├── registers jetpack-premium-analytics-wp-admin
       │   gated by jetpack_view_analytics
       │
       ▼
  @wordpress/boot          ← SPA shell and routing
       │
       ▼
  routes/<name>/stage.tsx  ← each route is a lazy-loaded ES module

Boot mounts inside the standard admin chrome; routes are discovered at build time from package.json metadata.

The generated full-page variant is disabled; only the registered, capability-gated admin page serves the dashboard.

Documentation

• Dashboard sections: how a section is registered, filtered, served to the client and rendered, and how another plugin registers one.
• Dashboard widget types: how a widget type is registered, filtered, served to the client and imported, and how another plugin registers one.

Extending the dashboard from another plugin

The package owns the dashboard, not the features. A section and its widgets belong to the code that knows the feature is there, and jetpack-mu-wpcom registers on WordPress.com Simple and Atomic where that fact is a plan feature.

A plugin extends the dashboard from two actions. Each fires once, when its registry hydrates on the first read after init.

Sections

Hook jetpack_premium_analytics_register_dashboard_sections and call register_dashboard_section() with the section's label, availability rule and default layout. See Dashboard sections.

Widget types

Hook jetpack_premium_analytics_register_widget_types, compare WIDGET_API_VERSION, require the build/build.php wp-build generated for your widgets/ folder, and call register_widget_types_from_manifest() with its manifest, your text domain and the URL of your i18n-manifest.json. See Dashboard widget types.

Your widgets import the dashboard through @automattic/jetpack-premium-analytics-sdk (projects/js-packages/premium-analytics-sdk). Your build keeps that import external, and the dashboard page's import map resolves it to the module this package registers.

The reference consumer

projects/packages/ads: the Ads section and its three widgets, called by the WordAds module of the Jetpack plugin and by jetpack-mu-wpcom. Report pages and detail routes are the next contract; today they are the package's own.

Requirements

• PHP >= 7.4
• WordPress core or Jetpack's wp-build polyfills provide the WordPress script handles/modules used by the dashboard. The Gutenberg plugin is not required.

Development

pnpm run build             # one-off build
pnpm run watch             # rebuild on file changes
jetpack build packages/premium-analytics   # via Jetpack CLI

Adding a route

1. Create routes/<name>/package.json:

   {
   	"name": "<name>-route",
   	"route": {
   		"path": "/<name>",
   		"page": "jetpack-premium-analytics"
   	}
   }

2. Create routes/<name>/stage.tsx exporting stage():

   export const stage = () => <div>My new page</div>;

3. Rebuild — routes are auto-discovered from package.json metadata.

Known issues

Boot asset shim

@wordpress/build 0.10+ stopped bundling @wordpress/boot locally, but the generated page.php template still looks for modules/boot/index.min.asset.php to resolve classic script prerequisites. Without it the page is blank.

Package automattic/jetpack-wp-build-polyfills provides a fixed version.

Init module (packages/init/)

Serves two purposes:

1. Sets the dashboard menu icon via @wordpress/boot store
2. Forces @wordpress/build to track @wordpress/boot as a module dependency — without an init module that imports boot, the build skips it

File structure

premium-analytics/
├── src/
│   └── class-analytics.php    # PHP entry: loads build, registers menu
├── packages/
│   └── init/                  # runs before routes render
├── routes/
│   └── dashboard/             # dashboard route (/)
│       └── stage.tsx
├── shims/
│   └── boot-asset.php         # boot prereqs workaround
├── composer.json              # automattic/jetpack-premium-analytics
├── package.json               # @wordpress/build config
└── build/                     # generated (gitignored)