Add support for base64-encoded blueprints in deeplinks #2042

ivan-ottinger · 2025-11-07T14:41:17Z

Related issues

Related to STU-921.

Proposed Changes

introduce deeplink handling for base64-enocoded blueprints
extract out createBlueprintFromData and applyPreferredVersions logic
move main window focus logic
rename IPC Events
add related unit tests

ℹ️ Please note that we will be adjusting the UI/UX once the designs are ready. This PR only adds raw support for base64-encoded blueprints in deeplinks.

Testing Instructions

Check out the PR branch and build the app with npm install && npm start.
Try out the following deeplinks and confirm they do what they are supposed to do. 🙂

Broken blueprint:

wpcom-local-dev://add-site?blueprint=invalid-base64!!!

an error message in a dialog should show up

Working blueprint:

wpcom-local-dev://add-site?blueprint=eyJwcmVmZXJyZWRWZXJzaW9ucyI6eyJwaHAiOiI4LjMiLCJ3cCI6ImxhdGVzdCJ9LCJzdGVwcyI6W3sic3RlcCI6Imluc3RhbGxUaGVtZSIsInRoZW1lRGF0YSI6eyJyZXNvdXJjZSI6IndvcmRwcmVzcy5vcmcvdGhlbWVzIiwic2x1ZyI6ImFzdHJhIn0sIm9wdGlvbnMiOnsiYWN0aXZhdGUiOnRydWV9fSx7InN0ZXAiOiJpbnN0YWxsUGx1Z2luIiwicGx1Z2luRGF0YSI6eyJyZXNvdXJjZSI6IndvcmRwcmVzcy5vcmcvcGx1Z2lucyIsInNsdWciOiJ3b3JkcHJlc3Mtc2VvIn0sIm9wdGlvbnMiOnsiYWN0aXZhdGUiOnRydWV9fV19

should land right on the Add a site step
if you click the Add site button the site with the related blueprint should create itself

Test for regressions:

Follow the testing steps in Rahul's (already-merged) PR: Blueprints: Add a deeplink to create a new site from the blueprint URL #1989.
Everything should be working well.

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

github-actions · 2025-11-07T15:54:05Z

📊 Performance Test Results

Comparing cece592 vs trunk

site-editor

Metric	trunk	`cece592`	Diff	Change
load	12878.00 ms	17781.00 ms	+4903.00 ms	🔴 38.1%

site-startup

Metric	trunk	`cece592`	Diff	Change
siteCreation	28408.00 ms	28521.00 ms	+113.00 ms	🔴 0.4%
siteStartup	7969.00 ms	9013.00 ms	+1044.00 ms	🔴 13.1%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change

epeicher

Thanks @ivan-ottinger for adding this feature! I have tested it, and it works as expected. I can see the error with the invalid blueprint, and I have successfully created a site installing Pendant by using a base64 encoded blueprint in the deeplink. Code changes also LGTM!

Invalid blueprint	Blueprint installing Pendant

I have also tested any regressions and I have not found any issues 👌

gcsecsey

Thanks @ivan-ottinger for tackling this! The changes LGTM and work as described. 🎉 I was able to create a site with WooCommerce installed using this link:

wpcom-local-dev://add-site?blueprint=ewogICJwbHVnaW5zIjogWwogICAgIndvb2NvbW1lcmNlIgogIF0sCiAgInN0ZXBzIjogW10sCiAgInByZWZlcnJlZFZlcnNpb25zIjogewogICAgInBocCI6ICI4LjMiLAogICAgIndwIjogImxhdGVzdCIKICB9LAogICJmZWF0dXJlcyI6IHt9LAogICJsb2dpbiI6IHRydWUKfQ==

ℹ️ Please note that we will be adjusting the UI/UX once the designs are ready. This PR only adds raw support for base64-encoded blueprints in deeplinks.

As we discussed on the meetup last week, I added this issue for the UI tweaks, and assigned you.

gavande1 · 2025-11-18T08:36:51Z

@ivan-ottinger Thank you for working on this. It works as expected. I have a suggestion from a technical implementation perspective. Instead of adding additional code to handle the base64 blueprint directly, how about saving the decoded content to a temporary JSON file and then reusing the existing logic that already handles blueprint paths via the IPC event? This approach should allow us to remove a significant amount of new code in this PR and rely on the established flow.

Here is a simple outline of the idea:

Add a new parameter blueprint to the deeplink listener
In the handler, check whether it is a base64 encoded blueprint
If it is, decode it and save it as a temporary JSON file
Once the JSON file is saved, reuse the existing logic that is triggered by a blueprint URL

