Snapshots Support

[adamziel]

Let's define the relationship between Snapshots and Blueprints.

• When writing Blueprints, it's useful to include some files, e.g. private plugins. If Blueprints required shipping them in wp-content/plugins, that starts resembling a Snapshot.
• A Snapshot exported from WordPress could include a Blueprint like {"theme": "twentytwentythree"} instead of shipping the actual files. That's a smaller archive and an up-to-date theme import.

Blueprints and Snapshots are a spectrum, not distinct ideas

The smallest WordPress setup description is an empty Blueprint {}.

The most extensive description is a full Snapshot + Playground binary bundled as a double click executable – click, and that exact site runs on your computer.

There's so much in between, though:

• A Blueprint file with some plugins, themes, and site options
• A Blueprint file + a wp-config.php
• A Blueprint file with a few plugins + wp-content with more plugins and themes
• A full snapshot with a Blueprint to update the WordPress version

[adamziel]

Here's an article I once wrote about Snapshots:

Playground as the WordPress export format

I propose Playground-powered WordPress Snapshots as the canonical site export format for WordPress core.

A Playground export already enables what no other export format may ever be able to do:

• Preview the exported site
• Edit the exported data without breaking it...
• ...using the editors and UI built specifically for that
• Preserves data, files, plugins, custom database tables
• Removes any PHP and database version compatibility issues
• Keeps producing what was there at the time the export was created
• Is usable in a vanilla browser, local dev env, or even on a mobile device

What inside the Playground export today?

An exported Playground site is a zip with wp-config.php and the wp-content directory. You can import that zip into Playground, run it locally in wp-now, or turn it into a real site using Playground CLI.

I think it would be more useful as a complete WordPress site with all WordPress core files in it. This way, that snapshot would just work without any additional downloads. It could be bundled with Playground as a single executable and would continue to work 10 years from now.

What else is possible with more work?

Playground itself, complete with the portable PHP binary, could be bundled with the exported Snapshot. This would make the export self-contained and usable locally, on any device, and independently from playground.wordpress.net.

WordPress could export itself into the Snapshot format. This would instantly unlock spinning a "temporary test copy" of your site.

WordPress could import from Snapshots to enable easy site transfers and easy "committing" of the changes from the test site.

The above features would also unlock "site templates" that you could turn into real WordPress sites with a few clicks.

What's wrong with WXR, XML, CSV, JSON, Markdown, etc?

Nothing. These are great formats for exporting content.

However, they aren't well suited for exporting entire sites. Exporting an entire site as XML or JSON is lossy and requires more work than just exporting an entire site.

What about advanced setups that require, e.g., Redis?

They won't be supported initially. Eventually, WebAssembly may replace Docker containers enough that we'll be able to bundle more parts of the stack.

What about really large sites, like 1GB or 300GB?

They won't be supported initially, but with additional work in Playground and WordPress core they absolutely can be supported:

• Playground will have to read data directly from the local disk (it already does) without loading it all into memory (to do).
• WordPress will need to support exports that can be paused, resumed, and streamed into the browser using multiple requests and zip files.

As a side note, a direct transfer may be a better fit for those huge sites than an export file. More about that on Trac.

[adamziel]

Here's another one:

What Blueprints and WordPress Snapshots are good and bad at

Are you considering Blueprints for your project? Have you considered WordPress Snapshots? This post will give you a good idea of the strengths and weaknesses of both of these formats.

Blueprints are recipes for building WordPress Snapshots. A WordPress Snapshot = Blueprint + Build step. In Docker analogy, these are Dockerfiles.

WordPress Snapshots are collections of, optionally zipped, files. They contain all the PHP source code, database data, static assets, and metadata necessary to start a WordPress website -- for example, in WordPress Playground or wp-now. In Docker analogy, these are Docker Images.

Snapshots are data, Blueprints are computations.

Let's also define a WordPress Website. It is a running, living organism where the source code, the PHP runtime, the database connection, and the hosting setup all work together so that you can use a web browser to read (or publish) that cool news article. In Docker terms, sites are Containers.

Things both Blueprints and WordPress Snapshots are good at

