WordPress Playground Integration Planning

[bengreeley]

This issue is meant for planning purposes of possible integration with WordPress Playground

Considerations:

• Setting/configuring default data
• Importing default data (https://github.com/WordPress/wordpress-playground/issues/115)
• Leveraging the existing Starter Content functionality for themes
• Opt-in vs opt-out process for theme and plugin authors
• How to handle themes and plugins that are dependent on other plugins
• Rollout process

[adamziel]

I'm glad to see this issue! Here's some notes:

Setting/configuring default data

A PHP script coming from a plugin developer would do the trick – Playground can execute PHP code after all.

Importing default default data

One approach would be to allow developers to upload a bundle of starter content/data. @artemiomorales is exploring import/export support to make this possible.

Leveraging the existing Starter Content functionality for themes

I'm not familiar with the details of the Starter Content feature, but just noting that some non-block themes can already set up the starter content: https://wasm.wordpress.net/wordpress.html?theme=pendant

How to handle themes and plugins that are dependent on other plugins

Developers should have to declare the dependencies somewhere. Perhaps this could be solved on the ecosystem level by introducing plugin.json or a similar construct? Plugins are de-facto packages after all.

[adamziel]

Big picture-wise, I imagine a "Live Preview management" UI where the developers could:

• Find the docs and learn everything they need to know about the process
• Turn the live preview on or off
• Add a preconfiguration PHP script
• Add a starter content bundle as a zip file – with instructions on how to prepare one and how to test it locally before uploading
• Declare dependent plugins
• Choose the default theme for the demo

Thinking a step further, there could be a generic "WordPress Playground package" format (like a .phar archive) that would encompass all of the above and would benefit from local development tools.

[dd32]

Just noting:

• Theme guidelines don't allow themes to require plugins. They can encourage it, but can't require it.
• Blueprints are not ideal for live previews, as implemented for plugins, and initial implementation for themes in #118
  • This is due to the time taken to setup the site from scratch each time, and imports being a bad experience with WXR currently
  • Block Themes don't have an easy way to use Starter Content or define templates in a blueprint without custom PHP.
  • Any assets can't be included in a blueprint, and usually end up stored on GitHub.
  • Creating JSON isn't very friendly for many people.

there could be a generic "WordPress Playground package" format (like a .phar archive) that would encompass all of the above and would benefit from local development tools.

This would be ideal, although my notes:

• Todays Playground supports an Import/Export as .zip which works well for this
• That isn't perfect for our use-case, as..
  • We probably want to allow upload of a .zip, but we'll want to discard all themes/plugins included within
    • Maybe we'd allow w.org hosted plugins..
    • That means the only thing we'd actually want from the archive is probably the Database + any uploaded assets.
  • Inject the latest version of the theme (and it's parent) / plugins (if w.org hosted are added..)
  • We'd need to run certain actions to ensure our custom plugins are loaded when needed
    • I guess this would just be us injecting our plugins, and then an mu-plugin to ensure they're loaded (or probably just injecting them as mu-plugins now that I think about it)
    • With Blueprints we just run our actions first & last, but I guess mu-plugins probably covers our needs.

So thinking about this... That would be:

• Allow upload of an export
• Process of upload to determine the included plugins, take note of the ones we want to include, discard all themes
• Store it somewhere
• Allow download of the export, dynamically inject the theme & it's parents, inject our mu-plugins, inject any w.org plugins we determine we want to allow
• Have the preview bootup be:
  • Install WP, overlay preview zip
  • Currently AFAIK this would install WP, then we'd overwrite the DB with the preview one.
  • This wouldn't be significantly faster than using a Blueprint today, except in the case of WXR imports and Block Themes that need DB customisations.

Bigger picture, It does make me question if this is actually a Theme Preview problem though ultimately; perhaps theme previews are just a subset of Playground Demo's, WordPress sites that we have in a directory as a starting point for new WordPress sites. They would include Blueprints, and full exports with DB/etc (which again, like above we'd probably want to inject the latest versions at download time, cached per day).

[adamziel]

@dd32 So the overall goal here is snappy theme preview loading, right?

Would the step you listed happen server-side with a cronjob? Or in the browser? For the former, Playground CLI + some custom scripting could help. For the latter, a export.zip -> sanitized-theme-preview.zip Blueprint + an additional "path allowlist / denylist" option in the import zip step would perhaps do the trick.

However, I wonder if that wouldn't actually slow down the boot once Offline Mode support lands. That's because after the initial load, your browser will source PHP and WordPress.zip from cache, so serving a new .zip bundle with all WordPress core files would add to the overall transfer size. Looping in @bgrgicak

Bigger picture, It does make me question if this is actually a Theme Preview problem though ultimately; perhaps theme previews are just a subset of Playground Demo's, WordPress sites that we have in a directory as a starting point for new WordPress sites. They would include Blueprints, and full exports with DB/etc (which again, like above we'd probably want to inject the latest versions at download time, cached per day).

Yes, I think that's a more general Playground apps problem. I hope the offline mode will greatly speed it up.

[dd32]

@dd32 So the overall goal here is snappy theme preview loading, right?

Yes, to reduce the speed of loading as much as possible. I wasn't aware of Offline mode, but I don't think it impacts too much.

Would the step you listed happen server-side with a cronjob? Or in the browser?

