My Jetpack: Finish the onboarding setup wizard by adampickering · Pull Request #52775 · Automattic/jetpack

adampickering · 2026-09-24T20:07:33Z

Fixes #

Proposed changes

This is now the whole onboarding wizard in one PR, so it can be tested and reviewed as final code. It builds on #52765 (merged) and folds in #52844 (the animation), #52842 (tracking), #53750 (lazy loading) and #53880 (the WordPress 7.0 fix), plus the design-system changes from @simison's review. Everything is behind the my-jetpack-onboarding-wizard flag. With the flag off, the only change is a smaller onboarding bundle. The wizard only runs when the Jetpack plugin is active, since the features step switches Jetpack modules. Sites with only standalone plugins keep the single connect screen.

The steps

Step 2, "What's this site for?" The answer reorders the feature list. "Something else" opens a free-text field.

Step 3, the feature list. Six modules: Stats, Forms, Brute Force Protection, Activity Log, Newsletter, Downtime Monitor. Each switch starts at what the site already runs, so nothing changes unless the user moves one. A module the host forces shows a locked switch. Continue waits until the module list has loaded. They're Jetpack modules, not My Jetpack feature cards: the Protect card would install the standalone Protect plugin, Downtime Monitor has no card, and modules give all six one control with names and descriptions from Jetpack itself.

Step 4, the finish. It reports what each switch actually did, read back from the requests. A module that failed gets "Some features need another look" and says so in its own row. "Nothing changed on your site" is only for a run that moved nothing and runs nothing; otherwise it's "You're all set", with a line saying what setup switched on or off.

The panel. A "publish everywhere" composition (everywhere.tsx) beside the site question and a "data in" one (data-in.tsx) beside the feature list. Both build in once and settle, since looping beside a form with no pause control would fail WCAG 2.2.2. Reduced motion gets finished frames. The start step keeps the Jetpack mark drawing in, and the finish step has no panel.

A run survives a reload. The step, answers and switches are held in sessionStorage and read back through clampStep(), so a corrupt value can't land on a step that doesn't exist. It never reopens the finish step, and goes back to the connect step if the user is no longer connected. Every control waits while modules are being switched or the user is on the way out, so nothing settles twice.

The full-window layout is the wizard's own. The takeover styles hang off a jetpack-onboarding-wizard body class the wizard sets while it's open, so the single connect screen (flag off, or the fallback below) keeps trunk's styles and scrolls.

Built from the design system

The switches are the @wordpress/ui Switch. They and the green buttons get their colour from a ThemeProvider seeded #008710 (--jp-green-50) instead of overriding @wordpress/ui internals. The rail head, the finish screen and the connected notice lay out with Stack, and the finish summary is a Card rendered as a list. Continue keeps one small override for its disabled state: the generated pair is 2.7:1, and it keeps the 4.2:1 one.

Loading only when the flag is on

Every site loads the onboarding bundle, flag or not, and the wizard's art alone is about 270 KB, which @kraftbj caught. The wizard now loads with React.lazy as its own onboarding-wizard.js chunk, only when the flag is on. With the flag off, here's what the onboarding screen loads (production build, gzipped in brackets):

File	trunk	This PR
`onboarding.js`	262,199 B (62,143)	105,468 B (38,650)

With the flag on, onboarding-wizard.js (540,762 B, 149,347 gzipped) and onboarding-wizard.css (23,592 B) load after it. That chunk carries the wizard, its art, @wordpress/ui and the bundled @wordpress/theme, and onboarding.asset.php no longer depends on wp-theme.

public-path.ts is the first module of the onboarding entry and sets webpack's public path from a new webpackPublicPath initial-state value, the way Comments and Forms do, since webpack's 'auto' guess breaks when another plugin combines scripts.
If the chunk fails to load, the page logs why and falls back to the single connect screen. Once the site is registered, that fallback keeps "Skip setup", because with the flag on My Jetpack keeps sending a site-only connection back to onboarding and the single screen alone has no way out. While the chunk loads, the window shows the wizard's dark shell.

WordPress 7.0

The wizard imports ThemeProvider from @wordpress/theme, which the default config takes from core's wp-theme script. On WordPress 7.0 that script exports only privateApis, with ThemeProvider locked inside, so the wizard threw "Element type is invalid" and the page stayed blank. 7.1 added the public export. My Jetpack now bundles @wordpress/theme with bundleWpUiDeps: true, as Boost, Protect and the Jetpack plugin already do. The webpack-config README warns against that option for entries that unlock private APIs from an external wp-* script, and none of My Jetpack's entries do. Since the wizard is lazy-loaded, the extra code ships in its chunk, not in onboarding.js. This was already on trunk from #52765, behind the flag, thanks to @LiamSarsfield for catching it.

Related product discussion/links