• Creating disposable websites -- WordPress Snapshots + Runtime = WordPress Website. You can easily dispose of the website and run a new one from the Snapshot, e.g. by refreshing the Playground website. Blueprints may enable building that Snapshot on the fly, but what ultimately becomes the website is the Snapshot.
• Version Control -- Tracking Blueprints is trivial as they're just text files. Tracking Snapshots takes extracting ZIP bundles and turning the SQLite blob into a plaintext SQL dump which could be made trivial by developer tooling.
• Forking and changing -- You can update a Blueprint with a text editor, and you can update an Snapshot via wp-admin or with a file editor.
• Undo -- Working on the copy of either a Blueprint or a Snapshot enables you to discard your changes and revert to the original version when anything breaks.

WordPress Snapshots are useful for users, designers, testers, and developers

WordPress Snapshots strengths

• Easy to change for users -- Run the Snapshot, go to wp-admin, write posts, import content, install plugins, and do anything else you might need. It's just WordPress.
• Familiar for developers -- A Snapshot is just WordPress. You can call a PHP function, copy a plugin to wp-content, or create a custom CSS file as usual.
• AI-friendly -- LLMs already know how to update site title, register a custom post type, and create a three-column layout using WordPress APIs. You run a WordPress Snapshot, ask AI to do things, and apply each response directly to the running website while showing the user a live preview of the changes.
• Zero build time -- Snapshots can be instantly started as all the information is embedded inside. Plug-in the runtime, done.
• No network required -- Snapshots are self--contained so you can use them on a busy workshop, a conference talk, or in a plane.
• Doesn't require special tools -- A Snapshot can be extracted and hosted without going through any specialized WordPress Playground tooling. It's just WordPress
• Reproducible and self-contained -- The same Snapshot will yield the same WordPress website today and 20 years from now. There are no external dependencies that could break. This is great for archiving websites.
• WordPress sites can be exported as and restored from a Snapshot -- It means simply packaging up the data, code, and uploads. See Playground as the WordPress export format for more details. Some tools to run the export/import process already exist and they might become a part of WordPress core in the future.

WordPress Snapshots weaknesses

• Size -- Source code, data and static assets can take megabytes or, sometimes, gigabytes.
• Opaque -- You can never be certain what's baked into the WordPress Snapshot unless you inspect its contents.
• Outdated dependencies -- A Snapshot from last year bundles last year's plugins and themes.

Blueprints are for advanced developers with specific needs

You would typically write a Blueprint if a) you're a developer and b) you need a WordPress build script. One-off Websites are so easy to create with wp-admin that most people wouldn't even think about Blueprints, but simply start clicking.

Blueprints strengths

• Flexibility -- With Blueprints, developers can make surgical adjustments to the build process.
• Lightweight -- Blueprints are tiny text files that cost almost nothing to store or transfer.
• Transparency -- A Blueprint includes all the commands needed to build a WordPress Snapshot. You can read through it and understand exactly how the site is built.
• Up-to-date dependencies -- A typical Blueprint fetches the latest version of WordPress, a particular plugin, and, perhaps, a theme. The resulting Snapshot is then up to date with the latest features and security fixes.
• WordPress.org integration -- Writing a Blueprint enables you to demo your plugin in the WordPress plugin directory.
• Spinning a development environment -- A new developer in the team could just download the Blueprint, run a hypothetical wp up command, and get a fresh dev env. The CI scripts could reuse the same method, and even the production build could be based on a Blueprint.

Blueprints weaknesses

• A WordPress site cannot be exported as a Blueprint -- Going from a WordPress site to a build script can't be automated. It is a manual effort that takes trial and error. The same goes for recording user interactions as a Blueprint. The way to export a WordPress site it to bundle it as a WordPress Snapshot.
• Difficult for AI -- LLMs don't know how to use Blueprints. Even if you teach themvia prompting or function calling API, they'd need to output all the setup steps in one go and that's a challenge in itself. Also, each change in a Blueprint means you have to build a new Snapshot (and wait).
• High entry barrier -- People know WordPress, not Blueprints. People are familiar with the UI of wp-admin and the structure of wp-content. Defining a build pipeline requires time, training, and a different way of thinking.
• Build time -- The more build steps, the longer the build takes. The Tag Concierge plugin demo took enough time to boot, it was eventually migrated to a pre-built WordPress Snapshot that only needs to be downloaded.
• Non-reproducible -- Using recent dependencies means a build could fail some day as BC breaks, plugins get abandoned, and API endpoints go offline.
• Requires a build tool -- You can't just run a Blueprint. You need WordPress Playground.

[adamziel]

@bph – would either of the writeups above make sense as a documentation page or a make.wp.org post?

[bph]

@adamziel I'll review this when I get back next week.