Probably it would be that the theme author would upload a ZIP, sourced from a playground instance Export option.

For the latter, a export.zip -> sanitized-theme-preview.zip Blueprint + an additional "path allowlist / denylist" option in the import zip step would perhaps do the trick.

That's what I was thinking; except, the path allow/deny probably wouldn't be needed, my thought was we'd take the export.zip provided, remove anything from the ZIP that's not expected (the theme, plugins, etc) and have the client download the sanitised-export.zip + theme.zip + plugin1.zip + plugin2.zip.. I guess ideally we'd have those all bundled up, but probably not viable at first.

That's because after the initial load, your browser will source PHP and WordPress.zip from cache, so serving a new .zip bundle with all WordPress core files would add to the overall transfer size.

100% We'd want the bundle to exclude the PHP/WordPress zip, and only have anything unique to the theme preview.

I hope the offline mode will greatly speed it up.

I'm not sure it will greatly, since the WordPress+PHP+Wasm+etc zips are already cached client-side. The main speed issue I've seen is just waiting for them to download on a cold-boot (Offline doesn't help that) and that it appears that WordPress is installed from scratch every boot (I didn't think that would be a speed issue,and I'm not certain it is, other than that after the ZIPs download there's a second or two while it's "setting up WordPress")

[bgrgicak]

However, I wonder if that wouldn't actually slow down the boot once https://github.com/WordPress/wordpress-playground/issues/133 support lands. That's because after the initial load, your browser will source PHP and WordPress.zip from cache, so serving a new .zip bundle with all WordPress core files would add to the overall transfer size. Looping in @bgrgicak

This isn't necessarily related to offline and could be considered an issue today.

We download WordPress here and it looks like the only thing that disables the download is if WordPress is available in OPFS.

If we want to avoid downloading WordPress twice, we could use the prefferdVersions.wp with a URL to download a customized version or WordPress. Example blueprint.

These ZIPs wouldn't be cached because they don't come from the Playground.WordPress.net, but that could be improved in the future.

100% We'd want the bundle to exclude the PHP/WordPress zip, and only have anything unique to the theme preview.

That would resolve the issue.

[adamziel]

Playground now supports offline mode. PHP and WP are downloaded just once, additional bundles like plugins and themes are a subject to HTTP caching. This doesn't help with a cold load, but it helps with subsequent loads.

From here, there's a few ways to reduce the initial download size. One is what you outlined @dd32, it seems like there are no technical blockers for this. Another would be pre-rendering the theme as a static site using Playground CLI and shipping that. There's also a hybrid approach where we'd still load Playground and the theme, but all the images and CSS files would be fetched from the remote server instead of being shipped with the initial theme.zip.

[richtabor]

What's the difference between previewing a theme and previewing a plugin?

We could just add a "Open in WordPress Playground" button if a blueprint is available. That would set expectations that you will wait for something more. And just keep the existing preview button for now.

Then if we get blueprints loading quicker, just use the Preview button.

[dd32]

What's the difference between previewing a theme and previewing a plugin?

The primary difference is that Themes almost 100% require additional content be installed, which may include images, which is significantly slower to provision than plugins.

If we were adding plugin previews with playground today, I'm not 100% that blueprints would be the right option either, it may be that any theme preview functionalities are ported back over to plugins too.

[adamziel]

@dd32 What would you say is the largest blocker for this today, assuming the extra content like images may be referenced from an external URL without frontloading them in Playground?

[dd32]

@adamziel I'm not sure. I suspect the biggest blocker that I'm aware of is an easy way to boot up a WordPress instance with a defined DB rather than the builtin. I'm sure there's a way to do it, but I'm not aware off the top of my head of how to using vanilla playground.

(ie. Last I looked, there wasn't a clear way to boot a Playground instance to resume a saved state / export, you boot, then import zip and overwrite the initialised environment)

[adamziel]

@dd32 there's a few ways to approach this:

1. Export a Playground instance as a zip, host that zip somewhere, load it through the API. I did that for the slides example at https://github.com/adamziel/playground-sites via the import-site query API parameter: https://playground.wordpress.net/?login=no&import-site=https%3A%2F%2Fraw.githubusercontent.com%2Fadamziel%2Fplayground-sites%2Fmain%2Fplayground-for-site-builders%2Fplayground.zip
2. Setup a Blueprint to define the desired DB state. I'm not sure if that would do the trick, though, maybe there's too much to do to reasonably encode it as a Blueprint.
3. Prepare a database file and prepare a Blueprint that replaces the Playground SQLite database file with your custom file using the writeFile Blueprint step.

Is this what you've had in mind? I know @annezazu and @juanmaguitar also explored restoring the Playground site from a ZIP export.

[dd32]

I wasn't aware of the importSite option. I think that would meet most of the need here.

It looks like under the hood this just maps to the importWordPressFiles blueprint step, so we'd probably be using a Blueprint that did... steps: [ { ..importWordPressFiles...}, { ...login... }, { ...installTheme... } ], which would do what we needed here.

[annezazu]

Yes! I use this option a fair amount. Most recently: https://nomad.blog/2024/08/29/join-me-in-testing-block-bindings-api/ Makes it super easy to offer ways for folks to help test.

[adamziel]

Yay! If I understand correctly, this is unblocked now 🎉