Builds on My Jetpack: add a setup wizard shell behind a feature flag #52765 (merged). Folds in My Jetpack: animate the onboarding panel beside each step #52844, My Jetpack: report what happens in the onboarding wizard #52842, My Jetpack: load the onboarding wizard in its own chunk #53750 and My Jetpack: Fix the onboarding wizard crashing on WordPress 7.0 #53880.
Reviews from @kraftbj, @simison and @LiamSarsfield on this PR and the ones folded in.

Does this pull request change what data or activity we track or use?

Yes, while the my-jetpack-onboarding-wizard flag is on. Every event carries the run's flow_id and the step's slug on top of what useAnalytics already adds.

Event	Fires	Its own properties
`jetpack_my_jetpack_onboarding_wizard_step_view`	a step becomes visible	none
`jetpack_my_jetpack_onboarding_click`	"Get started" is clicked (shared with the single-screen flow)	`flow: 'wizard'`
`jetpack_my_jetpack_onboarding_connect_error`	registration or the hand-off fails	`error_code`
`jetpack_my_jetpack_onboarding_wizard_site_type_select`	an option is chosen	`site_type`
`jetpack_my_jetpack_onboarding_wizard_site_type_detail`	Continue on the site-type step, only for "Something else"	`length_bucket`
`jetpack_my_jetpack_onboarding_wizard_module_toggle`	a switch moves	`module`, `enabled`
`jetpack_my_jetpack_onboarding_wizard_step_complete`	Continue advances	none
`jetpack_my_jetpack_onboarding_wizard_apply_result`	the module switches resolve	`offered`, `switched_on` (by this run only), `failed`
`jetpack_my_jetpack_onboarding_wizard_complete`	the user finishes	`site_type`
`jetpack_my_jetpack_onboarding_wizard_skip`	the user skips or leaves	none

There's no abandonment event. Abandonment is a step_view with no later complete or skip for the same flow_id.
A successful connection is calypso_jpc_authorize_success on WordPress.com, which already carries from: jetpack-onboarding-wizard. connect_error stays until CONNECT-502 has the connection package record registration failures itself.
The step is a slug, never an index, because a connected site opens on the second step.
The run id lives in sessionStorage, so the two halves of a run on either side of WordPress.com can be joined. It ends when the user leaves the wizard, and is none where storage is blocked.
What someone types about their own site never leaves the browser. Only a length bucket is sent, and a test checks every call the wizard makes for the text.
Tracks silently drops events whose name or property keys miss its rules, so tests check every name and every key a full run records.
Tracks only loads once the site has agreed to the terms or has a connected user, so the start screen's events on a fresh install are never sent. The connect step's denominator has to come from the server side.

None of the events are registered yet. They'll be registered once they've fired from a flag-on test site.

It also changes site state: the six modules are switched to match what the user left the switches at, through the same activation queue the rest of My Jetpack uses.

Testing instructions

Build My Jetpack (jp build packages/my-jetpack) and turn the flag on in a mu-plugin:

add_filter( 'jetpack_feature_flag_enabled_my-jetpack-onboarding-wizard', '__return_true' );

Open "Jetpack → My Jetpack" on a disconnected self-hosted site with the Jetpack plugin active, in a window at least 1280px wide, with the Network tab open, and connect.

onboarding-wizard.js and onboarding-wizard.css load right after onboarding.js, from the same build/ folder.
Step 2. Pick a site type. The panel builds in once and stops. Pick "Something else" and the text field appears.
Step 3. Six rows with Jetpack's own names, each switch matching what the site runs. On a fresh site Downtime Monitor starts off, and the list order follows the site type.
Turn Downtime Monitor on and continue. The finish screen says setup switched it on, and it really is on (check Jetpack → Settings). Leave everything alone and nothing is switched.
Reload mid-run. You stay on the same step with the same answers.
Step 4. "You're all set" with each row's real result. "Go to My Jetpack" and "Back to your WordPress site" both finish the run once, however many times you click.
Watch window._tkq through the run: one flow_id, step as a slug, and for "Something else" a length_bucket but never a word of what you typed.
Turn on Reduce motion in your OS. Both panels render finished, and the finish mark doesn't animate.

On WordPress 7.0 (wp core download --version=7.0 --force, with Gutenberg inactive, since it replaces wp-theme), the wizard renders and the console has no errors. On trunk the page is blank.

Flag off:

You get the single "Start with Jetpack for free" screen, and it scrolls in a short window.
No onboarding-wizard files load.

Flag on with only a standalone plugin (Boost, Protect…) and no Jetpack plugin: you get the single screen, not the wizard.

jp test js packages/my-jetpack covers the steps, the saved run, the exits, the tracking and the chunk fallback. public-path.ts has no unit test, since it only does something when a browser loads the wizard's chunk, which the steps above check. That's why this PR has the "Covered by non-unit tests" label.

github-actions · 2026-09-24T20:08:48Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the add/my-jetpack-onboarding-steps branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/my-jetpack-onboarding-steps

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2026-09-24T20:09:17Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Jetpack plugin:

No scheduled milestone found for this plugin.