What do you think about this approach?

cc @gcsecsey

ivan-ottinger · 2025-11-18T10:27:03Z

Thank you for your reviews and testing, Roberto, Gergely and Rahul!

It works as expected. I have a suggestion from a technical implementation perspective. Instead of adding additional code to handle the base64 blueprint directly, how about saving the decoded content to a temporary JSON file and then reusing the existing logic that already handles blueprint paths via the IPC event?

What do you think about this approach?

I think that could work well too!

What I am thinking is to merge this PR as-is and then create a subsequent one with a refactor - as I was planning to update the step handling as well (as currently the blueprint that is linked in the URL goes to the "choose a blueprint" step - as opposed to the Add site step).

gavande1 · 2025-11-18T10:36:36Z

What I am thinking is to merge this PR as-is and then create a subsequent one with a refactor - as I was planning to update the step handling as well (as currently the blueprint that is linked in the URL goes to the "choose a blueprint" step - as opposed to the Add site step).

Sure thing. Feel free to merge this and iterate on it later.

wojtekn · 2025-11-21T15:02:06Z

src/lib/deeplink/handlers/add-site-blueprint-with-url.ts

+			JSON.parse( blueprintJson );
+			await sendIpcEventToRenderer( 'add-site-blueprint-from-base64', { blueprintJson } );
+		} catch ( error ) {
+			Sentry.captureException( error );


Do we need to track such errors in Sentry? How would we use them?

Yes, no need for that. I have already removed the logging in the refactor PR: #2103.

ivan-ottinger self-assigned this Nov 7, 2025

ivan-ottinger marked this pull request as ready for review November 7, 2025 15:34

ivan-ottinger mentioned this pull request Nov 7, 2025

Blueprints: Add base64 deeplink blueprint handling (exploration) #1951

Closed

1 task

ivan-ottinger requested a review from a team November 7, 2025 15:37

epeicher approved these changes Nov 17, 2025

View reviewed changes

gcsecsey approved these changes Nov 17, 2025

View reviewed changes

ivan-ottinger force-pushed the add/blueprint-from-base64-handling branch from 1f95f35 to d35c230 Compare November 18, 2025 10:30

ivan-ottinger added 6 commits November 18, 2025 12:21

Add support for base64-encoded blueprints in deeplinks

1b8bddd

Restore and focus window before processing blueprint

fb7896f

Remove redundant mainWindow variable declaration

952f870

Update default blueprint description text

1b21fdf

Add error dialog for invalid blueprint data

d9c8a7b

Verify error dialog shown when base64 blueprint is invalid

f4cbcc7

ivan-ottinger force-pushed the add/blueprint-from-base64-handling branch from d35c230 to f4cbcc7 Compare November 18, 2025 11:21

Remove eslint-disable comment from add-site test file

bf3698c

ivan-ottinger merged commit 15b46a7 into trunk Nov 18, 2025
6 of 11 checks passed

ivan-ottinger deleted the add/blueprint-from-base64-handling branch November 18, 2025 11:55

wojtekn reviewed Nov 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for base64-encoded blueprints in deeplinks #2042

Add support for base64-encoded blueprints in deeplinks #2042

Uh oh!

ivan-ottinger commented Nov 7, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 7, 2025 •

edited

Loading

Uh oh!

epeicher left a comment •

edited

Loading

Uh oh!

gcsecsey left a comment

Uh oh!

gavande1 commented Nov 18, 2025 •

edited

Loading

Uh oh!

ivan-ottinger commented Nov 18, 2025 •

edited

Loading

Uh oh!

gavande1 commented Nov 18, 2025

Uh oh!

Uh oh!

wojtekn Nov 21, 2025

Uh oh!

ivan-ottinger Nov 21, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Add support for base64-encoded blueprints in deeplinks #2042

Add support for base64-encoded blueprints in deeplinks #2042

Uh oh!

Conversation

ivan-ottinger commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

github-actions bot commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

site-editor

site-startup

Uh oh!

epeicher left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gcsecsey left a comment

Choose a reason for hiding this comment

Uh oh!

gavande1 commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ivan-ottinger commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gavande1 commented Nov 18, 2025

Uh oh!

Uh oh!

wojtekn Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

ivan-ottinger Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ivan-ottinger commented Nov 7, 2025 •

edited

Loading

github-actions bot commented Nov 7, 2025 •

edited

Loading

epeicher left a comment •

edited

Loading

gavande1 commented Nov 18, 2025 •

edited

Loading

ivan-ottinger commented Nov 18, 2025 •

edited

Loading

ivan-ottinger Nov 21, 2025 •

edited

Loading