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)