automattic/jetpack-premium-analytics

Premium Analytics dashboard for Jetpack sites.

dev-trunk / 0.1.x-dev 2026-04-18 14:44 UTC

Requires

• php: >=7.2

Requires (Dev)

• automattic/jetpack-changelogger: ^6.0.14
• automattic/phpunit-select-config: ^1.0.4
• yoast/phpunit-polyfills: ^4.0.0

GPL-2.0-or-later

README

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

How it works

 Analytics::init()
       │
       ▼
  build/build.php          ← auto-generated by @wordpress/build
       │
       ├── registers admin_init interceptor
       │   for ?page=jetpack-premium-analytics
       │
       ▼
  @wordpress/boot          ← full-page HTML shell, sidebar, routing
       │
       ▼
  routes/<name>/stage.tsx  ← each route is a lazy-loaded ES module

The interceptor takes over the request before WordPress renders the standard admin chrome. Boot provides the SPA shell; routes are discovered at build time from package.json metadata.

Requirements

• PHP >= 7.2
• Gutenberg plugin — provides @wordpress/boot and @wordpress/route as script modules. Required until WordPress 7.0+ ships these natively.

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 (shims/boot-asset.php)

@wordpress/build 0.10+ stopped bundling @wordpress/boot locally (expects Core 7.0+ or Gutenberg), 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.

The shim provides the dependency list. Remove it when @wordpress/build fixes the template or the minimum WordPress version is 7.0+.

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)