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