Skip to content

Conversation

@akirk
Copy link
Member

@akirk akirk commented Jan 25, 2026

Motivation for the change, related issues

When a site crashes due to a broken plugin, recovery mode was failing because WordPress would boot and crash before the recovery blueprint could install the mu-plugins needed to disable the broken plugin. Additionally, when a site is crashed, users couldn't browse or edit files to manually fix issues.

I had this implemented in my https://github.com/akirk/wordpress-playground/ fork but missed to migrate it here.

Implementation details

  1. wordpressInstallMode for recovery: In recovery mode, pass wordpressInstallMode: 'do-not-attempt-installing' to prevent WordPress from booting before blueprint steps run. This allows the recovery blueprint to install mu-plugins even when a broken plugin would crash WordPress on boot.

  2. Direct OPFS file browser access: When PlaygroundClient is unavailable (site crashed), the file browser now falls back to accessing OPFS directly via OpfsFilesystemBackend. This allows browsing and editing files without needing WordPress to boot.

Testing Instructions (or ideally a Blueprint)

  1. Create a persistent site and activate a plugin that causes a fatal error
  2. Observe the site crashes on boot
  3. Click the recovery button in the menu
  4. Verify the recovery blueprint succeeds and enters troubleshooting mode
  5. Verify the file browser shows files even before the site fully boots
  6. Verify you can edit and save files via the file browser

@akirk akirk requested a review from a team as a code owner January 25, 2026 23:39
@akirk akirk changed the base branch from persistent/backup-reminder to trunk January 25, 2026 23:42
@akirk akirk force-pushed the persistent/recovery-improvements branch 3 times, most recently from 3c9976a to 85503ba Compare January 25, 2026 23:46
…access

- Add skipWordPressInstallCheck option to prevent WordPress from booting
  before blueprint steps run during recovery mode. This allows the recovery
  blueprint to install mu-plugins even when a broken plugin would crash
  WordPress on boot.

- Add direct OPFS file browser access when PlaygroundClient is unavailable.
  This allows browsing and editing files even when the site has crashed,
  enabling manual fixes without needing WordPress to boot.
@adamziel
Copy link
Collaborator

Could we not use the wordpressInstallMode option directly instead of introducing a new option that overrides the mode? That’s public client api and we already have a few deprecated boolean flags to remove eventually

…allCheck

Addresses review feedback to use the existing public API option instead of
introducing a new boolean flag that would eventually need deprecation.
@akirk
Copy link
Member Author

akirk commented Jan 28, 2026

Oh wow, I missed that opportunity. Yes, I'll use that!

@adamziel adamziel merged commit 6c6fac3 into trunk Jan 29, 2026
35 checks passed
@adamziel adamziel deleted the persistent/recovery-improvements branch January 29, 2026 11:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants