diff --git a/apps.json b/apps.json index fa21a7b8..c7bcdd4f 100644 --- a/apps.json +++ b/apps.json @@ -44,6 +44,16 @@ "Productivity" ] }, + "apps/personal-rag.json": { + "title": "Personal RAG", + "description": "Private local search and answers over your WordPress content using Ollama, EmbeddingGemma, and Gemma 4", + "author": "Playground", + "categories": [ + "Apps", + "AI", + "Productivity" + ] + }, "apps/rss-reader.json": { "title": "RSS Reader", "description": "Follow friends and consume their content in your WordPress", @@ -53,4 +63,4 @@ "Social" ] } -} \ No newline at end of file +} diff --git a/apps/personal-rag.json b/apps/personal-rag.json new file mode 100644 index 00000000..7a1408d0 --- /dev/null +++ b/apps/personal-rag.json @@ -0,0 +1,37 @@ +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "meta": { + "title": "Personal RAG", + "description": "Private local search and answers over your WordPress content using Ollama, EmbeddingGemma, and Gemma 4", + "author": "Playground", + "categories": [ + "Apps", + "AI", + "Productivity" + ] + }, + "landingPage": "/wp-admin/tools.php?page=personal-rag", + "steps": [ + { + "step": "installPlugin", + "pluginData": { + "resource": "git:directory", + "url": "https://github.com/WordPress/blueprints", + "ref": "trunk", + "refType": "branch", + "path": "blueprints/personal-rag/plugin" + }, + "options": { + "activate": true, + "targetFolderName": "personal-rag" + } + }, + { + "step": "importWxr", + "file": { + "resource": "url", + "url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/personal-rag/content.xml" + } + } + ] +} diff --git a/blueprints/my-wordpress/plugin/de/welcome-post.html b/blueprints/my-wordpress/plugin/de/welcome-post.html index 5bf0158b..a8b6ec7c 100644 --- a/blueprints/my-wordpress/plugin/de/welcome-post.html +++ b/blueprints/my-wordpress/plugin/de/welcome-post.html @@ -1,34 +1,31 @@ - -
+ +
+ +

👋

+ + + +

Dein eigener WordPress — fühl dich wie zuhause.

+ +
+ + + +
- -
- -

🎨

+ +
+ +

🎨

- -

- Spiel damit - Probier alles aus und mach es zu deinem -

+ +

Spiel damit

+ + + +

Probier alles aus und mach es zu deinem.

@@ -37,27 +34,18 @@
- -
- -

💾

+ +
+ +

💾

- -

- Bleibt erhalten - Änderungen sind morgen noch da -

+ +

Bleibt erhalten

+ + + +

Deine Änderungen werden gespeichert und sind morgen noch da.

@@ -66,27 +54,18 @@
- -
- -

🔒

+ +
+ +

🔒

- -

- Ganz privat - Läuft im Browser, ohne Konto -

+ +

Ganz privat

+ + + +

Läuft in deinem Browser, ohne Konto.

@@ -95,149 +74,73 @@
- -
- -

- Schau dir das Apps-Menü an — Suche dieses Symbol in der oberen Leiste, um Apps zu installieren, Backups zu verwalten und mehr. -

- -
- + +
+ +
+ +
+ +

Schau dir das Apps-Menü an
Finde dieses Symbol in der oberen Leiste, um Apps zu installieren, Backups zu verwalten und mehr.

+ +
+ +
+ - -
- -

- ⭐ Setze ein Lesezeichen — Das ist jetzt dein - WordPress. Füge es zu deinen Lesezeichen hinzu, damit du leicht - zurückkommen kannst. -

- + +
+ +
+ +

⭐Setze ein Lesezeichen
Das ist jetzt dein WordPress. Füge es zu deinen Lesezeichen hinzu, damit du leicht zurückkommen kannst.

+ +
+ +
+
- + - -

Was kannst du hier machen?

+ +

Was kannst du hier machen?

    -
  • - Ein eigener Raum — WordPress betreibt einen großen Teil - des Webs, aber hier ist es nur für dich. Nutze es als Notizbuch, - Projektraum oder kreativen Sandkasten — ohne Veröffentlichungszwang. -
    • -
  • - Voll anpassbar — Ändere dein Theme, organisiere alles - nach deinen Wünschen. Du lernst WordPress ganz natürlich nebenbei. -
    • +
  • Ein eigener Raum — WordPress betreibt einen großen Teil des Webs, aber hier ist es nur für dich. Nutze es als Notizbuch, Projektraum oder kreativen Sandkasten — ohne Veröffentlichungszwang.
    • +
  • Voll anpassbar — Ändere dein Theme, organisiere alles nach deinen Wünschen. Du lernst WordPress ganz natürlich nebenbei.
- -

Gut zu wissen

+ +

Gut zu wissen

    -
  • - Es ist an diesen Browser gebunden — Dein Playground - lebt im Speicher dieses Browsers, du kannst also nicht von anderen - Geräten darauf zugreifen. Das macht es zu einem sehr privaten Raum. -
    • -
  • - Sichere deine Arbeit — Nutze die Backup-Funktion im - oberen Menü, um deine Seite zu speichern. So kannst du sie in einem - anderen Browser wiederherstellen oder dich vor Datenverlust schützen. -
    • -
  • - Bereit für mehr? — Verschiebe dein Playground zu einem - dedizierten WordPress-Hosting, um von jedem Gerät darauf zuzugreifen, es - öffentlich zu teilen oder bestimmte Personen zur Zusammenarbeit - einzuladen. -
    • +
  • Es ist an diesen Browser gebunden — Dein Playground lebt im Speicher dieses Browsers, du kannst also nicht von anderen Geräten darauf zugreifen. Das macht es zu einem sehr privaten Raum.
    • +
  • Sichere deine Arbeit — Nutze die Backup-Funktion im oberen Menü, um deine Seite zu speichern. So kannst du sie in einem anderen Browser wiederherstellen oder dich vor Datenverlust schützen.
    • +
  • Bereit für mehr? — Verschiebe dein Playground zu einem dedizierten WordPress-Hosting, um von jedem Gerät darauf zuzugreifen, es öffentlich zu teilen oder bestimmte Personen zur Zusammenarbeit einzuladen.
- -

Das obere Menü

+ +

Das obere Menü

-

- Suche nach dem Raster-Symbol () in der oberen Leiste. Von dort aus kannst du: -

+

Suche nach dem Raster-Symbol () in der oberen Leiste. Von dort aus kannst du:

    -
  • - Installiere Apps — Wir haben einige Plugins - ausgewählt, die gut für den privaten Gebrauch funktionieren. Das - vollständige WordPress-Plugin-Verzeichnis ist auch da, falls du mehr - erkunden möchtest. -
    • -
  • - Backups — Speichere und stelle deine Seite wieder her -
    • -
  • - Neu anfangen — Setze dein WordPress zurück oder besuche - playground.wordpress.net - für schnelle, temporäre Experimente -
    • +
  • Apps installieren — Wir haben einige Plugins ausgewählt, die gut für den privaten Gebrauch funktionieren. Das vollständige WordPress-Plugin-Verzeichnis ist auch da, falls du mehr erkunden möchtest.
    • +
  • Backups — Speichere und stelle deine Seite wieder her.
    • +
  • Neu anfangen — Setze dein WordPress zurück oder besuche playground.wordpress.net für schnelle, temporäre Experimente.
- -

Viel Spaß mit deinem WordPress!

+ +

Viel Spaß mit deinem WordPress!

diff --git a/blueprints/my-wordpress/plugin/es/welcome-post.html b/blueprints/my-wordpress/plugin/es/welcome-post.html index 15e61425..6921129e 100644 --- a/blueprints/my-wordpress/plugin/es/welcome-post.html +++ b/blueprints/my-wordpress/plugin/es/welcome-post.html @@ -1,34 +1,31 @@ - -
+ +
+ +

👋

+ + + +

Un WordPress tuyo — siéntete como en casa.

+ +
+ + + +
- -
- -

🎨

+ +
+ +

🎨

- -

- Experimenta sin miedo
Cambia lo que quieras, prueba - cosas nuevas, hazlo tuyo -

+ +

Experimenta sin miedo

+ + + +

Cambia lo que quieras, prueba cosas nuevas, hazlo tuyo.

@@ -37,27 +34,18 @@
- -
- -

💾

+ +
+ +

💾

- -

- Permanece
Tus cambios se guardan y - estarán aquí mañana -

+ +

Se queda contigo

+ + + +

Tus cambios se guardan y estarán aquí mañana.

@@ -66,27 +54,18 @@
- -
- -

🔒

+ +
+ +

🔒

- -

- Es privado
Se ejecuta en tu navegador, sin - necesidad de crear una cuenta -

+ +

Es privado

+ + + +

Se ejecuta en tu navegador, sin crear una cuenta.

@@ -95,144 +74,73 @@
- -
- -

- Échale un vistazo al menú de aplicaciones — Busca este icono en la barra superior para instalar aplicaciones, gestionar copias de seguridad y mucho más. -

- -
- + +
+ +
+ +
+ +

Échale un vistazo al menú de aplicaciones
Busca este icono en la barra superior para instalar aplicaciones, gestionar copias de seguridad y mucho más.

+ +
+ +
+ - -
- -

- ⭐ Añade esta página a marcadores — Este es ahora tu WordPress. Añádelo - a tus favoritos para poder volver fácilmente. -

- + +
+ +
+ +

⭐Añade esta página a marcadores
Este es ahora tu WordPress. Añádelo a tus favoritos para poder volver fácilmente.

+ +
+ +
+
- + - -

¿Qué puedo hacer aquí?

+ +

¿Qué puedo hacer aquí?

    -
  • - Un espacio solo para ti — WordPress es la base de gran parte de la web, - pero aquí es solo para ti. Úsalo como cuaderno de notas, espacio para proyectos o - lugar para experimentar con tu creatividad; no hace falta que publiques nada. -
    • -
  • - Totalmente personalizable — Cambia el tema y organízalo todo - como más te guste. Aprenderás a usar WordPress de forma natural a medida que avances. -
    • +
  • Un espacio solo para ti — WordPress es la base de gran parte de la web, pero aquí es solo para ti. Úsalo como cuaderno de notas, espacio para proyectos o lugar para experimentar con tu creatividad; no hace falta que publiques nada.
    • +
  • Totalmente personalizable — Cambia el tema y organízalo todo como más te guste. Aprenderás a usar WordPress de forma natural a medida que avances.
- -

Cosas que debes saber

+ +

Cosas que debes saber

    -
  • - Está ligado a este navegador — Tu Playground se almacena en - la memoria de este navegador, por lo que no puedes acceder a él desde otros dispositivos. Esto - lo convierte en un espacio muy privado. -
    • -
  • - Haz copias de seguridad de tu trabajo — Usa la función de copia de seguridad del menú superior - para guardar tu sitio. Esto te permite restaurarlo en otro navegador o - protegerlo contra la pérdida de datos del almacenamiento del navegador. -
    • -
  • - ¿Listo para dar un paso más? — Traslada tu Playground a un - hospedaje dedicado de WordPress para acceder a él desde cualquier dispositivo, compartirlo públicamente o - invitar a personas concretas a colaborar. -
    • +
  • Está ligado a este navegador — Tu Playground se almacena en la memoria de este navegador, por lo que no puedes acceder a él desde otros dispositivos. Esto lo convierte en un espacio muy privado.
    • +
  • Haz copias de seguridad de tu trabajo — Usa la función de copia de seguridad del menú superior para guardar tu sitio. Esto te permite restaurarlo en otro navegador o protegerlo contra la pérdida de datos del almacenamiento del navegador.
    • +
  • ¿Listo para dar un paso más? — Traslada tu Playground a un hospedaje dedicado de WordPress para acceder a él desde cualquier dispositivo, compartirlo públicamente o invitar a personas concretas a colaborar.
- -

El menú superior

+ +

El menú superior

-

- Busca el icono de la cuadrícula () en la barra superior. Desde aquí puedes: -

+

Busca el icono de la cuadrícula () en la barra superior. Desde aquí puedes:

    -
  • - Instalar aplicaciones — Hemos seleccionado algunos plugins que funcionan bien - para uso privado. También encontrarás allí el directorio completo de plugins de WordPress, por si - quieres echarles un vistazo. -
    • -
  • Copias de seguridad — Guarda y restaura tu sitio web
    • -
  • - Empezar de cero — Restablece tu WordPress o visita - playground.wordpress.net - para realizar experimentos rápidos y temporales -
    • +
  • Instalar aplicaciones — Hemos seleccionado algunos plugins que funcionan bien para uso privado. También encontrarás allí el directorio completo de plugins de WordPress, por si quieres echarles un vistazo.
    • +
  • Copias de seguridad — Guarda y restaura tu sitio web.
    • +
  • Empezar de cero — Restablece tu WordPress o visita playground.wordpress.net para realizar experimentos rápidos y temporales.
- -

¡Disfruta de tu WordPress!

+ +

¡Disfruta de tu WordPress!

diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.mo b/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.mo index b8cefa3a..1dcbe3d9 100644 Binary files a/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.mo and b/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.mo differ diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.po b/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.po index fda19e96..86027633 100644 --- a/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.po +++ b/blueprints/my-wordpress/plugin/languages/playground-welcome-de_DE.po @@ -28,7 +28,7 @@ msgid "👋 Welcome to Your WordPress" msgstr "👋 Willkommen bei deinem WordPress" #: playground-welcome.php -msgid "Welcome to Your WordPress" +msgid "Welcome to your WordPress" msgstr "Willkommen bei deinem WordPress" #: playground-welcome.php @@ -83,6 +83,10 @@ msgstr "Importiere..." msgid "Not now" msgstr "Nicht jetzt" +#: playground-welcome.php +msgid "An error occurred. Please try again." +msgstr "Ein Fehler ist aufgetreten. Bitte versuche es erneut." + #: playground-welcome.php msgid "Security check failed." msgstr "Sicherheitsprüfung fehlgeschlagen." diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.mo b/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.mo index e7ff9f4e..9f86a178 100644 Binary files a/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.mo and b/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.mo differ diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.po b/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.po index a6ad8e33..1111e677 100644 --- a/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.po +++ b/blueprints/my-wordpress/plugin/languages/playground-welcome-es_ES.po @@ -24,7 +24,7 @@ msgid "👋 Welcome to Your WordPress" msgstr "👋 Te damos la bienvenida a tu WordPress" #: playground-welcome.php -msgid "Welcome to Your WordPress" +msgid "Welcome to your WordPress" msgstr "Este es tu WordPress" #: playground-welcome.php @@ -85,6 +85,10 @@ msgstr "Importando..." msgid "Not now" msgstr "Ahora no" +#: playground-welcome.php +msgid "An error occurred. Please try again." +msgstr "Se ha producido un error. Inténtalo de nuevo." + #: playground-welcome.php msgid "Security check failed." msgstr "La comprobación de seguridad ha fallado." diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.mo b/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.mo index e1e144e0..994b1d8d 100644 Binary files a/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.mo and b/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.mo differ diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.po b/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.po index 8af37a89..fb18c223 100644 --- a/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.po +++ b/blueprints/my-wordpress/plugin/languages/playground-welcome-pl_PL.po @@ -28,7 +28,7 @@ msgid "👋 Welcome to Your WordPress" msgstr "👋 Witaj w swoim WordPressie" #: playground-welcome.php -msgid "Welcome to Your WordPress" +msgid "Welcome to your WordPress" msgstr "Witaj w swoim WordPressie" #: playground-welcome.php @@ -83,6 +83,10 @@ msgstr "Importowanie..." msgid "Not now" msgstr "Nie teraz" +#: playground-welcome.php +msgid "An error occurred. Please try again." +msgstr "Wystąpił błąd. Spróbuj ponownie." + #: playground-welcome.php msgid "Security check failed." msgstr "Weryfikacja bezpieczeństwa nie powiodła się." diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.mo b/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.mo index 77977625..ecdfbbbc 100644 Binary files a/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.mo and b/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.mo differ diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.po b/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.po index 87a38338..f6676926 100644 --- a/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.po +++ b/blueprints/my-wordpress/plugin/languages/playground-welcome-pt_BR.po @@ -28,7 +28,7 @@ msgid "👋 Welcome to Your WordPress" msgstr "👋 Bem-vindo ao seu WordPress" #: playground-welcome.php -msgid "Welcome to Your WordPress" +msgid "Welcome to your WordPress" msgstr "Bem-vindo ao seu WordPress" #: playground-welcome.php @@ -83,6 +83,10 @@ msgstr "Importando..." msgid "Not now" msgstr "Agora não" +#: playground-welcome.php +msgid "An error occurred. Please try again." +msgstr "Ocorreu um erro. Tente novamente." + #: playground-welcome.php msgid "Security check failed." msgstr "A verificação de segurança falhou." diff --git a/blueprints/my-wordpress/plugin/languages/playground-welcome.pot b/blueprints/my-wordpress/plugin/languages/playground-welcome.pot index 897032ae..276617e9 100644 --- a/blueprints/my-wordpress/plugin/languages/playground-welcome.pot +++ b/blueprints/my-wordpress/plugin/languages/playground-welcome.pot @@ -21,7 +21,7 @@ msgid "👋 Welcome to Your WordPress" msgstr "" #: playground-welcome.php -msgid "Welcome to Your WordPress" +msgid "Welcome to your WordPress" msgstr "" #: playground-welcome.php @@ -76,6 +76,10 @@ msgstr "" msgid "Not now" msgstr "" +#: playground-welcome.php +msgid "An error occurred. Please try again." +msgstr "" + #: playground-welcome.php msgid "Security check failed." msgstr "" diff --git a/blueprints/my-wordpress/plugin/pl/welcome-post.html b/blueprints/my-wordpress/plugin/pl/welcome-post.html index 15cf7768..094a28fd 100644 --- a/blueprints/my-wordpress/plugin/pl/welcome-post.html +++ b/blueprints/my-wordpress/plugin/pl/welcome-post.html @@ -1,34 +1,31 @@ - -
+ +
+ +

👋

+ + + +

Twój własny WordPress — poczuj się jak u siebie.

+ +
+ + + +
- -
- -

🎨

+ +
+ +

🎨

- -

- Eksperymentuj - Zmieniaj wszystko, próbuj, twórz po swojemu -

+ +

Eksperymentuj

+ + + +

Zmieniaj wszystko, próbuj, twórz po swojemu.

@@ -37,27 +34,18 @@
- -
- -

💾

+ +
+ +

💾

- -

- Zostaje zapisane - Zmiany będą tu jutro -

+ +

Zostaje z Tobą

+ + + +

Twoje zmiany są zapisywane i będą tu jutro.

@@ -66,27 +54,18 @@
- -
- -

🔒

+ +
+ +

🔒

- -

- Prywatność - Działa w przeglądarce, bez konta -

+ +

Prywatność

+ + + +

Działa w przeglądarce, bez konta.

@@ -95,147 +74,73 @@
- -
- -

- Sprawdź menu Aplikacje — Szukaj tej ikony na górnym pasku, aby instalować aplikacje, zarządzać kopiami zapasowymi i więcej. -

- -
- + +
+ +
+ +
+ +

Sprawdź menu Aplikacje
Szukaj tej ikony na górnym pasku, aby instalować aplikacje, zarządzać kopiami zapasowymi i więcej.

+ +
+ +
+ - -
- -

- ⭐ Dodaj do zakładek — To teraz Twój WordPress. Dodaj tę - stronę do zakładek, żeby łatwo tu wrócić. -

- + +
+ +
+ +

⭐Dodaj do zakładek
To teraz Twój WordPress. Dodaj tę stronę do zakładek, żeby łatwo tu wrócić.

+ +
+ +
+
- + - -

Co możesz tu robić?

+ +

Co możesz tu robić?

    -
  • - Twoja własna przestrzeń — WordPress napędza znaczną część - internetu, ale tutaj jest tylko dla Ciebie. Używaj go jako notatnik, - przestrzeń projektową lub kreatywną piaskownicę — bez konieczności - publikowania. -
    • -
  • - Pełna personalizacja — Zmieniaj motyw, organizuj wszystko - po swojemu. Nauczysz się WordPressa naturalnie w trakcie używania. -
    • +
  • Twoja własna przestrzeń — WordPress napędza znaczną część internetu, ale tutaj jest tylko dla Ciebie. Używaj go jako notatnik, przestrzeń projektową lub kreatywną piaskownicę — bez konieczności publikowania.
    • +
  • Pełna personalizacja — Zmieniaj motyw, organizuj wszystko po swojemu. Nauczysz się WordPressa naturalnie w trakcie używania.
- -

Warto wiedzieć

+ +

Warto wiedzieć

    -
  • - Przypisany do tej przeglądarki — Twój Playground - przechowywany jest w tej przeglądarce, więc nie masz do niego dostępu z - innych urządzeń. Dzięki temu to bardzo prywatna przestrzeń. -
    • -
  • - Rób kopie zapasowe — Użyj funkcji kopii zapasowej w górnym - menu, aby zapisać swoją stronę. Pozwoli Ci to przywrócić ją w innej - przeglądarce lub zabezpieczyć przed utratą danych. -
    • -
  • - Chcesz więcej? — Przenieś swój Playground na dedykowany - hosting WordPress, aby mieć dostęp z każdego urządzenia, udostępnić go - publicznie lub zaprosić innych do współpracy. -
    • +
  • Przypisany do tej przeglądarki — Twój Playground przechowywany jest w tej przeglądarce, więc nie masz do niego dostępu z innych urządzeń. Dzięki temu to bardzo prywatna przestrzeń.
    • +
  • Rób kopie zapasowe — Użyj funkcji kopii zapasowej w górnym menu, aby zapisać swoją stronę. Pozwoli Ci to przywrócić ją w innej przeglądarce lub zabezpieczyć przed utratą danych.
    • +
  • Chcesz więcej? — Przenieś swój Playground na dedykowany hosting WordPress, aby mieć dostęp z każdego urządzenia, udostępnić go publicznie lub zaprosić innych do współpracy.
- -

Górne menu

+ +

Górne menu

-

- Szukaj ikony siatki () na górnym pasku. Stamtąd możesz: -

+

Szukaj ikony siatki () na górnym pasku. Stamtąd możesz:

    -
  • - Dodać aplikacje — Wybraliśmy wtyczki, które dobrze - sprawdzają się do prywatnego użytku. Pełny katalog wtyczek WordPress też - jest dostępny, jeśli chcesz odkrywać więcej. -
    • -
  • - Kopie zapasowe — Zapisuj i przywracaj swoją stronę -
    • -
  • - Zacznij od nowa — Zresetuj swojego WordPressa lub odwiedź - playground.wordpress.net - dla szybkich, tymczasowych eksperymentów -
    • +
  • Dodać aplikacje — Wybraliśmy wtyczki, które dobrze sprawdzają się do prywatnego użytku. Pełny katalog wtyczek WordPress też jest dostępny, jeśli chcesz odkrywać więcej.
    • +
  • Kopie zapasowe — Zapisuj i przywracaj swoją stronę.
    • +
  • Zacznij od nowa — Zresetuj swojego WordPressa lub odwiedź playground.wordpress.net dla szybkich, tymczasowych eksperymentów.
- -

Miłej zabawy z WordPressem!

+ +

Miłej zabawy z WordPressem!

diff --git a/blueprints/my-wordpress/plugin/playground-welcome.css b/blueprints/my-wordpress/plugin/playground-welcome.css index dd8372bc..73919389 100644 --- a/blueprints/my-wordpress/plugin/playground-welcome.css +++ b/blueprints/my-wordpress/plugin/playground-welcome.css @@ -9,178 +9,52 @@ display: none !important; } -.playground-welcome-overlay { - position: fixed; - top: 0; - left: 0; - right: 0; - bottom: 0; - background: linear-gradient( - 135deg, - #1e1e1e 0%, - #2f2f2f 100% - ); - display: flex; - align-items: flex-start; - justify-content: center; - z-index: 999999; - padding: 20px; - box-sizing: border-box; - overflow-y: auto; +body.tools_page_playground-welcome { + background: #f0f0f0; } -.playground-welcome-dialog { - background: var(--wp-components-color-background, #fff); - border-radius: 2px; - box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); - padding: 40px 48px; - max-width: 520px; - width: 100%; - animation: slideUp 0.4s ease-out; - margin: auto; +body.tools_page_playground-welcome #wpbody-content { + padding-bottom: 0; } -@keyframes slideUp { - from { - opacity: 0; - transform: translateY(20px); - } - to { - opacity: 1; - transform: translateY(0); - } +#playground-welcome-root { + min-height: 100vh; } -.playground-welcome-dialog header { - display: flex; - align-items: center; - gap: 8px; - margin: 0 0 8px 0; +.playground-welcome-modal .components-modal__frame { + width: calc(100% - 32px); + max-width: 520px; } -.playground-welcome-dialog header .dashicons { - font-size: 28px; - width: 28px; - height: 28px; - color: var(--wp-admin-theme-color, #3858e9); +.playground-welcome-form, +.playground-welcome-import-fields { + display: grid; + gap: 24px; } -.playground-welcome-dialog .playground-welcome-dialog-title { +.playground-welcome-intro { margin: 0; - font-size: 28px; - font-weight: 600; - color: var(--wp-components-color-foreground, #1e1e1e); - text-wrap: balance; - line-height: 1.3; -} - -.playground-welcome-dialog .intro { - margin: 0 0 32px 0; - color: var(--wp-components-color-gray-700, #757575); - font-size: 16px; + color: #757575; line-height: 1.5; } -.field-group { - margin-bottom: 24px; -} - -.field-group label { - display: block; - margin-bottom: 8px; - font-weight: 500; - color: var(--wp-components-color-foreground, #1e1e1e); - font-size: 14px; +.playground-welcome-import-panel { + border: 1px solid #ddd; } -/* Ensure inputs fill the form width */ -.field-group .components-text-control__input, -.field-group .components-select-control__input { - width: 100%; - box-sizing: border-box; -} - -.playground-welcome-overlay .button-group { +.playground-welcome-actions { display: flex; justify-content: flex-end; - gap: 16px; - margin-top: 32px; -} - -.playground-welcome-overlay .components-button { - padding: 8px 20px; - font-size: 16px; -} - -.playground-welcome-overlay .components-notice { - margin-top: 16px; -} - -.import-details { - margin-bottom: 24px; - border: 1px solid var(--wp-components-color-gray-300, #ddd); - border-radius: var(--wp-components-border-radius, 2px); - overflow: hidden; -} - -.import-details summary { - padding: 14px 16px; - font-weight: 500; - color: var(--wp-components-color-foreground, #1e1e1e); - font-size: 14px; - cursor: pointer; - background: var(--wp-components-color-gray-100, #f0f0f0); - transition: background 0.2s; - list-style: none; -} - -.import-details summary::-webkit-details-marker { - display: none; -} - -.import-details summary::before { - content: '+'; - display: inline-block; - width: 20px; - font-weight: 600; - color: var(--wp-components-color-gray-700, #757575); -} - -.import-details[open] summary::before { - content: '\2212'; -} - -.import-details summary:hover { - background: var(--wp-components-color-gray-200, #e0e0e0); -} - -.import-details[open] summary { - border-bottom: 1px solid var(--wp-components-color-gray-300, #ddd); -} - -.import-details .field-group { - padding: 16px; - margin-bottom: 0; -} - -.import-details .field-group:first-of-type { - padding-top: 20px; -} - -.import-details .field-group:last-of-type { - padding-bottom: 20px; + gap: 12px; } @media (max-width: 600px) { - .playground-welcome-dialog { - padding: 24px; - } - - .playground-welcome-dialog .playground-welcome-dialog-title { - font-size: 22px; + .playground-welcome-actions { + flex-direction: column-reverse; } - .playground-welcome-overlay .button-group { - flex-direction: column; + .playground-welcome-actions .components-button { + justify-content: center; + width: 100%; } } diff --git a/blueprints/my-wordpress/plugin/playground-welcome.js b/blueprints/my-wordpress/plugin/playground-welcome.js new file mode 100644 index 00000000..81324469 --- /dev/null +++ b/blueprints/my-wordpress/plugin/playground-welcome.js @@ -0,0 +1,171 @@ +( function ( wp, settings ) { + if ( ! wp || ! wp.components || ! wp.element || ! wp.domReady || ! settings ) { + return; + } + + const { Button, Modal, Notice, PanelBody, SelectControl, TextControl } = wp.components; + const { createElement: el, render, useState } = wp.element; + const { strings } = settings; + + function PlaygroundWelcomeModal() { + const [ displayName, setDisplayName ] = useState( '' ); + const [ feedUrl, setFeedUrl ] = useState( '' ); + const [ maxItems, setMaxItems ] = useState( '10' ); + const [ notice, setNotice ] = useState( null ); + const [ isSubmitting, setIsSubmitting ] = useState( false ); + + function goHome() { + window.location.href = settings.homeUrl; + } + + function submitForm( event ) { + event.preventDefault(); + setIsSubmitting( true ); + setNotice( null ); + + const formData = new window.FormData(); + formData.append( 'action', 'playground_welcome_save' ); + formData.append( 'nonce', settings.nonce ); + formData.append( 'display_name', displayName ); + formData.append( 'feed_url', feedUrl ); + formData.append( 'max_items', maxItems ); + + window + .fetch( settings.ajaxUrl, { + method: 'POST', + credentials: 'same-origin', + body: formData, + } ) + .then( ( response ) => response.json() ) + .then( ( response ) => { + if ( response.success ) { + setNotice( { + status: 'success', + message: response.data.message, + } ); + window.setTimeout( goHome, 1500 ); + return; + } + + setNotice( { + status: 'error', + message: response.data.message || strings.errorMessage, + } ); + setIsSubmitting( false ); + } ) + .catch( () => { + setNotice( { + status: 'error', + message: strings.errorMessage, + } ); + setIsSubmitting( false ); + } ); + } + + return el( + Modal, + { + title: strings.title, + className: 'playground-welcome-modal', + isDismissible: false, + shouldCloseOnClickOutside: false, + shouldCloseOnEsc: false, + onRequestClose: goHome, + }, + el( + 'form', + { + className: 'playground-welcome-form', + onSubmit: submitForm, + }, + el( 'p', { className: 'playground-welcome-intro' }, strings.intro ), + el( TextControl, { + label: strings.displayNameLabel, + value: displayName, + onChange: setDisplayName, + autoFocus: true, + __next40pxDefaultSize: true, + __nextHasNoMarginBottom: true, + } ), + el( + PanelBody, + { + title: strings.importTitle, + initialOpen: false, + className: 'playground-welcome-import-panel', + }, + el( + 'div', + { className: 'playground-welcome-import-fields' }, + el( TextControl, { + label: strings.feedUrlLabel, + help: strings.feedUrlHelp, + placeholder: 'example.com', + value: feedUrl, + onChange: ( value ) => { + setFeedUrl( value ); + if ( notice && notice.status === 'error' ) { + setNotice( null ); + } + }, + __next40pxDefaultSize: true, + __nextHasNoMarginBottom: true, + } ), + el( SelectControl, { + label: strings.maxItemsLabel, + value: maxItems, + options: [ + { label: strings.fivePosts, value: '5' }, + { label: strings.tenPosts, value: '10' }, + { label: strings.twentyPosts, value: '20' }, + { label: strings.fiftyPosts, value: '50' }, + ], + onChange: setMaxItems, + __next40pxDefaultSize: true, + __nextHasNoMarginBottom: true, + } ) + ) + ), + notice && + el( + Notice, + { + status: notice.status, + isDismissible: false, + }, + notice.message + ), + el( + 'div', + { className: 'playground-welcome-actions' }, + el( + Button, + { + variant: 'secondary', + href: settings.homeUrl, + disabled: isSubmitting, + }, + strings.notNow + ), + el( + Button, + { + variant: 'primary', + type: 'submit', + isBusy: isSubmitting, + disabled: isSubmitting, + }, + isSubmitting ? strings.importing : strings.continue + ) + ) + ) + ); + } + + wp.domReady( function () { + const root = document.getElementById( 'playground-welcome-root' ); + if ( root ) { + render( el( PlaygroundWelcomeModal ), root ); + } + } ); +} )( window.wp, window.playgroundWelcomeSettings ); diff --git a/blueprints/my-wordpress/plugin/playground-welcome.php b/blueprints/my-wordpress/plugin/playground-welcome.php index 97abcb89..e97e2f1a 100644 --- a/blueprints/my-wordpress/plugin/playground-welcome.php +++ b/blueprints/my-wordpress/plugin/playground-welcome.php @@ -41,7 +41,7 @@ private function maybe_setup_content() { if ($post) { wp_update_post([ 'ID' => $post->ID, - 'post_title' => __('Welcome to Your WordPress', 'playground-welcome'), + 'post_title' => __('Welcome to your WordPress', 'playground-welcome'), 'post_content' => self::get_welcome_post_content(), 'post_name' => 'welcome-to-your-wordpress', ]); @@ -108,12 +108,14 @@ public static function allow_svg_tags($tags) { 'xmlns' => true, 'width' => true, 'height' => true, + 'fill' => true, 'aria-hidden' => true, 'focusable' => true, 'style' => true, ]; $tags['path'] = [ 'd' => true, + 'fill' => true, 'fill-rule' => true, 'clip-rule' => true, ]; @@ -142,133 +144,46 @@ public function enqueue_styles($hook) { ['wp-components'], '1.0.0' ); + + wp_enqueue_script( + 'playground-welcome', + plugin_dir_url(__FILE__) . 'playground-welcome.js', + ['wp-components', 'wp-dom-ready', 'wp-element'], + '1.0.0', + true + ); + + wp_localize_script( + 'playground-welcome', + 'playgroundWelcomeSettings', + [ + 'ajaxUrl' => admin_url('admin-ajax.php'), + 'homeUrl' => home_url('/'), + 'nonce' => wp_create_nonce('playground_welcome_nonce'), + 'strings' => [ + 'title' => __('Welcome to your WordPress', 'playground-welcome'), + 'intro' => __("This is a private WordPress that's free and needs no account. It's stored in your browser and will be here when you come back.", 'playground-welcome'), + 'displayNameLabel' => __("What's your name?", 'playground-welcome'), + 'importTitle' => __('Import content from a website', 'playground-welcome'), + 'feedUrlLabel' => __('Website URL', 'playground-welcome'), + 'feedUrlHelp' => __("Enter a site URL and we'll find and import its RSS feed.", 'playground-welcome'), + 'maxItemsLabel' => __('Maximum posts to import', 'playground-welcome'), + 'fivePosts' => __('5 posts', 'playground-welcome'), + 'tenPosts' => __('10 posts', 'playground-welcome'), + 'twentyPosts' => __('20 posts', 'playground-welcome'), + 'fiftyPosts' => __('50 posts', 'playground-welcome'), + 'continue' => __('Continue', 'playground-welcome'), + 'importing' => __('Importing...', 'playground-welcome'), + 'notNow' => __('Not now', 'playground-welcome'), + 'errorMessage' => __('An error occurred. Please try again.', 'playground-welcome'), + ], + ] + ); } public function render_page() { - $current_user = wp_get_current_user(); ?> -
-
-
- -

-
-

- -
- - -
- - -
- -
- -
- - -

-
- -
- - -
-
- - - -
- - -
-
-
-
- - +
-
+ +
+ +

👋

+ + + +

A WordPress of your own — make yourself at home.

+ +
+ + + +
- -
- -

🎨

+ +
+ +

🎨

- -

- Experiment freely
Change anything, try - things out, make it yours -

+ +

Experiment freely

+ + + +

Change anything, try things out, make it yours.

@@ -37,27 +34,18 @@
- -
- -

💾

+ +
+ +

💾

- -

- It stays
Your changes are saved and will - be here tomorrow -

+ +

It stays with you

+ + + +

Your changes are saved and will be here tomorrow.

@@ -66,27 +54,18 @@
- -
- -

🔒

+ +
+ +

🔒

- -

- It's private
Runs in your browser, no - account needed -

+ +

It's private

+ + + +

Runs in your browser, no account needed.

@@ -95,144 +74,73 @@
- -
- -

- Check out the Apps menu — Look for this icon in the top bar to install apps, manage backups, and more. -

- -
- + +
+ +
+ +
+ +

Check out the Apps menu
Find this icon in the top bar to install apps, manage backups, and more.

+ +
+ +
+ - -
- -

- ⭐ Bookmark this page — This is your WordPress now. Add - it to your bookmarks so you can easily come back. -

- + +
+ +
+ +

⭐Bookmark this page
This is your WordPress. Add it to your bookmarks so you can come back easily.

+ +
+ +
+
- + - -

What can you do here?

+ +

What can you do here?

    -
  • - A space of your own — WordPress powers much of the web, - but here it's just for you. Use it as a notebook, project space, or - creative sandbox—no publishing required. -
    • -
  • - Fully customizable — Change your theme, organize things - however you like. You'll learn WordPress naturally as you go. -
    • +
  • A space of your own — WordPress powers much of the web, but here it's just for you. Use it as a notebook, project space, or creative sandbox — no publishing required.
    • +
  • Fully customizable — Change your theme, organize things however you like. You'll learn WordPress naturally as you go.
- -

Things to know

+ +

Things to know

    -
  • - It's bound to this browser — Your Playground lives in - this browser's storage, so you can't access it from other devices. This - makes it a very private space. -
    • -
  • - Back up your work — Use the backup feature in the top - menu to save your site. This lets you restore it in another browser or - protect against browser storage loss. -
    • -
  • - Ready to go bigger? — Move your Playground to dedicated - WordPress hosting to access it from any device, share it publicly, or - invite specific people to collaborate. -
    • +
  • It's bound to this browser — Your Playground lives in this browser's storage, so you can't access it from other devices. This makes it a very private space.
    • +
  • Back up your work — Use the backup feature in the top menu to save your site. This lets you restore it in another browser or protect against browser storage loss.
    • +
  • Ready to go bigger? — Move your Playground to dedicated WordPress hosting to access it from any device, share it publicly, or invite specific people to collaborate.
- -

The top menu

+ +

The top menu

-

- Look for the grid icon () in the top bar. From there you can: -

+

Look for the grid icon () in the top bar. From there you can:

    -
  • - Install Apps — We've picked some plugins that work well - for private use. The full WordPress plugin directory is there too if you - want to explore. -
    • -
  • Backups — Save and restore your site
    • -
  • - Start over — Reset your WordPress or visit - playground.wordpress.net - for quick, temporary experiments -
    • +
  • Install Apps — We've picked some plugins that work well for private use. The full WordPress plugin directory is there too if you want to explore.
    • +
  • Backups — Save and restore your site.
    • +
  • Start over — Reset your WordPress or visit playground.wordpress.net for quick, temporary experiments.
- -

Enjoy your WordPress!

+ +

Enjoy your WordPress!

diff --git a/blueprints/personal-rag/blueprint.json b/blueprints/personal-rag/blueprint.json new file mode 100644 index 00000000..24b805ce --- /dev/null +++ b/blueprints/personal-rag/blueprint.json @@ -0,0 +1,67 @@ +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "meta": { + "title": "Personal RAG", + "description": "A private local RAG app for WordPress Playground using Ollama, EmbeddingGemma, Gemma 4, and SQLite-backed WordPress data.", + "author": "Playground", + "categories": [ + "Apps", + "AI" + ] + }, + "login": true, + "landingPage": "/wp-admin/tools.php?page=personal-rag", + "steps": [ + { + "step": "mkdir", + "path": "/wordpress/wp-content/plugins/personal-rag" + }, + { + "step": "mkdir", + "path": "/wordpress/wp-content/plugins/personal-rag/assets" + }, + { + "step": "writeFile", + "path": "/wordpress/wp-content/plugins/personal-rag/personal-rag.php", + "data": { + "resource": "bundled", + "path": "./plugin/personal-rag.php" + } + }, + { + "step": "writeFile", + "path": "/wordpress/wp-content/plugins/personal-rag/uninstall.php", + "data": { + "resource": "bundled", + "path": "./plugin/uninstall.php" + } + }, + { + "step": "writeFile", + "path": "/wordpress/wp-content/plugins/personal-rag/assets/personal-rag.js", + "data": { + "resource": "bundled", + "path": "./plugin/assets/personal-rag.js" + } + }, + { + "step": "writeFile", + "path": "/wordpress/wp-content/plugins/personal-rag/assets/personal-rag.css", + "data": { + "resource": "bundled", + "path": "./plugin/assets/personal-rag.css" + } + }, + { + "step": "activatePlugin", + "pluginPath": "personal-rag/personal-rag.php" + }, + { + "step": "importWxr", + "file": { + "resource": "bundled", + "path": "./content.xml" + } + } + ] +} diff --git a/blueprints/personal-rag/content.xml b/blueprints/personal-rag/content.xml new file mode 100644 index 00000000..b96f6df6 --- /dev/null +++ b/blueprints/personal-rag/content.xml @@ -0,0 +1,10557 @@ + + + + WordPress Playground Docs for Personal RAG + https://playground.wordpress.net + Starter documentation corpus for the Personal RAG blueprint. + Mon, 11 May 2026 00:00:00 +0000 + en-US + 1.2 + https://playground.wordpress.net + https://playground.wordpress.net + + 1 + + + + + + + + 1 + + + + + + 2 + + + + + + 3 + + + + + + 4 + + + + + + 5 + + + + + + 6 + + + + + + 7 + + + + + + 8 + + + + + + 9 + + + + + + 10 + + + + + + 11 + + + + + + 12 + + + + + + 13 + + + + + + 14 + + + + + + 15 + + + + + + + <![CDATA[Getting started]]> + https://playground.wordpress.net/blueprints-getting-started/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=1 + + Getting started with Blueprints +

Blueprints are JSON files for setting up your very own WordPress Playground instance. For example:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"landingPage": "/wp-admin/",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "latest"
+	},
+	"steps": [
+		{
+			"step": "login",
+			"username": "admin",
+			"password": "password"
+		}
+	]
+}
+

There are three ways to use Blueprints:

+ +

What problems are solved by Blueprints?

+

No coding skills required

+

Blueprints are just JSON. You don't need a development environment, any libraries, or even JavaScript knowledge. You can write them in any text editor.

+

However, if you do have a development environment, that's great! You can use the Blueprint JSON schema to get autocompletion and validation.

+

HTTP Requests are managed for you

+

Blueprints fetch any resources you declare for you. You don't have to worry about managing multiple fetch() calls or waiting for them to finish. You can just declare a few links and let Blueprints handle and optimize the downloading pipeline.

+

You can link to a Blueprint-preconfigured Playground

+

Because Blueprints can be pasted in the URL, you can embed or link to a Playground with a specific configuration. For example, clicking this button will open a Playground with PHP 8.3 and a pendant theme installed:

+
<BlueprintExample justButton={true} blueprint={{
+	"preferredVersions": {
+		"php": "8.3",
+  		"wp": "latest"
+	},
+	"steps": [
+        {
+            "step": "installTheme",
+            "themeData": {
+                "resource": "wordpress.org/themes",
+            	"slug": "pendant"
+            },
+            "options": {
+                "activate": true
+            }
+        }
+	]
+}} />
+

Trusted by default

+

Blueprints are just JSON. Running other people's Blueprints doesn't require the element of trust. Since Blueprints cannot execute arbitrary JavaScript, they are limited in what they can do.

+

With Blueprints, WordPress.org plugin directory may be able to offer live previews of plugins. Plugin authors will just write a custom Blueprint to preconfigure the Playground instance with any site options or starter content they may need.

+

Write it once, use it anywhere

+

Blueprints work both on the web and in node.js. You can run them both in the same JavaScript process, and through a remote Playground Client. They are the universal language of configuration. Where you can run Playground, you can use Blueprints.

+

Original Playground docs source: https://playground.wordpress.net/blueprints/getting-started

]]> + + 1 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Using Blueprints]]> + https://playground.wordpress.net/blueprints-using-blueprints/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=2 + + Using Blueprints +

You can use Blueprints in one of the following ways:

+
  • By passing them as a URL fragment to the Playground.
  • By loading them from a URL using the blueprint-url parameter.
  • By using Blueprint bundles (ZIP files or directories).
  • By using the JavaScript API.
+

URL Fragment

+

The easiest way to start using Blueprints is to paste one into the URL "fragment" on WordPress Playground website, e.g. https://playground.wordpress.net/#{"preferredVersions....

+

For example, to create a Playground with specific versions of WordPress and PHP you would use the following Blueprint:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.5"
+	}
+}
+

And then you would go to https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"6.5"}}.

+

Tip

+

In Javascript, you can get a compact version of any blueprint JSON with JSON.stringify and JSON.parse Example:

+
const blueprintJson = `{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.5"
+	}
+}`;
+const minifiedBlueprintJson = JSON.stringify(JSON.parse(blueprintJson)); // {"preferredVersions":{"php":"8.3","wp":"6.5"}}
+

You won't have to paste links to follow along. We'll use code examples with a "Try it out" button that will automatically run the examples for you:

+
<BlueprintExample justButton={true} blueprint={{
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.5"
+	}
+}} />
+

Base64 encoded Blueprints

+

Some tools, including GitHub, might not format the Blueprint correctly when pasted into the URL. In such cases, encode your Blueprint in Base64 and append it to the URL. For example, that's the above Blueprint in Base64 format: eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19.

+

To run it, go to https://playground.wordpress.net/#eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19

+

Tip

+

In JavaScript, You can get any blueprint JSON in Base64 format with global function btoa().

+

Example:

+
const blueprintJson = `{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.5"
+	}
+}`;
+const minifiedBlueprintJson = btoa(blueprintJson); // eyIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsInByZWZlcnJlZFZlcnNpb25zIjogeyJwaHAiOiAiNy40Iiwid3AiOiAiNi41In19
+

Load Blueprint from a URL

+

When your Blueprint gets too wieldy, you can load it via the ?blueprint-url query parameter in the URL, like this:

+

https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json

+

Note that the Blueprint must be publicly accessible and served with the correct Access-Control-Allow-Origin header:

+
Access-Control-Allow-Origin: *
+

Blueprint Bundles

+

The ?blueprint-url parameter now also supports Blueprint bundles in ZIP format. A Blueprint bundle is a ZIP file that contains a blueprint.json file at the root level, along with any additional resources referenced by the Blueprint.

+

For example, you can load a Blueprint bundle like this:

+

https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip

+

When using a Blueprint bundle, you can reference bundled resources using the bundled resource type:

+
{
+	"landingPage": "/my-file.txt",
+	"steps": [
+		{
+			"step": "writeFile",
+			"path": "/wordpress/my-file.txt",
+			"data": {
+				"resource": "bundled",
+				"path": "/bundled-text-file.txt"
+			}
+		}
+	]
+}
+

For more information on Blueprint bundles, see the Blueprint Bundles documentation.

+

JavaScript API

+

You can also use Blueprints with the JavaScript API using the startPlaygroundWeb() function from the @wp-playground/client package. Here's a small, self-contained example you can run on JSFiddle or CodePen:

+
<iframe id="wp-playground" style="width: 1200px; height: 800px"></iframe>
+<script type="module">
+	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp-playground'),
+		remoteUrl: `https://playground.wordpress.net/remote.html`,
+		blueprint: {
+			landingPage: '/wp-admin/',
+			preferredVersions: {
+				php: '8.3',
+				wp: 'latest',
+			},
+			steps: [
+				{
+					step: 'login',
+					username: 'admin',
+					password: 'password',
+				},
+				{
+					step: 'installPlugin',
+					pluginData: {
+						resource: 'wordpress.org/plugins',
+						slug: 'friends',
+					},
+				},
+			],
+		},
+	});
+
+	const response = await client.run({
+		// wp-load.php is only required if you want to interact with WordPress.
+		code: '<?php require_once "/wordpress/wp-load.php"; $posts = get_posts(); echo "Post Title: " . $posts[0]->post_title;',
+	});
+	console.log(response.text);
+</script>
+

Original Playground docs source: https://playground.wordpress.net/blueprints/using-blueprints

]]> + + 2 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Blueprint data Format]]> + https://playground.wordpress.net/blueprints-data-format/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=3 + + Blueprint data format +

A Blueprint JSON file can have many different properties that will be used to define your Playground instance. The most important properties are detailed below.

+

Here's an example that uses many of them:

+
<BlueprintExample blueprint={{
+	"landingPage": "/wp-admin/",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.5"
+	},
+	"features": {
+		"networking": true
+	},
+	"steps": [
+		{
+			"step": "login",
+			"username": "admin",
+			"password": "password"
+		}
+	]
+}} />
+

JSON schema

+

JSON files can be tedious to write and easy to get wrong. To help with that, Playground provides a JSON schema file that you can use to get auto-completion and validation in your editor. Just set the $schema property to the following:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+}
+

Landing page

+

The landingPage property tells Playground which URL to navigate to after the Blueprint has been run. This is a great tool, especially when creating theme or plugin demos. Often, you will want to start Playground in the Site Editor or have a specific post open in the Post Editor. Make sure you use a relative path.

+
{
+	"landingPage": "/wp-admin/site-editor.php",
+}
+

Preferred versions

+

The preferredVersions property declares your preferred PHP and WordPress versions. It can contain the following properties:

+
  • php (string): Loads the specified PHP version. Accepts 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5, or latest. Minor versions like 7.4.1 are not supported.
  • wp (string): Loads the specified WordPress version. Accepts the last seven major WordPress versions. As of April 28, 2026, that's 6.3, 6.4, 6.5, 6.6, 6.7, 6.8, or 6.9. You can also use the generic values latest, beta, or nightly (alias trunk). beta resolves to the most recent Beta or Release Candidate of an active release cycle; nightly/trunk builds straight from the WordPress development branch.
+
{
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.7"
+	},
+}
+

Features

+

You can use the features property to turn on or off certain features of the Playground instance. It can contain the following properties:

+
  • networking: Defaults to true. Enables or disables the networking support for Playground. If enabled, wp_safe_remote_get and similar WordPress functions will actually use fetch() to make HTTP requests. If disabled, they will immediately fail instead. You will need this property enabled if you want the user to be able to install plugins or themes.
+
{
+	"features": {
+		"networking": false
+	},
+}
+

Extra libraries

+

You can preload extra libraries into the Playground instance. The following libraries are supported:

+
  • wp-cli: Enables WP-CLI support for Playground. If included, WP-CLI will be installed during boot. If not included, you will get an error message when trying to run WP-CLI commands using the JS API. WP-CLI will be installed by default if the blueprint contains any wp-cli steps.
+
{
+	"extraLibraries": [ "wp-cli" ],
+}
+

Steps

+

Arguably the most powerful property, steps allows you to configure the Playground instance with preinstalled themes, plugins, demo content, and more. The following example logs the user in with a dedicated username and password. It then installs and activates the Gutenberg plugin. Learn more about steps.

+
{
+	"steps": [
+		{
+			"step": "login",
+			"username": "admin",
+			"password": "password"
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "gutenberg"
+			}
+		},
+	]
+}
+

Original Playground docs source: https://playground.wordpress.net/blueprints/data-format

]]> + + 3 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Resources References]]> + https://playground.wordpress.net/blueprints-steps-resources/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=4 + + Resources References +

"Resource References" allow you use external files in Blueprints

+

Blueprints steps such as installPlugin or installTheme require a location of the plugin or theme to be installed.

+

That location can be defined as a URL resource of the .zip file containing the theme or plugin. It can also be defined as a wordpress.org/plugins or wordpress.org/themes resource for those plugins/themes published in the official WordPress directories.

+

The following resource references are available:

+

URLReference

+

The URLReference resource is used to reference files that are stored on a remote server. The URLReference resource is defined as follows:

+
type URLReference = {
+	resource: 'url';
+	url: string;
+};
+

To use the URLReference resource, you need to provide the URL of the file. For example, to reference a file named "index.html" that is stored on a remote server, you can create a URLReference as follows:

+
{
+	"resource": "url",
+	"url": "https://example.com/index.html"
+}
+

The resource url type works really in combination with blueprint steps such as installPlugin or installTheme. These steps require a ResourceType to define the location of the plugin or the theme to install.

+

With a "resource": "url" we can define the location of a .zip containing the plugin/theme. Use this for built ZIP artifacts hosted on a publicly accessible URL that does not require authentication, such as a release asset or a CI artifact direct-download URL.

+

For source code stored in a Git repository, prefer git:directory. It can fetch a repository subdirectory from a branch, tag, or commit without requiring a ZIP archive.

+

GitDirectoryReference

+

The GitDirectoryReference resource is used to reference a directory inside a Git repository. This is useful when a plugin or theme lives in a subfolder of a repo, or when you want to install from a specific branch, tag, or commit.

+
type GitDirectoryReference = {
+	resource: 'git:directory';
+	url: string; // Repository URL (https://, ssh git@..., etc.)
+	path?: string; // Optional subdirectory inside the repository
+	ref?: string; // Branch, tag, or commit SHA (defaults to HEAD)
+	refType?: 'branch' | 'tag' | 'commit'; // Hint for resolving the ref
+	'.git'?: boolean; // Experimental: include a .git directory with fetched metadata
+};
+

Example:

+
{
+	"step": "installPlugin",
+	"pluginData": {
+		"resource": "git:directory",
+		"url": "https://github.com/WordPress/block-development-examples",
+		"ref": "HEAD",
+		"path": "plugins/data-basics-59c8f8"
+	},
+	"options": {
+		"activate": true,
+		"targetFolderName": "data-basics"
+	}
+}
+

Notes:

+
  • When using a branch or tag name for ref, you must specify refType (e.g. "refType": "branch"). Without it, only HEAD is reliably resolved.
  • Playground automatically detects providers like GitHub and GitLab.
  • Repository URLs may include or omit a trailing .git suffix. Extra trailing slashes are ignored.
  • It handles CORS-proxied fetches and sparse checkouts, so you can use URLs that point to specific subdirectories or branches.
  • This resource can be used with steps like installPlugin and installTheme.
  • Set ".git": true to include a .git folder containing packfiles and refs so Git-aware tooling can detect the checkout. This currently mirrors a shallow clone of the selected ref.
  • The folder name is derived from the URL by default (e.g. https-github-com-WordPress-block-development-examples-HEAD-at-plugins-data-basics-59c8f8). Use options.targetFolderName in the step to override it, as shown in the example above.
+

CoreThemeReference

+

The _CoreThemeReference_ resource is used to reference WordPress core themes. The _CoreThemeReference_ resource is defined as follows:

+
type CoreThemeReference = {
+	resource: 'wordpress.org/themes';
+	slug: string;
+	version?: string;
+};
+

To use the _CoreThemeReference_ resource, you need to provide the slug of the theme. For example, to reference the "Twenty Twenty-One" theme, you can create a _CoreThemeReference_ as follows:

+
{
+	"resource": "wordpress.org/themes",
+	"slug": "twentytwentyone"
+}
+

CorePluginReference

+

The _CorePluginReference_ resource is used to reference WordPress core plugins. The _CorePluginReference_ resource is defined as follows:

+
type CorePluginReference = {
+	resource: 'wordpress.org/plugins';
+	slug: string;
+	version?: string;
+};
+

To use the _CorePluginReference_ resource, you need to provide the slug of the plugin. For example, to reference the "Akismet" plugin, you can create a _CorePluginReference_ as follows:

+
{
+	"resource": "wordpress.org/plugins",
+	"slug": "akismet"
+}
+

VFSReference

+

The _VFSReference_ resource is used to reference files that are stored in a virtual file system (VFS). The VFS is a file system that is stored in memory and can be used to store files that are not part of the file system of the operating system. The _VFSReference_ resource is defined as follows:

+
type VFSReference = {
+	resource: 'vfs';
+	path: string;
+};
+

To use the _VFSReference_ resource, you need to provide the path to the file in the VFS. For example, to reference a file named "index.html" that is stored in the root of the VFS, you can create a _VFSReference_ as follows:

+
{
+	"resource": "vfs",
+	"path": "/index.html"
+}
+

LiteralReference

+

The _LiteralReference_ resource is used to reference files that are stored as literals in the code. The _LiteralReference_ resource is defined as follows:

+
type LiteralReference = {
+	resource: 'literal';
+	name: string;
+	contents: string | Uint8Array;
+};
+

To use the _LiteralReference_ resource, you need to provide the name of the file and its contents. For example, to reference a file named "index.html" that contains the text "Hello, World!", you can create a _LiteralReference_ as follows:

+
{
+	"resource": "literal",
+	"name": "index.html",
+	"contents": "Hello, World!"
+}
+

BundledReference

+

The BundledReference resource is used to reference files that are bundled with the Blueprint itself. This is particularly useful for creating self-contained Blueprint bundles that include all necessary resources. The BundledReference resource is defined as follows:

+
type BundledReference = {
+	resource: 'bundled';
+	path: string;
+};
+

To use the BundledReference resource, you need to provide the relative path to the file within the bundle. For example, to reference a file named "plugin.php" that is bundled with the Blueprint, you can create a BundledReference as follows:

+
{
+	"resource": "bundled",
+	"path": "plugin.php"
+}
+

Blueprint bundles can be distributed in various formats, including:

+
  • ZIP files with a top-level blueprint.json file
  • Directories containing a blueprint.json file and related resources
  • Remote URLs where the Blueprint and its resources are hosted together
+

For more information on Blueprint bundles, see the Blueprint Bundles documentation.

+

Original Playground docs source: https://playground.wordpress.net/blueprints/steps/resources

]]> + + 4 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Shorthands]]> + https://playground.wordpress.net/blueprints-steps-shorthands/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=5 + + Shorthands +

You can specify some steps using a shorthand syntax. The following steps are currently supported:

+

login

+

Use

+
	"login": true,
+

Or

+
{
+	"step": "login",
+	"username": "admin",
+	"password": "password"
+}
+

plugins

+

(replaces the installPlugin step)

+

Use

+
	"plugins": [
+		"hello-dolly",
+		"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+	]
+

Or

+
[
+	{
+		"step": "installPlugin",
+		"pluginData": {
+			"resource": "wordpress.org/plugins",
+			"slug": "hello-dolly"
+		}
+	},
+	{
+		"step": "installPlugin",
+		"pluginData": {
+			"resource": "url",
+			"url": "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+		}
+	}
+]
+

siteOptions

+

Use

+
	"siteOptions": {
+		"blogname": "My first Blueprint"
+	}
+

Or

+
	"step": "setSiteOptions",
+	"options": {
+		"blogname": "My first Blueprint"
+	}
+

defineWpConfigConsts

+

(constants only)

+

Use

+
{
+	"step": "defineWpConfigConsts",
+	"consts": {
+		"WP_DISABLE_FATAL_ERROR_HANDLER": true,
+		"WP_DEBUG": true,
+		"WP_DEBUG_DISPLAY": true
+	}
+}
+

Or

+
	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DISABLE_FATAL_ERROR_HANDLER": true
+		}
+	},
+	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DEBUG": true
+		}
+	},
+	{
+		"step": "defineWpConfigConsts",
+		"consts": {
+			"WP_DEBUG_DISPLAY": true
+		}
+	}
+

---

+

The shorthand syntax and the step syntax correspond to each other. Every step specified with the shorthand syntax is added to the top of the steps array in arbitrary order.

+

Which should you choose?

+
  • Use shorthands when brevity is your main concern.
  • Use explicit steps when you need more control over the execution order.
+

Original Playground docs source: https://playground.wordpress.net/blueprints/steps/shorthands

]]> + + 5 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Steps]]> + https://playground.wordpress.net/blueprints-steps/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=6 + + Steps +

The steps property of a Blueprint is an array of steps to run. For example this Blueprint logs the user in as an admin:

+
<BlueprintExample blueprint={{
+	"steps": [
+		{
+			"step": "login",
+			"username": "admin",
+			"password": "password"
+		}
+	]
+}} />
+

Each step is an object that contains a step property that specifies the type of step to run. The rest of the properties depend on the type of step. Learn and try each step type below.

+

The following step-related topics are addressed on dedicated pages included in this section:

+ +
  • Some steps have a shorthand version. Check the Shorthands section for more information about them.
+
  • For each step listed below, you'll find both a "Blueprint API" and a "Function API". Refer to the API Consistency page for further details.
+

Tip

+

The WordPress Playground Step Library tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!

+

---

+

Blueprint Step Reference

+

activatePlugin

+

Activates a WordPress plugin (if it's installed).

+

Parameters:

+
  • pluginName (string optional): Optional. Plugin name to display in the progress bar.
+
  • pluginPath (string): Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php).
+

Example:

+

+{
+		"step": "activatePlugin",
+		"pluginName": "Gutenberg",
+		"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
+}
+
+

activateTheme

+

Activates a WordPress theme (if it's installed).

+

Parameters:

+
  • themeFolderName (string): The name of the theme folder inside wp-content/themes/
+

Example:

+

+{
+		"step": "activateTheme",
+		"themeFolderName": "storefront"
+}
+
+

cp

+

Copies a file from one path to another.

+

Parameters:

+
  • fromPath (string): Source path
+
  • toPath (string): Target path
+

Example:

+

+{
+		"step": "cp",
+		"fromPath": "/wordpress/index.php",
+		"toPath": "/wordpress/index2.php"
+}
+
+

defineSiteUrl

+

Sets WP_HOME and WP_SITEURL constants for the WordPress installation. Using this step on playground.wordpress.net is moot. It is useful when building a custom Playground-based tool, like wp-now, or deploying Playground on a custom domain.

+

Parameters:

+
  • siteUrl (string): The URL
+

defineWpConfigConsts

+

Defines constants in a wp-config.php file. This step can be called multiple times, and the constants will be merged.

+

Parameters:

+
  • consts (Record): The constants to define
+
  • method ("rewrite-wp-config" | "define-before-run" optional): The method of defining the constants in wp-config.php. Possible values are: - rewrite-wp-config: Default. Rewrites the wp-config.php file to explicitly call define() with the requested name and value. This method alters the file on the disk, but it doesn't conflict with existing define() calls in wp-config.php. - define-before-run: Defines the constant before running the requested script. It doesn't alter any files on the disk, but constants defined this way may conflict with existing define() calls in wp-config.php.
+
  • virtualize (boolean optional)
+

Example:

+

+{
+		"step": "defineWpConfigConsts",
+		"consts": {
+         "WP_DEBUG": true
+     }
+}
+
+

enableMultisite

+

Defines the Multisite constants in a wp-config.php file. This step can be called multiple times, and the constants will be merged.

+

Parameters:

+
  • wpCliPath (string optional): wp-cli.phar path
+

Example:

+

+{
+		"step": "enableMultisite"
+}
+
+

importThemeStarterContent

+

Imports a theme Starter Content into WordPress.

+

Parameters:

+
  • themeSlug (string optional): The name of the theme to import content from.
+

Example:

+

+{
+		"step": "importThemeStarterContent"
+}
+
+

importWordPressFiles

+

Imports top-level WordPress files from a given zip file into the documentRoot. For example, if a zip file contains the wp-content and wp-includes directories, they will replace the corresponding directories in Playground's documentRoot. Any files that Playground recognizes as "excluded from the export" will carry over from the existing document root into the imported directories. For example, the sqlite-database-integration plugin.

+

Parameters:

+
  • pathInZip (string optional): The path inside the zip file where the WordPress files are.
+
  • wordPressFilesZip (ResourceType): The zip file containing the top-level WordPress files and directories.
+

Example:

+

+{
+		"step": "importWordPressFiles",
+		"wordPressFilesZip": {
+			"resource": "url",
+			"url": "https://mysite.com/import.zip"
+ 	}
+}
+
+

importWxr

+

Imports a WXR file into WordPress.

+

Parameters:

+
  • file (ResourceType): The file to import
+
  • importer ("default" | "data-liberation" optional): The importer to use. Possible values: - default: The importer from https://github.com/humanmade/WordPress-Importer - data-liberation: The experimental Data Liberation WXR importer developed at https://github.com/WordPress/wordpress-playground/issues/1894 This option is deprecated. The syntax will not be removed, but once the Data Liberation importer matures, it will become the only supported importer and the importer option will be ignored.
+

Example:

+

+{
+		"step": "importWxr",
+		"file": {
+			"resource": "url",
+			"url": "https://your-site.com/starter-content.wxr"
+		}
+}
+
+

installPlugin

+

Installs a WordPress plugin in the Playground.

+

Parameters:

+
  • ifAlreadyInstalled ("error" | "overwrite" | "skip" optional): What to do if the asset already exists.
+
  • options (InstallPluginOptions optional): Optional installation options.
+
  • pluginData (FileResource | DirectoryResource): The plugin files to install. It can be a plugin zip file, a single PHP file, or a directory containing all the plugin files at its root.
+
  • pluginZipFile (FileResource optional): @deprecated. Use 'pluginData' instead.
+

Example:

+

+{
+		"step": "installPlugin",
+		"pluginData": {
+			"resource": "wordpress.org/plugins",
+			"slug": "gutenberg"
+		},
+		"options": {
+			"activate": true
+		}
+}
+
+

installTheme

+

Installs a WordPress theme in the Playground.

+

Parameters:

+
  • ifAlreadyInstalled ("error" | "overwrite" | "skip" optional): What to do if the asset already exists.
+
  • options (InstallThemeOptions optional): Optional installation options.
+
  • themeData (FileResource | DirectoryResource): The theme files to install. It can be either a theme zip file, or a directory containing all the theme files at its root.
+
  • themeZipFile (FileResource optional): @deprecated. Use 'themeData' instead.
+

Example:

+

+{
+		"step": "installTheme",
+		"themeData": {
+			"resource": "wordpress.org/themes",
+			"slug": "pendant"
+		},
+		"options": {
+			"activate": true,
+			"importStarterContent": true
+		}
+}
+
+

login

+

Logs in to Playground. Under the hood, this function sets the PLAYGROUND_AUTO_LOGIN_AS_USER constant. The 0-auto-login.php mu-plugin uses that constant to log in the user on the first load. This step depends on the @wp-playground/wordpress package because the plugin is located in and loaded automatically by the @wp-playground/wordpress package.

+

Parameters:

+
  • password (string optional)
+
  • username (string optional): The user to log in as. Defaults to 'admin'.
+

Example:

+

+{
+    "step": "login",
+    "username": "admin"
+}
+
+

mkdir

+

Creates a directory at the specified path.

+

Parameters:

+
  • path (string): The path of the directory you want to create
+

Example:

+

+{
+		"step": "mkdir",
+		"path": "/wordpress/my-new-folder"
+}
+
+

mv

+

Moves a file or directory from one path to another.

+

Parameters:

+
  • fromPath (string): Source path
+
  • toPath (string): Target path
+

Example:

+

+{
+		"step": "mv",
+		"fromPath": "/wordpress/index.php",
+		"toPath": "/wordpress/index2.php"
+}
+
+

resetData

+

Deletes WordPress posts and comments and sets the auto increment sequence for the posts and comments tables to 0.

+

Example:

+

+{
+		"step": "resetData"
+}
+
+

rmdir

+

Removes a directory at the specified path.

+

Parameters:

+
  • path (string): The path to remove
+

Example:

+

+{
+		"step": "rmdir",
+		"path": "/wordpress/wp-admin"
+}
+
+

rm

+

Removes a file at the specified path.

+

Parameters:

+
  • path (string): The path to remove
+

Example:

+

+{
+		"step": "rm",
+		"path": "/wordpress/index.php"
+}
+
+

runPHP

+

Runs PHP code. When running WordPress functions, the code key must first load wp-load.php and start with "<?php require_once '/wordpress/wp-load.php'; ".

+

Parameters:

+
  • code (string | object): The PHP code to run.
+

Example:

+

+{
+		"step": "runPHP",
+		"code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
+}
+
+

runPHPWithOptions

+

Runs PHP code. When running WordPress functions, the code key must first load wp-load.php and start with "<?php require_once '/wordpress/wp-load.php'; ".

+

Parameters:

+
  • options (PHPRunOptions): Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/))
+

Example:

+

+{
+		"step": "runPHPWithOptions",
+		"options": {
+			"code": "<?php require_once '/wordpress/wp-load.php'; update_option('blogname', file_get_contents('php://input'));?>",
+			"body": "Site Name Modified by runPHPWithOptions"
+		}
+}
+
+

runSql

+

Run one or more SQL queries. This step uses WP_MySQL_Naive_Query_Stream to parse and execute SQL queries using streaming semantics. It supports multiline queries, comments, and queries separated by semicolons. Each query is executed using $wpdb. This step assumes a presence of the sqlite-database-integration plugin that ships the required query tokenizer classes.

+

Parameters:

+
  • sql (ResourceType): The SQL to run. Each non-empty line must contain a valid SQL query.
+

Example:

+

+{
+		"step": "runSql",
+		"sql": {
+			"resource": "literal",
+			"name": "schema.sql",
+			"contents": "DELETE FROM wp_posts"
+		}
+}
+
+

setSiteLanguage

+

Sets the site language and download translations.

+

Parameters:

+
  • language (string): The language to set, e.g. 'en_US'
+

Example:

+

+{
+		"step": "setSiteLanguage",
+		"language": "en_US"
+}
+
+

setSiteOptions

+

Sets site options. This is equivalent to calling update_option for each option in the options object.

+

Parameters:

+
  • options (Record): The options to set on the site.
+

Example:

+

+{
+    "step": "setSiteOptions",
+    "options": {
+        "blogname": "My Blog",
+        "blogdescription": "A great blog"
+    }
+}
+
+

unzip

+

Unzip a zip file.

+

Parameters:

+
  • extractToPath (string): The path to extract the zip file to
+
  • zipFile (ResourceType optional): The zip file to extract
+
  • zipPath (string optional): The path of the zip file to extract
+

Example:

+

+{
+		"step": "unzip",
+		"zipFile": {
+			"resource": "vfs",
+			"path": "/wordpress/data.zip"
+		},
+		"extractToPath": "/wordpress"
+}
+
+

updateUserMeta

+

Updates user meta. This is equivalent to calling update_user_meta for each meta value in the meta object.

+

Parameters:

+
  • meta (Record): An object of user meta values to set, e.g. { "first_name": "John" }
+
  • userId (number): User ID
+

Example:

+

+{
+    "step": "updateUserMeta",
+    "meta": {
+	       "first_name": "John",
+	       "last_name": "Doe"
+    },
+    "userId": 1
+}
+
+

wp-cli

+

Runs PHP code using WP-CLI.

+

Parameters:

+
  • command (string | string[]): The WP CLI command to run.
+
  • wpCliPath (string optional): wp-cli.phar path
+

Example:

+

+{
+		"step": "wp-cli",
+		"command": "wp post create --post_title='Test post' --post_excerpt='Some content'"
+}
+
+

writeFiles

+

Writes multiple files to a specified directory in the Playground filesystem. `` my-plugin/ ├── index.php └── public/ └── style.css ``

+

Parameters:

+
  • filesTree (DirectoryResource): The 'filesTree' defines the directory structure, supporting 'literal:directory' or 'git:directory' types. The 'name' represents the root directory, while 'files' is an object where keys are file paths, and values contain either file content as a string or nested objects for subdirectories.
+
  • writeToPath (string): The path of the file to write to
+

Example:

+

+{
+		"step": "writeFiles",
+		"writeToPath": "/wordpress/wp-content/plugins/my-plugin",
+		"filesTree": {
+			"name": "my-plugin",
+			"files": {
+				"index.php": "<?php echo '<a>Hello World!</a>'; ?>",
+				"public": {
+					"style.css": "a { color: red; }"
+				}
+			}
+		}
+}
+
+

writeFile

+

Writes data to a file at the specified path.

+

Parameters:

+
  • data (string | Uint8Array | FileResource): The data to write
+
  • path (string): The path of the file to write to
+

Example:

+

+{
+		"step": "writeFile",
+		"path": "/wordpress/test.php",
+		"data": "<?php echo 'Hello World!'; ?>"
+}
+
+

<hr/> </> ))}

+

Original Playground docs source: https://playground.wordpress.net/blueprints/steps

]]> + + 6 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Blueprint Bundles]]> + https://playground.wordpress.net/blueprints-bundles/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=7 + + Blueprint Bundles +

Blueprint bundles are self-contained packages that include a Blueprint declaration (blueprint.json) along with all the additional resources required to compile and run it. This makes it easier to distribute and share complete WordPress Playground setups.

+

What are Blueprint Bundles?

+

A Blueprint bundle is a collection of files that includes:

+
  1. A blueprint.json file that defines the Blueprint configuration
  2. Any additional resources referenced by the Blueprint (themes, plugins, content files, etc.)
+

Blueprint bundles can be distributed in various formats:

+
  • A ZIP file with a top-level blueprint.json file and additional resources
  • A directory inside a git repository where blueprint.json resides alongside other resources
  • A local directory on your computer
  • An inline JavaScript object with the relevant files inlined
+

Using Blueprint Bundles

+

On the Website

+

The WordPress Playground website supports Blueprint bundles through the ?blueprint-url= query parameter. You can provide a URL to a ZIP file containing your Blueprint bundle:

+
https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip
+

The ZIP file should contain a blueprint.json file at the root level, along with any additional resources referenced by the Blueprint.

+

In the CLI

+

The Playground CLI supports Blueprint bundles through the --blueprint= option. You can provide:

+
  • A path to a local directory containing a Blueprint bundle
  • A path to a local ZIP file containing a Blueprint bundle
  • A URL to a remote Blueprint bundle (http:// or https://)
+

For example:

+
# Using a local ZIP file
+npx @wp-playground/cli --blueprint=./my-blueprint.zip server
+
+# Using a remote URL
+npx @wp-playground/cli --blueprint=https://example.com/my-blueprint.zip server
+
+# Using a local directory
+npx @wp-playground/cli --blueprint=./my-blueprint-directory server
+

By default, the CLI restricts access to local files for security reasons. If your Blueprint needs to access files in the same parent directory, you need to explicitly grant permission using the --blueprint-may-read-adjacent-files flag:

+
npx @wp-playground/cli --blueprint=./my-blueprint.json --blueprint-may-read-adjacent-files server
+

Creating Blueprint Bundles

+

Basic Structure

+

A basic Blueprint bundle might look like this:

+
my-blueprint-bundle/
+├── blueprint.json
+├── theme.zip
+├── plugin.zip
+└── content/
+    └── sample-content.wxr
+

Example Blueprint with Bundled Resources

+

Here's an example of a blueprint.json file that references bundled resources:

+
{
+	"landingPage": "/my-file.txt",
+	"steps": [
+		{
+			"step": "writeFile",
+			"path": "/wordpress/my-file.txt",
+			"data": {
+				"resource": "bundled",
+				"path": "/bundled-text-file.txt"
+			}
+		},
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "bundled",
+				"path": "/theme.zip"
+			}
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "bundled",
+				"path": "/plugin.zip"
+			}
+		},
+		{
+			"step": "importWxr",
+			"file": {
+				"resource": "bundled",
+				"path": "/content/sample-content.wxr"
+			}
+		}
+	]
+}
+

In this example, the Blueprint references several bundled resources:

+
  • A text file at /bundled-text-file.txt
  • A theme ZIP file at /theme.zip
  • A plugin ZIP file at /plugin.zip
  • A WXR content file at /content/sample-content.wxr
+

Creating a ZIP Bundle

+

To create a ZIP bundle, simply create a directory with your blueprint.json and all required resources, then zip it up:

+
# Create a directory for your bundle
+mkdir my-blueprint-bundle
+cd my-blueprint-bundle
+
+# Create your blueprint.json and add resources
+# ...
+
+# Zip it up
+zip -r ../my-blueprint-bundle.zip .
+

ZIP File Structure Flexibility

+

Blueprint bundles support blueprint.json at two locations within a ZIP file:

+
  1. Root level (standard): blueprint.json sits directly at the ZIP root
  2. One directory deep: blueprint.json sits inside a single top-level directory
+

This means ZIP files created with macOS's right-click "Compress" feature (which wraps contents in a folder) work automatically. The __MACOSX metadata directory is ignored during detection.

+

Example: Both of these ZIP structures work:

+
# Structure A (root level)
+my-bundle.zip/
+├── blueprint.json
+├── theme.zip
+└── plugin.zip
+
+# Structure B (one directory deep — macOS-style)
+my-bundle.zip/
+├── my-bundle/
+│   ├── blueprint.json
+│   ├── theme.zip
+│   └── plugin.zip
+└── __MACOSX/         ← ignored
+

If multiple top-level directories contain a blueprint.json, Playground returns an error to avoid ambiguity.

+

Troubleshooting

+

If you encounter issues with Blueprint bundles:

+
  1. Ensure your blueprint.json file is at the root level of your ZIP file or inside a single top-level directory
  2. Check that all paths in your bundled resource references are correct
  3. Verify that your ZIP file is properly formatted
  4. When using the CLI, check if you need the --blueprint-may-read-adjacent-files flag
  5. Ensure all required resources are included in the bundle
+

Original Playground docs source: https://playground.wordpress.net/blueprints/bundles

]]> + + 7 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[API Consistency]]> + https://playground.wordpress.net/blueprints-steps-api-consistency/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=8 + + JSON API and Function API +

Blueprints are defined in JSON format, but the underlying implementation uses JavaScript functions to execute the steps. While JSON is the most convenient way of interacting with Blueprints, you can also use the underlying functions directly.

+

JSON is merely a wrapper around the functions. Whether you use the JSON steps or the exported functions, you'll have to provide the same parameters (except for the step name):

+

You can use Blueprints both with the web and the node.js versions of WordPress Playground.

+

Blueprints version 2

+

The team is exploring ways to transition Blueprints from a TypeScript library to a PHP library. This would allow people to run Blueprints in any WordPress environments: Playground, a hosted site, or a local setup.

+

The proposed new specification is discussed on a separate GitHub repository, and you’re more than welcome to join (there or on the #playground Slack channel) and help shape the next generation of Playground.

+

Differences between JSON and Function APIs

+

There are two main differences between the JSON and Function APIs:

+
  1. Blueprints handle the progress bar and error reporting for you. The function API requires you to handle these yourself.
  2. The function API requires importing the API client library while Blueprints may be just pasted into the URL fragment.
+

Note

+

Check the Use the same structure for Blueprint JSON definitions and step handlers issue at wordpress-playground repo for more detailed info about this topic

+

Original Playground docs source: https://playground.wordpress.net/blueprints/steps/api-consistency

]]> + + 8 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Examples]]> + https://playground.wordpress.net/blueprints-examples/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=9 + + Blueprints Examples +

Tip

+

Check the Blueprints Gallery to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.

+

Let's see some cool things you can do with Blueprints.

+

Install a Theme and a Plugin

+
<BlueprintExample blueprint={{
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "coblocks"
+			}
+		},
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "pendant"
+			}
+		}
+	]
+}} />
+

The meta object

+

The optional meta object provides descriptive information about your Blueprint. While it doesn't affect how the Blueprint executes, this information is crucial for display purposes in galleries, Blueprint selectors, and integrated tools like WordPress Studio and Blueprints Gallery.

+

Properties

+
| Field             | Type            | Description                                      |
+| :---------------- | :-------------- | :----------------------------------------------- |
+| **`title`**       | `string`        | A short, human-readable name for the Blueprint.  |
+| **`description`** | `string`        | A brief summary explaining the setup.            |
+| **`author`**      | `string`        | The name or handle of the creator.               |
+| **`categories`**  | `array<string>` | Tags used for filtering and grouping Blueprints. |
+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"meta": {
+		"title": "Default Playground Setup",
+		"description": "A basic setup for a new WordPress site with the latest versions.",
+		"author": "Playground Team",
+		"categories": ["starter", "default"]
+	},
+	"landingPage": "/wp-admin/",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "latest"
+	}
+}
+

Run custom PHP code

+
<BlueprintExample
+display={`{
+	"steps": [
+		{
+			"step": "runPHP",
+			"code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array( 'post_title' => 'Post title', 'post_content' => 'Post content', 'post_status' => 'publish', 'post_author' => 1 )); "
+		}
+	]
+}` }
+blueprint={{
+		"steps": [
+			{
+				"step": "runPHP",
+				"code": `<?php
+require_once '/wordpress/wp-load.php';
+wp_insert_post(array(
+'post_title' => 'Post title',
+'post_content' => 'Post content',
+'post_status' => 'publish',
+'post_author' => 1
+));
+`
+}
+]
+}} />
+

Enable an option on the Gutenberg Experiments page

+

Here: Switch on the "new admin views" feature.

+
<BlueprintExample
+display={`{
+	"steps": [
+		{
+			"step": "runPHP",
+			"code": "<?php require '/wordpress/wp-load.php'; update_option( 'gutenberg-experiments', array( 'gutenberg-dataviews' => true ) );"
+		}
+	]
+}`}
+blueprint={{
+		"steps": [
+			{
+				"step": "runPHP",
+				"code": "<?php require '/wordpress/wp-load.php'; update_option( 'gutenberg-experiments', array( 'gutenberg-dataviews' => true ) );"
+			}
+		]
+}} />
+

How to work with WP-CLI from the terminal and Playground

+

You can run WP-CLI commands on a Playground instance either from your terminal or directly within a Blueprint.

+

To use your terminal, you must first mount the /wordpress/ directory and ensure the SQLite database integration is configured. This is because Playground's internal database doesn't persist on a mounted site, so you must explicitly install the database plugin via a Blueprint. This allows WP-CLI to recognize the WordPress installation and connect to its database.

+

Note

+

If you run WP-CLI commands as steps within your Blueprint file, this manual setup is not needed.

+

The following Blueprint snippet handles this setup:

+
<BlueprintExample blueprint={{
+    "plugins": [ "sqlite-database-integration" ]
+}} />
+

For a detailed explanation of why this is needed, refer to the Troubleshoot and Debug Blueprints section.

+

Showcase a product demo

+
<BlueprintExample noButton blueprint={{
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "url",
+				"url": "https://your-site.com/your-plugin.zip"
+			}
+		},
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "url",
+				"url": "https://your-site.com/your-theme.zip"
+			}
+		},
+		{
+			"step": "importWxr",
+			"file": {
+				"resource": "url",
+				"url": "https://your-site.com/starter-content.wxr"
+			}
+		},
+		{
+			"step": "setSiteOptions",
+			"options": {
+				"some_required_option_1": "your_favorite_values",
+				"some_required_option_2": "your_favorite_values"
+			}
+		}
+	]
+}} />
+

Enable networking

+
<BlueprintExample blueprint={{
+	"landingPage": "/wp-admin/plugin-install.php",
+	"features": {
+		"networking": true
+	},
+	"steps": [
+		{
+			"step": "login"
+		}
+	]
+}} />
+

Load PHP code on every request (mu-plugin)

+

Use the writeFile step to add code to a mu-plugin that runs on every request.

+
<BlueprintExample blueprint={{
+	"landingPage": "/category/uncategorized/",
+	"features": {
+		"networking": true
+	},
+	"steps": [
+		{
+			"step": "login"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/mu-plugins/rewrite.php",
+			"data": "<?php add_action( 'after_setup_theme', function() { global $wp_rewrite; $wp_rewrite->set_permalink_structure('/%postname%/'); $wp_rewrite->flush_rules(); } );"
+		}
+	]
+}} />
+

Code editor (as a Gutenberg block)

+
<BlueprintExample blueprint={{
+  "landingPage": "/wp-admin/post.php?post=4&action=edit",
+  "steps": [
+    {
+      "step": "login",
+      "username": "admin",
+      "password": "password"
+    },
+    {
+      "step": "installPlugin",
+      "pluginData": {
+        "resource": "wordpress.org/plugins",
+        "slug": "interactive-code-block"
+      }
+    },
+    {
+      "step": "runPHP",
+      "code": "<?php require '/wordpress/wp-load.php'; wp_insert_post(['post_title' => 'WordPress Playground block demo!','post_content' => '<!-- wp:wordpress-playground/playground /-->', 'post_status' => 'publish', 'post_type' => 'post',]);"
+    }
+  ]
+}} />
+

You can share your own Blueprint examples in this dedicated wiki.

+

Load an older WordPress version

+

Playground only ships with a few recent WordPress releases. If you need to use an older version, this Blueprint can help you: change the version number in "url": "https://playground.wordpress.net/plugin-proxy.php?url=https://wordpress.org/wordpress-6.2.1.zip" from 6.2.1 to the release you want to load.

+

Note: the oldest supported WordPress version is 6.2.1, following the SQLite integration plugin.

+
<BlueprintExample blueprint={{
+  "landingPage": "/wp-admin",
+  "preferredVersions": {
+    "wp": "https://playground.wordpress.net/plugin-proxy.php?url=https://wordpress.org/wordpress-6.2.1.zip",
+    "php": "8.3"
+  },
+  "features": {
+    "networking": true
+  },
+  "steps": [
+    {
+      "step": "login",
+      "username": "admin",
+      "password": "password"
+    }
+  ]
+}} />
+

Run WordPress from trunk or a specific commit.

+

WordPress Playground can run trunk (the latest commit), the HEAD of a specific branch or a specific commit from the WordPress/WordPress GitHub repository.

+

You can specify the reference in "url": "https://playground.wordpress.net/plugin-proxy.php?build-ref=trunk".

+

To specify the latest commit of a particular branch, you can change the reference to the branch version number, eg 6.6. To run a specific commit, you can use the commit hash from WordPress/WordPress, eg 7d7a52367dee9925337e7d901886c2e9b21f70b6.

+

Note: the oldest supported WordPress version is 6.2.1, following the SQLite integration plugin.

+
<BlueprintExample blueprint={{
+    "landingPage": "/wp-admin",
+	"login" : true,
+	"preferredVersions" : {
+		"php": "8.3",
+		"wp": "https://playground.wordpress.net/plugin-proxy.php?build-ref=trunk"
+	}
+}} />
+

Using Blueprint Bundles

+

Here's an example of a Blueprint that uses bundled resources from a Blueprint bundle:

+
{
+	"landingPage": "/",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "latest"
+	},
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "bundled",
+				"path": "/my-theme.zip"
+			},
+			"activate": true
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "bundled",
+				"path": "/my-plugin.zip"
+			},
+			"activate": true
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/custom-page.html",
+			"data": {
+				"resource": "bundled",
+				"path": "/assets/custom-page.html"
+			}
+		}
+	]
+}
+

This Blueprint bundle would be zip file containing the following files:

+
  • /blueprint.json - The blueprint declaration outlined above
  • /my-theme.zip - A theme package
  • /my-plugin.zip - A plugin package
  • /assets/custom-page.html - A custom HTML file
+

You can use this Blueprint bundle by:

+
  1. Creating a ZIP file with these files and the blueprint.json
  2. Hosting the ZIP file on a server
  3. Loading it with ?blueprint-url=https://example.com/my-blueprint-bundle.zip
+

For more information on Blueprint bundles, see the Blueprint Bundles documentation.

+

Original Playground docs source: https://playground.wordpress.net/blueprints/examples

]]> + + 9 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Troubleshoot and debug]]> + https://playground.wordpress.net/blueprints-troubleshoot-and-debug/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=10 + + Troubleshoot and debug Blueprints +

When you build Blueprints, you might run into issues. Here are tips and tools to help you debug them:

+

Review Common gotchas

+
  • Require wp-load: to run a WordPress PHP function using the runPHP step, you’d need to require wp-load.php. So, the value of the code key should start with "<?php require_once('wordpress/wp-load.php'); REST_OF_YOUR_CODE".
+

Common Issues and Solutions

+

WP-CLI: Error Establishing a Database Connection on Mounted Sites

+

When using wp-cli with a mounted Playground site (e.g., via --mount-before-install), you might encounter an "Error establishing a database connection." This happens because WordPress Playground loads the SQLite database integration plugin from its internal files by default, not from the mounted directory, meaning it's not persisted for external wp-cli calls.

+

To resolve this, you need to explicitly install and configure the SQLite database integration plugin within your Blueprint.

+

Solution: Add the following steps to your Blueprint:

+
{
+	"plugins": ["sqlite-database-integration"]
+}
+

Example Usage:

+

To test this locally, combine the Blueprint with your Playground CLI command:

+
mkdir wordpress
+# Ensure your blueprint with the above steps is saved as, for example, './blueprint.json'
+npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json
+cd wordpress
+wp post list
+

This will ensure the SQLite plugin is installed correctly and configured within your mounted WordPress site, allowing wp-cli commands to function correctly.

+

Blueprints Builder

+

You can use an in-browser Blueprints editor to build, validate, and preview your Blueprints in the browser.

+

Danger: Caution

+

The editor is under development and the embedded Playground sometimes fails to load. To get around it, refresh the page. We're aware of that, and are working to improve the experience.

+

Check for the Filesystem and Database

+

Some blueprint steps (such as writeFile) alter the internal Filesystem structure of the Playground instance and some others (such as runSql) alter the internal WordPress database.

+

To check the final internal filesystem structure and database (after the blueprint steps have been applied) we can leverage some WordPress plugins that provide a SQL manager and a file explorer such as SQL Buddy and WPide (you can see them in action from https://playground.wordpress.net/?plugin=sql-buddy&plugin=wpide)

+

Tip

+

There are a bunch of methods we can launch from the console of any WordPress Playground instance to inspect the internals of that instance. They're exposed as part of window.playground object (see Developers > JavaScript API > Debugging and testing). Some examples:

+
> await playground.isDir("/wordpress/wp-content/plugins")
+true
+> await playground.listFiles("/wordpress/wp-content/plugins")
+(3) ['hello.php', 'index.php', 'WordPress-Importer-master']
+

Full list of methods we can use is available here

+

Check for errors in the browser console

+

If your Blueprint isn’t running as expected, open the browser developer tools to check for any errors.

+

To open the developer tools in Chrome, Firefox, Safari\*, and Edge: press Ctrl + Shift + I on Windows/Linux or Cmd + Option + I on macOS.

+

Caution

+

If you haven't yet, enable the Develop menu: go to Safari > Settings... > Advanced and check Show features for web developers.

+

The developer tools window allows you to inspect network requests, view console logs, debug JavaScript, and examine the DOM and CSS styles applied to your webpage. This is crucial for diagnosing and fixing issues with Blueprints.

+

Log your own error messages

+

You can error_log your own error messages through runPHP step (see blueprint example and live demo) and check them from the "View Logs" option or from the browser's console.

+

Log errors snapshot

+

When you download your Playground instance as a zip through the "Download as zip" option you'll also download the debug.log file containing all the logs from your Playground instance.

+

Ask for help

+

The community is here to help! If you have questions or comments, open a new issue in this repository. Remember to include the following details:

+
  • The Blueprint you’re trying to run.
  • The error message you’re seeing, if any.
  • The full output from the browser developer tools.
  • Any other relevant information that might help us understand the issue: OS, browser version, etc.
+

Original Playground docs source: https://playground.wordpress.net/blueprints/troubleshoot-and-debug

]]> + + 10 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Introduction]]> + https://playground.wordpress.net/blueprints/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=11 + + Blueprints Docs +

Tip

+

Check the Blueprints Gallery to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.

+

Hi! Welcome to WordPress Playground Blueprints documentation.

+

Blueprints are JSON files for setting up your very own WordPress Playground instance. This subsite (Blueprints Docs) is where you will find all the information you need to use Blueprints.

+

<p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>

+
  • Documentation – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs.
  • 👉 Blueprints (you're here) – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from this Blueprints docs hub.
  • Developers – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in the Developers docs hub.
  • API Reference – All the APIs exposed by WordPress Playground
+

Navigating the Blueprints documentation hub

+

This docs hub is focused on Blueprints info and is divided into the following major sections:

+ +
  • Tutorial - Blueprints 101 - Blueprints API crash course. The tutorial will guide you through the complete process of creating a blueprint that loads a theme and plugin (among other things).
+
  • Blueprint data Format: Blueprint JSON files define your Playground instance with various properties. This section highlights the key properties you need to know.
+ +
  • Steps: API Reference of all the available steps that can be set in a blueprint to run tasks such as login, plugin/theme activation, file operations, and more.
+
  • Blueprint Bundles: Learn how to create and use Blueprint bundles - self-contained packages that include a Blueprint and all its resources.
+
  • Examples: Compilation of Blueprint examples for various WordPress Playground setups, including installing themes/plugins, running PHP code, enabling features, and loading specific WordPress versions.
+ +

Original Playground docs source: https://playground.wordpress.net/blueprints

]]> + + 11 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[What are Blueprints?]]> + https://playground.wordpress.net/blueprints-tutorial-what-are-blueprints-what-you-can-do-with-them/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=12 + + What are Blueprints, and what can you do with them? +

With WordPress Playground you can create a whole website, including plugins, themes, content (posts, pages, taxonomy, and comments), settings (site name, users, permalinks, and more), etc. They allow you to generate a WooCommerce store complete with products, a magazine populated with articles, a corporate blog with multiple users, and more.

+

Blueprints are JSON files that you can use to configure Playground instances.

+

Blueprints support advanced use cases, like file system and database manipulation, and give you fine-grained control over the instance you create. The WordPress Test Team has been using Playground in the 6.5 beta release cycle, creating a Blueprint that loads the latest version, several testing plugins, and dummy data.

+

A simple example

+

A Blueprint might look something like this:

+
{
+	"plugins": ["akismet", "gutenberg"],
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "twentynineteen"
+			}
+		}
+	],
+	"siteOptions": {
+		"blogname": "My Blog",
+		"blogdescription": "Just another WordPress site"
+	},
+	"constants": {
+		"WP_DEBUG": true
+	}
+}
+

The Blueprint above installs the _Akismet_ and _Gutenberg_ plugins and the _Twenty Nineteen_ theme, sets the site name and description, and enables the WordPress debugging mode.

+

The benefits of Blueprints

+

Blueprints are an invaluable tool for building WordPress sites via Playground

+
  • Flexibility: developers can make granular adjustments to the build process.
  • Consistency: ensure that every new site starts with the same configuration.
  • Lightweight: small text files that are easy to store and transfer.
  • Transparency: A Blueprint includes all the commands needed to build a snapshot of a WordPress site. You can read through it and understand how the site is built.
  • Productivity: reduces the time-consuming process of manually setting up a new WordPress site. Instead of installing and configuring themes and plugins for each new project, apply a Blueprint and set everything in one process.
  • Up-to-date dependencies: fetch the latest version of WordPress, a particular plugin, or a theme. Your snapshot is always up to date with the latest features and security fixes.
  • Collaboration: the JSON files are easy to review in tools like GitHub. Share Blueprints with your team or the WordPress community. Allowing others to use your well-configured setup.
  • Experimentation and Learning: For those new to WordPress or looking to experiment with different configurations, Blueprints provide a safe and easy way to try new setups without "breaking" a live site.
  • WordPress.org integration: offer a demo of your plugin in the WordPress plugin directory, or a preview in a Theme Trac ticket.
  • Spinning a development environment: A new developer in the team could download the Blueprint, run a hypothetical wp up command, and get a fresh developer environments—loaded with everything they need. The entire CI/CD process can reuse the same Blueprint.
+

More Resources

+

Visit these links to learn more about the (endless) possibilities of Blueprints:

+ +

Original Playground docs source: https://playground.wordpress.net/blueprints/tutorial/what-are-blueprints-what-you-can-do-with-them

]]> + + 12 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[How to run Blueprints]]> + https://playground.wordpress.net/blueprints-tutorial-how-to-load-run-blueprints/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=13 + + How to load and run Blueprints +

URL fragment

+

The fastest way to run Blueprints is to paste one into the URL "fragment" of a WordPress Playground website. Just add a # after the .net/.

+

Let's say you want to create a Playground with specific versions of WordPress and PHP using the following Blueprint:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "5.9"
+	}
+}
+

To run it, go to https://playground.wordpress.net/#{"preferredVersions": {"php":"8.3", "wp":"5.9"}}. You can also use the button below:

+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Use this method to run the example code in the next chapter, Build your first Blueprint.

+

Base64 encoded Blueprints

+

Some tools, including GitHub, might not format the Blueprint correctly when pasted into the URL. In such cases, encode your Blueprint in Base64 and append it to the URL. For example, that's the above Blueprint in Base64 format: eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19.

+

To run it, go to https://playground.wordpress.net/#eyJwcmVmZXJyZWRWZXJzaW9ucyI6IHsicGhwIjoiNy40IiwgIndwIjoiNS45In19

+

Load Blueprint from a URL

+

When your Blueprint gets too wieldy, you can load it via the ?blueprint-url query parameter in the URL, like this:

+

https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/latest-gutenberg/blueprint.json

+

Note that the Blueprint must be publicly accessible and served with the correct Access-Control-Allow-Origin header:

+
Access-Control-Allow-Origin: *
+

Original Playground docs source: https://playground.wordpress.net/blueprints/tutorial/how-to-load-run-blueprints

]]> + + 13 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Build your first Blueprint]]> + https://playground.wordpress.net/blueprints-tutorial-build-your-first-blueprint/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=14 + + Let's build an elementary Blueprint that

+
  1. Creates a new WordPress site
  2. Sets the site title to "My first Blueprint"
  3. Installs the _Adventurer_ theme
  4. Installs the _Hello Dolly_ plugin from the WordPress plugin directory
  5. Installs a custom plugin
  6. Changes the site content
+

1. Create a new WordPress site

+

Let's start by creating a blueprint.json file with the following contents:

+
{}
+

It may seem like nothing is happening, but this Blueprint already spins up a WordPress site with the latest major version.

+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Tip: Autocomplete

+

If you use an IDE, like VS Code or PHPStorm, you can use the Blueprint JSON Schema for an autocompleted Blueprint development experience. Add the following line at the top of your blueprint.json file:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json"
+}
+

Here's what it looks like in VS Code:

+

Autocompletion visualized

+

2. Set the site title to "My first Blueprint"

+

Blueprints consist of a series of steps that define how to build a WordPress site. Before you write the first step, declare an empty list of steps:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"steps": []
+}
+

This Blueprint isn't very exciting—it creates the same default site as the empty Blueprint above. Let's do something about it!

+

WordPress stores the site title in the blogname option. Add your first step and set that option to "My first Blueprint":

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"steps": [
+		{
+			"step": "setSiteOptions",
+			"options": {
+				"blogname": "My first Blueprint"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

The setSiteOptions step specifies the site options in the WordPress database. The options object contains the key-value pairs to set. In this case, you changed the value of the blogname key to "My first Blueprint". You can read more about all available steps in the Blueprint Steps API Reference.

+

Shorthands

+

You can specify some steps using a shorthand syntax. For example, you could write the setSiteOptions step like this:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	}
+}
+

The shorthand syntax and the step syntax correspond with each other. Every step specified with the shorthand syntax is automatically added at the beginning of the steps array in an arbitrary order. Which should you choose? Use shorthands when brevity is your main concern, use steps when you need more control over the order of execution.

+

3. Install the _Adventurer_ theme

+

Adventurer is an open-source theme available in the WordPress theme directory. Let's install it using the installTheme step:

+
{
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

The site should now look like the screenshot below:

+

Site with the adventurer theme

+

Resources

+

The themeData defines a resource and references an external file required to complete the step. Playground supports different types of resources, including

+
  • url,
  • wordpress.org/themes,
  • wordpress.org/plugins,
  • vfs(virtual file system), or
  • literal.
+

The example uses the wordpress.org/themes resource, which requires a slug identical to the one used in WordPress theme directory:

+

In this case, https://wordpress.org/themes/<slug>/ becomes https://wordpress.org/themes/adventurer/.

+

Note

+

Learn more about the supported resources in the Blueprint Resources API Reference.

+

4. Install the _Hello Dolly_ plugin

+

A classic WordPress plugin that displays random lyrics from the song "Hello, Dolly!" in the admin dashboard. Let's install it using the installPlugin step:

+
{
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "hello-dolly"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

The Hello Dolly plugin is now installed and activated.

+

Like the themeData, the pluginData defines a reference to an external file required for the step. The example uses the wordpress.org/plugins resource to install the plugin with the matching slug from the WordPress plugin directory.

+

5. Install a custom plugin

+

Let's install a custom WordPress plugin that adds a message to the admin dashboard:

+
<?php
+/*
+Plugin Name: "Hello" on the Dashboard
+Description: A custom plugin to showcase WordPress Blueprints
+Version: 1.0
+Author: WordPress Contributors
+*/
+
+function my_custom_plugin() {
+    echo '<h1>Hello from My Custom Plugin!</h1>';
+}
+
+add_action('admin_notices', 'my_custom_plugin');
+

You can use the installPlugin, but that requires creating a ZIP file. Let's start with something different to see if the plugin works:

+
  1. Create a wp-content/plugins/hello-from-the-dashboard directory using the mkdir step.
  2. Write a plugin.php file using the writeFile step.
  3. Activate the plugin using the activatePlugin step.
+

Here's what that looks like in a Blueprint:

+
{
+	// ...
+	"steps": [
+		// ...
+		{
+			"step": "mkdir",
+			"path": "/wordpress/wp-content/plugins/hello-from-the-dashboard"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/plugins/hello-from-the-dashboard/plugin.php",
+			"data": "<?php\n/*\nPlugin Name: \"Hello\" on the Dashboard\nDescription: A custom plugin to showcase WordPress Blueprints\nVersion: 1.0\nAuthor: WordPress Contributors\n*/\n\nfunction my_custom_plugin() {\n    echo '<h1>Hello from My Custom Plugin!</h1>';\n}\n\nadd_action('admin_notices', 'my_custom_plugin');"
+		},
+		{
+			"step": "activatePlugin",
+			"pluginPath": "hello-from-the-dashboard/plugin.php"
+		}
+	]
+}
+

The last thing to do is log the user in as an admin. You can do that with a shorthand of the login step:

+
{
+	"login": true,
+	"steps": {
+		// ...
+	}
+}
+

Here's the complete Blueprint:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"login": true,
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "hello-dolly"
+			}
+		},
+		{
+			"step": "mkdir",
+			"path": "/wordpress/wp-content/plugins/hello-from-the-dashboard"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/plugins/hello-from-the-dashboard/plugin.php",
+			"data": "<?php\n/*\nPlugin Name: \"Hello\" on the Dashboard\nDescription: A custom plugin to showcase WordPress Blueprints\nVersion: 1.0\nAuthor: WordPress Contributors\n*/\n\nfunction my_custom_plugin() {\n    echo '<h1>Hello from My Custom Plugin!</h1>';\n}\n\nadd_action('admin_notices', 'my_custom_plugin');"
+		},
+		{
+			"step": "activatePlugin",
+			"pluginPath": "hello-from-the-dashboard/plugin.php"
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

That's what it looks like when you navigate to the dashboard:

+

Site with the custom plugin

+

Create a plugin and zip it

+

Encoding PHP files as JSON can be useful for quick testing, but it's inconvenient and difficult to read. Instead, create a file with the plugin code, compress it, and use the ZIP file as the resource in the installPlugin step to install it (the path in the URL should match the one in your GitHub repository):

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"login": true,
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "hello-dolly"
+			}
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+			}
+		}
+	]
+}
+

You can shorten that Blueprint even more using the shorthand syntax:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"login": true,
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"plugins": ["hello-dolly", "https://raw.githubusercontent.com/wordpress/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"],
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

6. Change the site content

+

Finally, let's delete the default content of the site and import a new one from a WordPress export file (WXR).

+

Delete the old content

+

There isn't a Blueprint step to delete the default content, but you can do that with a snippet of PHP code:

+
<?php
+require '/wordpress/wp-load.php';
+
+// Delete all posts and pages
+$posts = get_posts(array(
+    'numberposts' => -1,
+    'post_type' => array('post', 'page'),
+    'post_status' => 'any'
+));
+
+foreach ($posts as $post) {
+    wp_delete_post($post->ID, true);
+}
+

To run that code during the site setup, use the runPHP step:

+
{
+	// ...
+	"steps": [
+		// ...
+		{
+			"step": "runPHP",
+			"code": "<?php\nrequire '/wordpress/wp-load.php';\n\n$posts = get_posts(array(\n    'numberposts' => -1,\n    'post_type' => array('post', 'page'),\n    'post_status' => 'any'\n));\n\nforeach ($posts as $post) {\n    wp_delete_post($post->ID, true);\n}"
+		}
+	]
+}
+

Import the new content

+

Let's use the importWxr step to import a WordPress export (WXR) file that helps test WordPress themes. The file is available in the WordPress/theme-test-data repository, and you can access it via its raw.githubusercontent.com address: https://raw.githubusercontent.com/WordPress/theme-test-data/master/themeunittestdata.wordpress.xml.

+

Here's what the final Blueprint looks like:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"login": true,
+	"siteOptions": {
+		"blogname": "My first Blueprint"
+	},
+	"plugins": ["hello-dolly", "https://raw.githubusercontent.com/wordpress/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"],
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "adventurer"
+			}
+		},
+		{
+			"step": "runPHP",
+			"code": "<?php\nrequire '/wordpress/wp-load.php';\n\n$posts = get_posts(array(\n    'numberposts' => -1,\n    'post_type' => array('post', 'page'),\n    'post_status' => 'any'\n));\n\nforeach ($posts as $post) {\n    wp_delete_post($post->ID, true);\n}"
+		},
+		{
+			"step": "importWxr",
+			"file": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/WordPress/theme-test-data/master/themeunittestdata.wordpress.xml"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

And that's it. Congratulations on creating your first Blueprint! 🥳

+

Original Playground docs source: https://playground.wordpress.net/blueprints/tutorial/build-your-first-blueprint

]]> + + 14 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Blueprints 101]]> + https://playground.wordpress.net/blueprints-tutorial/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=15 + + Blueprints 101 - A crash course +

Welcome to a Blueprints crash course, where you'll find everything you need to know about Blueprints: what they are, how to create them, and how to use them effectively.

+
  1. What are Blueprints, and what can you do with them?
  2. How to load and run Blueprints
  3. Build your first Blueprint
+

Tip

+

If you encounter any issues while following this tutorial, refer to the Troubleshoot and debug Blueprints section for tips and tools to help you solve them.

+

Original Playground docs source: https://playground.wordpress.net/blueprints/tutorial

]]> + + 15 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Quick Start Guide for Developers]]> + https://playground.wordpress.net/developers-build-your-first-app/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=16 + + Quick Start Guide for Developers +

WordPress Playground was created as a programmable tool. Below you'll find a few examples of what you can do with it. Each discussed API is described in detail in the APIs section:

+

Embed WordPress on your website

+

Playground can be embedded on your website using the HTML <iframe> tag as follows:

+
<iframe src="https://playground.wordpress.net/"></iframe>
+

Every visitor will get their own private WordPress instance for free. You can then customize it using one of the Playground APIs.

+

Caution: Careful with the demo site

+

The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.

+

If you need certain availability, you should host your own WordPress Playground.

+

Control the embedded website

+

WordPress Playground provides three APIs you can use to control the iframed website. All the examples in this section are built using one of these:

+
  • Query API enable basic operations using only query parameters
  • Blueprints API give you a great degree of control with a simple JSON file
  • JavaScript API give you full control via a JavaScript client from an npm package
+

Learn more about each of these APIs in the APIs overview section.

+

Showcase a plugin or theme from WordPress directory

+

You can install plugins and themes from the WordPress directory with only URL parameters. This iframe preinstalls the coblocks and friends plugins and the pendant theme. This is called Query API and you can learn more about it here.

+
<iframe src="https://playground.wordpress.net/?plugin=coblocks"></iframe>
+

Showcase any plugin or theme

+

What if your plugin is not in the WordPress directory?

+

You can still showcase it on Playground by using JSON Blueprints. For example, this Blueprint would download and install a plugin and a theme from your website and also import some starter content:

+
{
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "url",
+				"url": "https://your-site.com/your-plugin.zip"
+			}
+		},
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "url",
+				"url": "https://your-site.com/your-theme.zip"
+			}
+		},
+		{
+			"step": "importWxr",
+			"file": {
+				"resource": "url",
+				"url": "https://your-site.com/starter-content.wxr"
+			}
+		}
+	]
+}
+

See getting started with Blueprints to learn more.

+

Preview pull requests from your repository

+

You can preview repository code two ways: directly with git:directory, or by pointing to a .zip from your CI pipeline. Here's the git:directory approach using Blueprints:

+
{
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "git:directory",
+				"url": "https://github.com/my-user/my-repo",
+				"ref": "refs/pull/1/head",
+				"refType": "refname"
+			},
+			"options": {
+				"activate": true
+			},
+			"progress": {
+				"caption": "Installing plugin from my-user/my-repo PR #1"
+			}
+		}
+	]
+}
+

In the code above, it will install a plugin from a repository located at the url, and the reference to find the branch is refType; in this case, it will use refname, but it can also use branch, tag, and commit.

+

Tip

+

You can automate this process using the GitHub Action to generate preview links, which will help streamline the process.

+

Loading a .zip file is another alternative for previewing your project. See the live example of Gutenberg PR previewer.

+

To use Playground as a PR previewer, you need:

+
  • A CI pipeline that bundles your plugin or theme
  • Public access to the generated .zip file
+

Those zip bundles aren't any different from regular WordPress Plugins, which means you can install them in Playground using the JSON Blueprints API. Once you expose an endpoint like https://your-site.com/pull-request-1234.zip, the following Blueprint will do the rest:

+
{
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "url",
+				"url": "https://your-site.com/pull-request-1234.zip"
+			}
+		}
+	]
+}
+

The official Playground demo uses this technique to preview pull requests from the Gutenberg repository:

+
<BlueprintExample
+blueprint={{
+	"landingPage": "/wp-admin/plugins.php?test=42test",
+	"steps": [
+		{
+			"step": "login",
+			"username": "admin",
+			"password": "password"
+		},
+		{
+			"step": "mkdir",
+			"path": "/wordpress/pr"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/pr/pr.zip",
+			"data": {
+				"resource": "url",
+				"url": "/plugin-proxy.php?org=WordPress&repo=gutenberg&workflow=Build%20Gutenberg%20Plugin%20Zip&artifact=gutenberg-plugin&pr=60819",
+				"caption": "Downloading Gutenberg PR 47739"
+			},
+			"progress": {
+				"weight": 2,
+				"caption": "Applying Gutenberg PR 47739"
+			}
+		},
+		{
+			"step": "unzip",
+			"zipPath": "/wordpress/pr/pr.zip",
+			"extractToPath": "/wordpress/pr"
+		},
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "vfs",
+				"path": "/wordpress/pr/gutenberg.zip"
+			}
+		}
+	]
+	}} />
+

Preview WordPress Core and Gutenberg Branches or PRs

+

You can preview specific pull requests from WordPress Core and Gutenberg repositories using Query API parameters. Gutenberg branches also have an alternative to preview them with the parameter gutenberg-branch. This is useful for testing the latest trunk changes or specific feature branches without creating a PR.

+
  • Preview a specific WordPress Core PR: https://playground.wordpress.net/?core-pr=9500
  • Preview a specific Gutenberg PR: https://playground.wordpress.net/?gutenberg-pr=73010
  • Preview the Gutenberg trunk branch: https://playground.wordpress.net/?gutenberg-branch=trunk
+

Build a compatibility testing environment

+

Test your plugin across PHP and WordPress versions by configuring them in Playground. This helps you verify compatibility before release.

+

With the Query API, you'd simply add the php and wp query parameters to the URL:

+
<iframe src="https://playground.wordpress.net/?php=8.3&wp=6.1"></iframe>
+

With JSON Blueprints, you'd use the preferredVersions property:

+
{
+	"preferredVersions": {
+		"php": "8.3",
+		"wp": "6.1"
+	}
+}
+

Run PHP code in the browser

+

The JavaScript API provides the run() method which you can use to run PHP code in the browser:

+
<iframe id="wp"></iframe>
+<script type="module">
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: 'https://playground.wordpress.net/remote.html',
+	});
+	await client.isReady;
+	await client.run({
+		code: `<?php
+		require("/wordpress/wp-load.php");
+
+		update_option("blogname", "Playground is really cool!");
+		echo "Site title updated!";
+		`,
+	});
+	client.goTo('/');
+</script>
+

Combine that with a code editor like Monaco or CodeMirror, and you'll get live code snippets like in this article!

+

Original Playground docs source: https://playground.wordpress.net/developers/build-your-first-app

]]> + + 16 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[wp-now]]> + https://playground.wordpress.net/developers-local-development-wp-now/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=17 + +

Caution: Package deprecated

+

The NPM package @wp-now/wp-now is deprecated and won't receive updates in the future. To use a command-line tool in your developer workflow, use the NPM package @wp-playground/cli.

+

wp-now NPM package

+

wp-now is a command-line tool designed to simplify the process of running WordPress locally. It provides a quick and easy way to set up a local WordPress environment with minimal configuration.

+

Key Features:

+
  • Command-line Interface: Easy to use for developers comfortable with CLI.
  • Quick Setup: Set up a local WordPress environment in seconds.
  • Customizable: Allows for configuration to suit specific development needs.
+

@wp-now/wp-now is a CLI tool to spin up a WordPress site with a single command. Similarly to the VS Code extension, it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache are required.

+

Documentation

+

wp-now is maintained in a different GitHub repository, Playground Tools. You can find the latest documentation in the dedicated README file.

+

Launch wp-now in a plugin or theme directory

+

Navigate to your plugin or theme directory and start wp-now with the following commands:

+
cd my-plugin-or-theme-directory
+npx @wp-now/wp-now start
+

Launch wp-now in the wp-content directory with options

+

You can also start wp-now from any wp-content folder. The following example passes parameters for changing the PHP and WordPress versions and loading a blueprint file.

+
cd my-wordpress-folder/wp-content
+npx @wp-now/wp-now start --wp=6.4 --php=8.3 --blueprint=path/to/blueprint.json
+

Install wp-now globally

+

Alternatively, you can install @wp-now/wp-now globally to load it from any directory:

+
npm install -g @wp-now/wp-now
+cd my-plugin-or-theme-directory
+wp-now start
+

Original Playground docs source: https://playground.wordpress.net/developers/local-development/wp-now

]]> + + 17 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[VS Code extension]]> + https://playground.wordpress.net/developers-local-development-vscode-extension/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=18 + + VS Code extension +

Start a zero-setup development environment using the VS Code extension, and develop your plugin or theme locally without installing Apache or MySQL.

+

Key Features:

+
  • Integrated Development: Develop WordPress sites directly within VS Code.
  • Ease of Use: Simplifies the development workflow with integrated tools.
+

Documentation

+

The VS Code extension is maintained in a different GitHub repository, Playground Tools. You can find the latest documentation in the dedicated README file.

+

Installation and Usage:

+
  1. Install the Extension: Search for “WordPress Playground” in the VS Code extensions marketplace and install it.
  2. Setup: Follow the setup instructions provided in the extension to configure your development environment.
  3. Develop and Debug: Use the integrated tools to develop and debug your WordPress site.
+

The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. Once installed, all you have to do is click the Start WordPress Server button in VS Code:

+

Original Playground docs source: https://playground.wordpress.net/developers/local-development/vscode-extension

]]> + + 18 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[php-wasm/node]]> + https://playground.wordpress.net/developers-local-development-php-wasm-node/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=19 + + Using WordPress Playground in Node.js +

As a WebAssembly project, you can also use WordPress Playground in Node.js.

+

If you need low-level control over the underlying WebAssembly PHP build, take a look at the @php-wasm/node package which ships the PHP WebAssembly runtime. This package is at the core of all WordPress Playground tools for Node.js.

+

Consult the complete list of Classes, Functions, Interfaces, and Type Aliases.

+

WebAssembly PHP for Node.js

+

This package ships WebAssembly PHP binaries and the JavaScript API optimized for Node.js. It uses the host file system directly and can access the network if you plug in a custom WS proxy.

+

Basic usage

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+const output = await php.runStream({
+	code: '<?php phpinfo(); ?>',
+});
+console.log(await output.stdoutText);
+

Use cases

+

Run PHP inside Node.js without a native PHP install. Allow developer to produce the following solutions:

+
  • CI/CD jobs and developer tooling.
  • Support education and WordPress workflows: Power interactive tutorials, sandboxes, and coding challenges.
  • Generate content and prototype server behavior.
  • Render HTML using PHP templates, and quickly stand up mock API endpoints to simulate requests.
+

Practical demos

+

We will list some examples using the PHP-WASM package.

+

Demo 1: File system operations

+

Execute PHP scripts that interact with the file system:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// Create directory structure
+php.mkdir('/app/data');
+
+// Write configuration file
+await php.writeFile(
+	'/app/config.json',
+	JSON.stringify({
+		app: 'MyApp',
+		version: '1.0.0',
+		debug: true,
+	})
+);
+
+// Create and run PHP script that reads the config
+await php.writeFile(
+	'/app/index.php',
+	`<?php
+$config = json_decode(file_get_contents('/app/config.json'), true);
+echo "Application: " . $config['app'] . "\\n";
+echo "Version: " . $config['version'] . "\\n";
+echo "Debug Mode: " . ($config['debug'] ? 'ON' : 'OFF') . "\\n";
+
+// List all files
+echo "\\nFiles in /app:\\n";
+foreach (scandir('/app') as $file) {
+    if ($file !== '.' && $file !== '..') {
+        echo "  - $file\\n";
+    }
+}
+?>`
+);
+
+const result = await php.runStream({ scriptPath: '/app/index.php' });
+console.log(await result.stdoutText);
+

Demo 2: SQLite database operations

+

Use PHP's SQLite extension for data storage:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// Create directory for database
+php.mkdir('/data');
+
+// Create database, insert data, and query
+const result = await php.runStream({
+	code: `<?php
+// Create/connect to SQLite database
+$db = new SQLite3('/data/app.db');
+
+// Create table
+$db->exec('CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+)');
+
+// Insert sample data
+$stmt = $db->prepare('INSERT INTO users (name, email) VALUES (?, ?)');
+$users = [
+    ['Alice Johnson', 'alice@example.com'],
+    ['Bob Smith', 'bob@example.com'],
+    ['Charlie Davis', 'charlie@example.com']
+];
+
+foreach ($users as $user) {
+    $stmt->bindValue(1, $user[0]);
+    $stmt->bindValue(2, $user[1]);
+    $stmt->execute();
+}
+
+// Query data
+echo "All Users:\\n";
+echo str_repeat('-', 50) . "\\n";
+$results = $db->query('SELECT * FROM users ORDER BY name');
+while ($row = $results->fetchArray(SQLITE3_ASSOC)) {
+    echo "ID: {$row['id']} | {$row['name']} ({$row['email']})\\n";
+}
+
+$db->close();
+?>`,
+});
+
+console.log(await result.stdoutText);
+
+// Database file persists in the virtual file system
+const dbExists = await php.fileExists('/data/app.db');
+console.log('\nDatabase persisted:', dbExists);
+

Demo 3: Processing uploaded files (ZIP archives)

+

Process ZIP files using PHP's Libzip extension:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// Create sample files
+php.mkdir('/uploads');
+await php.writeFile('/uploads/readme.txt', 'This is a sample text file');
+await php.writeFile('/uploads/data.json', JSON.stringify({ name: 'Test', version: '1.0' }));
+
+// Create, process, and extract ZIP archive
+const result = await php.runStream({
+	code: `<?php
+// Create ZIP archive
+$zip = new ZipArchive();
+$zip->open('/uploads/archive.zip', ZipArchive::CREATE);
+$zip->addFromString('readme.txt', file_get_contents('/uploads/readme.txt'));
+$zip->addFromString('data.json', file_get_contents('/uploads/data.json'));
+$zip->addFromString('info.txt', 'Created with PHP WASM');
+$zip->close();
+
+echo "ZIP archive created successfully\\n\\n";
+
+// Read and display archive contents
+$zip->open('/uploads/archive.zip');
+echo "Archive Contents:\\n";
+echo str_repeat('=', 50) . "\\n";
+
+for ($i = 0; $i < $zip->numFiles; $i++) {
+    $stat = $zip->statIndex($i);
+    $size = round($stat['size'] / 1024, 2);
+    echo sprintf("%-40s %10s KB\\n", $stat['name'], $size);
+}
+
+// Extract files
+$zip->extractTo('/uploads/extracted/');
+$zip->close();
+
+echo "\\nExtracted successfully to /uploads/extracted/\\n";
+
+// List extracted files
+echo "\\nExtracted Files:\\n";
+$files = new RecursiveIteratorIterator(
+    new RecursiveDirectoryIterator('/uploads/extracted/')
+);
+foreach ($files as $file) {
+    if ($file->isFile()) {
+        echo "  " . $file->getPathname() . "\\n";
+    }
+}
+?>`,
+});
+
+console.log(await result.stdoutText);
+

Demo 4: HTTP request/response pattern

+

Simulate web server behavior with request handlers:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// Set up a simple API endpoint
+await php.mkdir('/www/api');
+await php.writeFile(
+	'/www/api/users.php',
+	`<?php
+header('Content-Type: application/json');
+
+// Parse request
+$method = $_SERVER['REQUEST_METHOD'];
+$input = json_decode(file_get_contents('php://input'), true);
+
+// Simple routing
+switch ($method) {
+    case 'GET':
+        echo json_encode([
+            'users' => [
+                ['id' => 1, 'name' => 'John Doe'],
+                ['id' => 2, 'name' => 'Jane Smith']
+            ]
+        ]);
+        break;
+        
+    case 'POST':
+        $name = $input['name'] ?? 'Unknown';
+        echo json_encode([
+            'success' => true,
+            'user' => [
+                'id' => 3,
+                'name' => $name
+            ],
+            'message' => "User $name created"
+        ]);
+        break;
+        
+    default:
+        http_response_code(405);
+        echo json_encode(['error' => 'Method not allowed']);
+}
+?>`
+);
+
+// Make GET request
+const getResponse = await php.runStream({
+	scriptPath: '/www/api/users.php',
+	env: {
+		REQUEST_METHOD: 'GET',
+		SERVER_NAME: 'localhost',
+		SERVER_PORT: '80',
+	},
+});
+console.log('GET Response:', await getResponse.stdoutText);
+
+// Make POST request
+const postResponse = await php.runStream({
+	scriptPath: '/www/api/users.php',
+	env: {
+		REQUEST_METHOD: 'POST',
+		SERVER_NAME: 'localhost',
+		SERVER_PORT: '80',
+	},
+	body: JSON.stringify({ name: 'Alice Wonder' }),
+});
+console.log('\\nPOST Response:', await postResponse.stdoutText);
+

Demo 5: Template rendering engine

+

Use PHP as a templating engine for dynamic content:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// Create templates directory
+php.mkdir('/templates');
+
+// Create template
+await php.writeFile(
+	'/templates/email.php',
+	`<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        body { font-family: Arial, sans-serif; }
+        .header { background: #4CAF50; color: white; padding: 20px; }
+        .content { padding: 20px; }
+        .footer { background: #f1f1f1; padding: 10px; text-align: center; }
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1>Welcome, <?= htmlspecialchars($name) ?>!</h1>
+    </div>
+    <div class="content">
+        <p>Thank you for registering with <?= $appName ?>.</p>
+        <p>Your account details:</p>
+        <ul>
+            <li><strong>Email:</strong> <?= htmlspecialchars($email) ?></li>
+            <li><strong>Member Since:</strong> <?= date('F j, Y', $timestamp) ?></li>
+        </ul>
+        <p>You now have access to the following features:</p>
+        <ul>
+            <?php foreach ($features as $feature): ?>
+                <li><?= htmlspecialchars($feature) ?></li>
+            <?php endforeach; ?>
+        </ul>
+    </div>
+    <div class="footer">
+        <p>&copy; <?= date('Y') ?> <?= $appName ?>. All rights reserved.</p>
+    </div>
+</body>
+</html>`
+);
+
+// Render template with data
+const templateData = {
+	name: 'Priya Sharma',
+	email: 'priya@example.com',
+	appName: 'MyAwesomeApp',
+	timestamp: Math.floor(Date.now() / 1000),
+	features: ['Dashboard Access', 'API Integration', 'Premium Support', 'Custom Branding'],
+};
+
+// Pass data to template via environment variables or files
+await php.writeFile('/template-data.json', JSON.stringify(templateData));
+
+const result = await php.runStream({
+	code: `<?php
+    $data = json_decode(file_get_contents('/template-data.json'), true);
+    extract($data);
+    include '/templates/email.php';
+  ?>`,
+});
+
+console.log(await result.stdoutText);
+// Now you have rendered HTML that can be sent via email or saved
+

Demo 6: Real-time code execution and streaming

+

Process PHP output as it's generated:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+await php.writeFile(
+	'/stream-demo.php',
+	`<?php
+// Simulate long-running process
+echo "Starting process...\\n";
+flush();
+
+for ($i = 1; $i <= 10; $i++) {
+    echo "Processing item $i/10...\\n";
+    flush();
+    usleep(100000); // Sleep 100ms
+}
+
+echo "Process complete!\\n";
+?>`
+);
+
+// Run PHP script
+const streamedResponse = await php.runStream({
+	scriptPath: '/stream-demo.php',
+});
+
+streamedResponse.stdout.pipeTo(
+	new WritableStream({
+		write(chunk) {
+			console.log(chunk);
+		},
+	})
+);
+

Integration patterns

+

Pattern 1: Express.js middleware

+

Integrate PHP processing into an Express.js application:

+
import express from 'express';
+import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const app = express();
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+// PHP execution middleware
+app.use('/php', async (req, res, next) => {
+	try {
+		const phpScript = req.query.script || 'index.php';
+		const result = await php.runStream({
+			scriptPath: `/www/${phpScript}`,
+			env: {
+				REQUEST_METHOD: req.method,
+				QUERY_STRING: new URLSearchParams(
+					req.query as Record<string, string>
+				).toString(),
+				REQUEST_URI: req.url,
+			},
+		});
+
+		res.send(await result.stdoutText);
+	} catch (error) {
+		next(error);
+	}
+});
+
+app.listen(3000, () => {
+	console.log('Server with PHP support running on port 3000');
+});
+

Pattern 2: Automated testing

+

Create automated tests for PHP code:

+
import { describe, it, expect, beforeAll } from '@jest/globals';
+import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+describe('PHP Functions', () => {
+	let php: PHP;
+
+	beforeAll(async () => {
+		php = new PHP(await loadNodeRuntime('8.3'));
+	});
+
+	it('should calculate sum correctly', async () => {
+		const result = await php.run({
+			code: `<?php
+        function sum($a, $b) {
+          return $a + $b;
+        }
+        echo sum(5, 3);
+      ?>`,
+		});
+
+		expect(result.text).toBe('8');
+	});
+
+	it('should handle JSON operations', async () => {
+		const input = { name: 'Test', value: 42 };
+		const result = await php.run({
+			code: `<?php
+        $input = json_decode('${JSON.stringify(input)}', true);
+        $output = [
+          'received' => $input,
+          'doubled' => $input['value'] * 2
+        ];
+        echo json_encode($output);
+      ?>`,
+		});
+
+		const output = JSON.parse(result.text);
+		expect(output.doubled).toBe(84);
+	});
+});
+

Pattern 3: Build tool integration

+

Use in build scripts with other Node.js tools:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+import fs from 'fs/promises';
+
+async function generateDocumentation() {
+	const php = new PHP(await loadNodeRuntime('8.3'));
+
+	// Create output directory
+	php.mkdir('/output');
+
+	// Generate documentation
+	const result = await php.runStream({
+		code: `<?php
+echo "Generating documentation...\\n";
+
+$summary = "# Generated Documentation\\n\\n";
+$summary .= "Generated at: " . date('Y-m-d H:i:s') . "\\n\\n";
+
+file_put_contents('/output/summary.md', $summary);
+echo "Documentation generated successfully!\\n";
+?>`,
+	});
+
+	console.log(await result.stdoutText);
+
+	// Extract generated docs back to Node.js file system
+	await fs.mkdir('./docs', { recursive: true });
+	const summaryContent = await php.readFileAsText('/output/summary.md');
+	await fs.writeFile('./docs/summary.md', summaryContent);
+
+	console.log('Documentation saved to ./docs/summary.md');
+}
+
+generateDocumentation().catch(console.error);
+

Advanced features

+

Working with environment variables

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+const result = await php.runStream({
+	code: '<?php echo getenv("CUSTOM_VAR"); ?>',
+	env: {
+		CUSTOM_VAR: 'Hello from Node.js!',
+	},
+});
+
+console.log(await result.stdoutText);
+

Error handling

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+try {
+	const result = await php.runStream({
+		code: '<?php trigger_error("Test error", E_USER_ERROR); ?>',
+	});
+
+	const stdout = await result.stdoutText;
+	const stderr = await result.stderrText;
+
+	console.log('stdout:', stdout);
+	console.log('stderr:', stderr);
+
+	if (stderr) {
+		console.error('PHP produced errors:', stderr);
+	}
+} catch (error: any) {
+	console.error('JavaScript Error:', error.message);
+}
+

Performance considerations

+
  • Reuse PHP instances: Creating a new PHP instance is expensive. Reuse the same instance when possible.
  • Batch operations: Group multiple file operations together rather than running separate scripts.
  • Memory management: Large files may impact performance. Consider streaming for big datasets.
  • Caching: Cache compiled PHP scripts and frequently accessed data.
+

Original Playground docs source: https://playground.wordpress.net/developers/local-development/php-wasm-node

]]> + + 19 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Playground CLI]]> + https://playground.wordpress.net/developers-local-development-wp-playground-cli/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=20 + + Playground CLI +

@wp-playground/cli is a command-line tool that simplifies the WordPress development and testing flow. Playground CLI supports auto-mounting a directory with a plugin, theme, or WordPress installation. But if you need flexibility, the CLI supports mounting commands to personalize your local environment.

+

Key features:

+
  • Quick Setup: Set up a local WordPress environment in seconds.
  • Flexibility: Allows for configuration to adapt to different scenarios.
  • Simple Environment: No extra configuration, just a compatible Node version, and you are ready to use it.
+

The Playground CLI includes two main commands for running WordPress locally:

+
  • start (Simplified): Auto-detects your project type, persists sites between sessions, and opens a browser automatically.
  • server (Advanced): Provides full manual control over configuration. Best for custom setups, CI/CD pipelines, or when you need fine-grained control.
+

Requirements

+

The Playground CLI requires Node.js 20.18 or higher, which is the recommended Long-Term Support (LTS) version. You can download it from the Node.js website.

+

Quickstart

+

To run the Playground CLI, open a command line and use one of the following commands:

+

Using start (Simplified)

+

The start command is the easiest way to get started. It automatically detects your project type, persists your site, and opens the browser:

+
npx @wp-playground/cli@latest start
+

When run inside a plugin or theme directory, start automatically mounts your project:

+
cd my-plugin
+npx @wp-playground/cli@latest start
+

Key differences from server:

+
  • Auto-login is enabled by default
  • Opens browser automatically
  • Auto-mounts the project by default
+

Using server (Advanced)

+

The server command provides full control over configuration:

+
npx @wp-playground/cli@latest server
+

Playground CLI in Action

+

Automatic site persistence: By default, the start command keeps your WordPress site persistent across sessions. Your files and database are stored in ~/.wordpress-playground/sites/<path-hash>/, where <path-hash> is derived from your project directory. This means you can stop and restart the CLI without losing your work.

+

This is useful when:

+
  • You want a clean WordPress installation
  • Testing fresh installation scenarios
  • Your site data became corrupted or inconsistent
+

The --reset flag works only with start. For server, manually delete the persisted site directory at ~/.wordpress-playground/sites/<path-hash>/.

+

Choosing a WordPress and PHP Version

+

By default, the CLI loads the latest stable version of WordPress and PHP 8.3 due to its improved performance. To specify your preferred versions, you can use the flag --wp=<version> and --php=<version>:

+
npx @wp-playground/cli@latest server --wp=6.8 --php=8.3
+

Loading Blueprints

+

One way to take your Playground CLI development experience to the next level is to integrate with Blueprints. For those unfamiliar with this technology, it allows developers to configure the initial state for their WordPress Playground instances.

+

Using the --blueprint=<blueprint-address> flag, developers can run a Playground with a custom initial state. We’ll use the example below to do this.

+

(my-blueprint.json)

+
{
+  "landingPage": "/wp-admin/options-general.php?page=akismet-key-config",
+  "login": true,
+  "plugins": [
+    "hello-dolly",
+    "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
+  ]
+}
+

CLI command loading a blueprint:

+
npx @wp-playground/cli@latest server --blueprint=my-blueprint.json
+

Mounting folders manually

+

Some projects have a specific structure that requires a custom configuration; for example, your repository contains all the files in the /wp-content/ folder. So in this scenario, you can specify to the Playground CLI that it will mount your project from that folder using the --mount flag.

+
npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY
+

Mounting before WordPress installation

+

Consider mounting your WordPress project files before the WordPress installation begins. This approach is beneficial if you want to override the Playground boot process, as it can help connect Playground with WP-CLI. The --mount-before-install flag supports this process.

+
npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/
+

On Windows, the path format /host/path:/vfs/path can cause issues. To resolve this, use the flags --mount-dir and --mount-dir-before-install. These flags let you specify host and virtual file system paths in an alternative format: "/host/path" "/vfs/path".

+

Understanding Data Persistence and SQLite Location in server mode

+

By default, Playground CLI stores WordPress files and the SQLite database in temporary directories on your operating system:

+
<OS-TEMP-DIR>/playground-<random-id>/
+├── wordpress/          # WordPress installation
+├── internal/          # Playground runtime config
+└── tmp/              # Temporary PHP files
+

Finding Your Temp Directory:

+

The actual location depends on your OS (these are examples or common possibilities):

+
  • macOS/Linux: May be under /tmp/ or /private/var/folders/ (varies by system)
  • Windows: C:\Users\<username>\AppData\Local\Temp\
+

To see the exact temp directory path being used, run the CLI with the --verbosity=debug flag:

+
npx @wp-playground/cli@latest server --verbosity=debug
+

This will output something like:

+
Native temp dir for VFS root:
+/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC
+Mount before WP install: /home ->
+/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/home
+Mount before WP install: /tmp ->
+/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/tmp
+Mount before WP install: /wordpress ->
+/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/wordpress
+

Where is the SQLite Database Stored?

+

The database location depends on what you mount:

+
  • Auto-mounting wp-content or full WordPress:
  • Database: <your-local-project>/wp-content/database/.ht.sqlite
  • ✅ Persisted locally in your project folder
+
  • Auto-mounting plugin/theme only:
  • Database: <OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/.ht.sqlite
  • ⚠️ Lost when server stops (temp directories are cleaned up)
+
  • Custom mounts: Database location follows your mount configuration
+

Automatic Cleanup: Playground CLI automatically removes temp directories that are:

+
  • Older than 2 days
  • No longer associated with a running process
+

Recommendation: To persist both your code and database when developing plugins or themes, mount the entire wp-content directory instead of just the plugin/theme folder.

+

Example: Mounting wp-content for persistence

+
# Mount your entire wp-content directory
+cd my-wordpress-project
+npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content
+

Data Persistence in start mode

+

Running in start mode, Playground CLI automatically persists your WordPress site in a dedicated directory:

+
~/.wordpress-playground/sites/<path-hash>/
+├── wordpress/          # WordPress installation
+├── internal/          # Playground runtime config
+└── tmp/              # Temporary PHP files
+

The <path-hash> is derived from your project directory path. This ensures isolation between different projects while persisting changes automatically.

+

Persistence behavior

+
  • Default (no explicit mount): WordPress files and database persist in ~/.wordpress-playground/sites/<path-hash>/. Changes survive between CLI restarts.
  • Explicit /wordpress mount: If you provide a mount path for /wordpress, automatic persistence is skipped. Your mount configuration takes precedence.
+

The database location depends on your configuration:

+
  • Default (automatic persistence):
  • Database: ~/.wordpress-playground/sites/<path-hash>/wordpress/wp-content/database/.ht.sqlite
  • Persisted automatically between sessions
+

Resetting a persisted site

+

To start fresh, use the --reset flag with the start command:

+
npx @wp-playground/cli@latest start --reset
+

Command and Arguments

+

Playground CLI is simple, configurable, and unopinionated. You can set it up according to your unique WordPress setup. With the Playground CLI, you can use the following top-level commands:

+
  • start: (Simplified) Starts a local WordPress server with automatic project detection, site persistence, and browser opening.
  • server: (Advanced) Starts a local WordPress server with full manual control over configuration.
  • run-blueprint: Executes a Blueprint file without starting a web server.
  • build-snapshot: Builds a ZIP snapshot of a WordPress site based on a Blueprint.
+

The start command has a dedicated argument:

+
  • --reset: Delete the stored site and start fresh. Defaults to false.
+

The server command supports the following optional arguments:

+
  • --port=<port>: The port number for the server to listen on. Defaults to 9400.
  • --version: Show version number.
  • --outfile: When building, write to this output file.
  • --site-url=<url>: Site URL to use for WordPress. Defaults to http://127.0.0.1:{port}.
  • --wp=<version>: The version of WordPress to use. Defaults to the latest.
  • --php=<version>: PHP version to use. Choices: 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.4. Defaults to 8.5.
  • --auto-mount[=<path>]: Automatically mount a directory. If no path is provided, mounts the current working directory. You can mount a WordPress directory, a plugin directory, a theme directory, a wp-content directory, or any directory containing PHP and HTML files.
  • --mount=<mapping>: Manually mount a directory (can be used multiple times). Format: "/host/path:/vfs/path".
  • --mount-before-install: Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: "/host/path:/vfs/path".
  • --mount-dir: Mount a directory to the PHP runtime (can be used multiple times). Format: "/host/path" "/vfs/path".
  • --mount-dir-before-install: Mount a directory before WordPress installation (can be used multiple times). Format: "/host/path" "/vfs/path"
  • --blueprint=<path>: The path to a JSON Blueprint file to execute.
  • --blueprint-may-read-adjacent-files: Consent flag: Allow "bundled" resources in a local blueprint to read files in the same directory as the blueprint file.
  • --login: Automatically log the user in as an administrator.
  • --wordpress-install-mode <mode>: Control how Playground prepares WordPress before booting. Defaults to download-and-install. Other options: install-from-existing-files (install using files you've mounted), install-from-existing-files-if-needed (skip setup when an existing site is detected), and do-not-attempt-installing (never download or install WordPress).
  • --skip-sqlite-setup: Do not set up the SQLite database integration.
  • --verbosity=<level>: Output logs and progress messages. Choices: quiet, normal, debug. Defaults to normal.
  • --debug: Print the PHP error log if an error occurs during boot.
  • --follow-symlinks: Allow Playground to follow symlinks by automatically mounting symlinked directories and files encountered in mounted directories.
  • --internal-cookie-store: Enable internal cookie handling. When enabled, Playground will manage cookies internally using an HttpCookieStore that persists cookies across requests. When disabled, cookies are handled externally (e.g., by a browser in Node.js environments). Defaults to false.
  • --phpmyadmin[=<path>]: Install phpMyAdmin for database management. The phpMyAdmin URL will be printed after boot. Optionally specify a custom URL path (default: /phpmyadmin).
  • --xdebug: Enable Xdebug. Defaults to false.
  • --experimental-devtools: Enable experimental browser development tools. Defaults to false.
  • --experimental-unsafe-ide-integration=<ide>: Set up the Xdebug integration on VS Code (vscode) and PhpStorm (phpstorm).
  • --workers=<n|auto>: Number of request-handling worker threads. Pass a positive integer, or auto to use one worker per CPU core (minus one). Defaults to min(6, cpus-1). Useful for multi-client workloads (e.g. parallel e2e suites) that need more than 6 in-flight requests.
  • --experimental-multi-worker=<number>: Deprecated. Use --workers=<n|auto> instead. The value of this flag is ignored.
+

Caution

+

With the flag --follow-symlinks, the following symlinks will expose files outside mounted directories to Playground and could be a security risk.

+

Need some help with the CLI?

+

With the Playground CLI, you can use the --help flag to get the full list of available commands and arguments.

+
npx @wp-playground/cli@latest --help
+

Programmatic usage

+

The Playground CLI can also be controlled programmatically from JavaScript/TypeScript using the runCLI function. See the Programmatic Usage guide for details on automation and testing.

+

Original Playground docs source: https://playground.wordpress.net/developers/local-development/wp-playground-cli

]]> + + 20 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Local Development]]> + https://playground.wordpress.net/developers-local-development/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=21 + + Local WordPress Development with Playground +

Playground offers various development environments to streamline setting up and managing WordPress sites.

+

For a quick start, use a public Playground web instance at https://playground.wordpress.net/. Alternatively, you can host your own WordPress Playground.

+

Playground also provides tools for local WordPress development, prioritizing ease of installation and usability:

+
  • @wp-playground/cli: A command-line tool to quickly launch a WordPress site from your terminal.
  • Visual Studio Code Extension: Integrates WordPress development directly into VS Code for a seamless experience within the popular editor.
+

For those needing more control, Playground offers tools for Node.js:

+ +

Original Playground docs source: https://playground.wordpress.net/developers/local-development

]]> + + 21 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[APIs overview]]> + https://playground.wordpress.net/developers-apis/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=22 + + WordPress Playground APIs overview +

WordPress Playground exposes a few APIs that you can use to interact with the Playground:

+

Query API

+

Basic operations can be done by adjusting the URL, for example here's how you can preinstall a coblocks plugin:

+

https://playground.wordpress.net/?plugin=coblocks

+

Or a theme:

+

https://playground.wordpress.net/?theme=pendant

+

This is called Query API and you can learn more about it here. Once you have a URL that you like, you can embed it in your website using an iframe:

+
<iframe style="width: 800px; height: 500px;" src="https://playground.wordpress.net/?plugin=coblocks"></iframe>
+

Check the Query API section for more info.

+

Blueprints

+

If you need more control over your Playground, you can use JSON Blueprints. For example, here's how to create a post and install a plugin:

+
<BlueprintExample
+display={`{
+  "steps": [
+    {
+      "step": "login"
+    },
+    {
+      "step": "installPlugin",
+      "pluginData": {
+        "resource": "wordpress.org/plugins",
+        "slug": "friends"
+      }
+    },
+    {
+      "step": "runPHP",
+      "code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Post title', 'post_content' => 'Post content', 'post_status' => 'publish', 'post_author' => 1)); ?>"
+    }
+  ]
+}` }
+blueprint={{
+		"steps": [
+            {
+                "step": "login"
+            },
+            {
+            step: 'installPlugin',
+                pluginData: {
+                    resource: 'wordpress.org/plugins',
+                    slug: 'friends',
+                },
+            },
+			{
+				"step": "runPHP",
+				"code": `<?php
+require_once '/wordpress/wp-load.php';
+wp_insert_post(array(
+'post_title' => 'Post title',
+'post_content' => 'Post content',
+'post_status' => 'publish',
+'post_author' => 1
+));
+`
+}
+]
+}} />
+

Blueprints play a significant role in WordPress Playground, so they have their own dedicated documentation hub. Learn more about JSON Blueprints at the Blueprints Docs Hub.

+

JavaScript API

+

The @wp-playground/client package provides a JavaScript API you can use to fully control your Playground instance. Here's a simple example of what you can do:

+
<iframe id="wp" style="width: 100%; height: 300px; border: 1px solid #000;"></iframe>
+<script type="module">
+	// Use unpkg for convenience
+	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: `https://playground.wordpress.net/remote.html`,
+	});
+	// Let's wait until Playground is fully loaded
+	await client.isReady();
+</script>
+

Check the JavaScript API section for more info.

+

Playground APIs Concepts

+

WordPress Playground in the browser is all about links and iframes. Regardless of which API you choose, you will use it in one of the following ways:

+

Link to the Playground site

+

You can customize WordPress Playground by modifying the https://playground.wordpress.net/ link. You can, for example, create a post, request a specific plugin, or run any PHP code.

+

To prepare such a link, use either the Query API (easy) or the JSON Blueprints API (medium).

+

Once it's ready, simply post it on your site. It makes a great "Try it yourself" button in a tutorial, for example.

+

Embed in an <iframe>

+

WordPress Playground can be embedded in your app using an <iframe>:

+
<iframe src="https://playground.wordpress.net/"></iframe>
+

To customize that Playground instance, you can:

+ +

The JavaScript API gives you the most control, but it is also the least convenient option as it requires loading the Playground Client library.

+

Caution: Careful with the demo site

+

The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.

+

If you need certain availability, you should host your own WordPress Playground.

+

Browser APIs

+

The following Playground APIs are available in the browser:

+
  • Query API enable basic operations using only query parameters
  • Blueprints API give you a great degree of control with a simple JSON file
  • JavaScript API give you full control via a JavaScript client from an npm package
+

In Node.js

+

The following Playground APIs are available in Node.js:

+ +

These APIs are very similar to their web counterparts, but, unsurprisingly, they are not based or links or iframes.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/

]]> + + 22 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[JavaScript API]]> + https://playground.wordpress.net/developers-apis-javascript-api/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=23 + + JavaScript API +

WordPress Playground comes with a JavaScript API client that grants you full control over your WordPress.

+

API here doesn't mean "REST API"

+

WordPress Playground is a browser-based application. The term API here refers to a set of functions you can call inside JavaScript. This is not a network-based REST API.

+

Quick start

+

To use the JavaScript API, you'll need:

+
  • An <iframe> element
  • The @wp-playground/client package (from npm or a CDN)
+

Here's the shortest example of how to use the JavaScript API in a HTML page:

+
<iframe id="wp" style="width: 100%; height: 300px; border: 1px solid #000;"></iframe>
+<script type="module">
+	// Use unpkg for convenience
+	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: `https://playground.wordpress.net/remote.html`,
+	});
+	// Let's wait until Playground is fully loaded
+	await client.isReady();
+</script>
+

/remote.html is a special URL

+

/remote.html is a special URL that loads the Playground API endpoint instead of the demo app with the browser UI. Read more about the difference between / and /remote.html and on this page.

+

Controlling the website

+

Now that you have a client object, you can use it to control the website inside the iframe. There are three ways to do that:

+ +

Debugging and testing

+

For quick testing and debugging, the JavaScript API client is exposed as window.playground by both index.html and remote.html.

+
> await playground.listFiles("/")
+(6) ['tmp', 'home', 'dev', 'proc', 'internal', 'wordpress']
+

Note that in index.html, playground is a Proxy object and you won't get any autocompletion from the browser. In remote.html, however, playground is a class instance and you will benefit from browser's autocompletion.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api

]]> + + 23 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[remote.html vs index.html]]> + https://playground.wordpress.net/developers-apis-javascript-api-html-vs-remote-html/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=24 + + remote.html vs index.html +

playground.wordpress.net exposes two distinct APIs through two separate HTML files: remote.html and index.html. Here's an overview of their functions and differences:

+
  • index.html uses WordPress Playground API client to control the "endpoint" that is remote.html.
  • The Query API is exclusively provided by index.html, independent of the WordPress Playground JavaScript API.
  • The JavaScript API is exclusively provided by remote.html. Only that file can be used as an "endpoint" for the PlaygroundClient class.
+

Here's a bit more about each of these files:

+

Remote.html

+

remote.html runs and renders WordPress and also exposes an API for developers to control it. Importantly, remote.html does not render any UI elements, such as browser UI or version switchers. It's just WordPress. The primary functions of remote.html are:

+
  • Loading the suitable version of php.wasm, the WebAssembly build of PHP.
  • Loading the correct version of WordPress for user interaction.
  • Initiating PHP in a WebWorker and registering a ServiceWorker for HTTP requests.
  • Listening to the message event from the parent window and executing the appropriate code command.
+

That last part is how the public API works. The parent window (index.html) sends a message to the iframe (remote.html) with a command and arguments, and the iframe then executes that command and sends the result back with another message.

+

Sending messages is cumbersome, so the PlaygroundClient class provides an object-oriented API that handles the messages internally.

+

For quick testing and debugging, remote.html also exposes the JavaScript API client as window.playground. You can use it from your devtools as follows:

+
> await playground.listFiles("/")
+(6) ['tmp', 'home', 'dev', 'proc', 'internal', 'wordpress']
+

playground is a class instance in this context, and you will benefit from browser's autocompletion.

+

Index.html

+

index.html is an independent app built around remote.html using the WordPress Playground API client.

+

It renders the browser UI, version selectors, and renders WordPress by embedding remote.html via an iframe. UI features, such as an address bar or a version selector, are implemented by communicating with remote.html using PlaygroundClient.

+

index.html monitors the query parameters it receives and triggers the appropriate PlaygroundClient methods. For instance, ?plugin=coblocks triggers installPluginsFromDirectory( client, ['coblocks'] ). This mechanism forms the basis of the Query API.

+

For quick testing and debugging, index.html also exposes the JavaScript API client as window.playground. You can use it from your devtools as follows:

+
> await playground.listFiles("/")
+(6) ['tmp', 'home', 'dev', 'proc', 'internal', 'wordpress']
+

Note that playground is a Proxy object in this context and you won't get any autocompletion from the browser.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api/-html-vs-remote-html

]]> + + 24 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Playground API Client]]> + https://playground.wordpress.net/developers-apis-javascript-api-playground-api-client/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=25 + + Playground API Client +

The PlaygroundClient object implements the UniversalPHP interface. All the methods from that interface are also available in Node.js and same-process PHP instances (Playground runs PHP in a web worker).

+

Broadly speaking, you can use the client to perform three types of operations:

+
  • Running PHP code
  • Customizing PHP.ini
  • Managing files and directories
+

Running PHP code

+

The two methods you can use to run PHP code are:

+
  • run() - runs PHP code and returns the output
  • request() - makes an HTTP request to the website
+

In Node.js, you can also use the cli() method to run PHP in a CLI mode.

+

The run() method

+

The request() method

+

Customizing PHP.ini

+

The API client also allows you to change the php.ini file:

+
await setPhpIniEntries(client, {
+	display_errors: 'On',
+	error_reporting: 'E_ALL',
+});
+

Managing files and directories

+

The client object provides you with a low-level API for managing files and directories in the PHP filesystem:

+
await client.mkdirTree('/wordpress/test');
+// Create a new PHP file
+await client.writeFile(
+	'/wordpress/test/index.php',
+	`<?php
+     echo "Hello, world!<br/>";
+     // List all the files in current directory
+     print_r(glob(__DIR__ . '/*'));
+  `
+);
+// Create files named 1, 2, and 3
+await client.writeFile('/wordpress/test/1', '');
+await client.writeFile('/wordpress/test/2', '');
+await client.writeFile('/wordpress/test/3', '');
+// Remove the file named 1
+await client.unlink('/wordpress/test/1');
+// Navigate to our PHP file
+await client.goTo('/test/index.php');
+

For a complete list of these methods, refer to the PlaygroundClient interface.

+

Sending messages to JavaScript

+

You can pass messages from PHP to JavaScript using the post_message_to_js() function. It accepts one argument:

+
  • $data (string) – Data to pass to JavaScript.
+

For example, here's how you would send a message with a JSON-encoded post ID and title:

+
import { PHP } from '@php-wasm/universal';
+import { loadNodeRuntime } from '@php-wasm/node';
+
+const php = new PHP(await loadNodeRuntime('8.3'));
+
+php.onMessage(
+	// The data is always passed as a string
+	function (data: string) {
+		// Let's decode and log the data:
+		console.log(JSON.parse(data));
+	}
+);
+
+// Now that we have a listener in place, let's
+// dispatch a message:
+await php.runStream({
+	code: `<?php
+        post_message_to_js(
+            json_encode([
+                'post_id' => '15',
+                'post_title' => 'This is a blog post!'
+            ])
+        );
+    `,
+});
+
+// You will see the following output in the console:
+// { post_id: '15', post_title: 'This is a blog post!' }
+

The cli() method

+

In Node.js, you also have access to the cli() method that runs PHP in a CLI mode:

+
// Run PHP in a CLI mode
+client.cli(['-r', 'echo "Hello, world!";']);
+// Outputs "Hello, world!"
+

Once cli() method finishes running, the PHP instance is no longer usable and should be discarded. This is because PHP internally cleans up all the resources and calls exit().

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api/playground-api-client

]]> + + 25 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Blueprints JSON and the API Client]]> + https://playground.wordpress.net/developers-apis-javascript-api-blueprint-json-in-api-client/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=26 + + Blueprints JSON and the API Client +

The Playground API client can be initialized with a JSON Blueprint. This is a convenient way of preconfiguring it in any way you like without worrying about progress bars and fetching remote files:

+
import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';
+
+const client = await startPlaygroundWeb({
+	iframe: document.getElementById('wp'),
+	remoteUrl: `https://playground.wordpress.net/remote.html`,
+	blueprint: {
+		preferredVersions: {
+			wp: '6.3',
+			php: '8.3',
+		},
+		steps: [
+			{ step: 'login' },
+			{
+				step: 'installPlugin',
+				pluginData: {
+					resource: 'wordpress.org/plugins',
+					slug: 'gutenberg',
+				},
+			},
+		],
+	},
+});
+await client.isReady();
+

Running a JSON Blueprint is only possible during the initialization of the API client.

+

If this is sufficient for your needs, read more about JSON Blueprints.

+

If you need to work with an already initialized client, you should look into Blueprint functions.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api/blueprint-json-in-api-client

]]> + + 26 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Blueprints Functions and the API Client]]> + https://playground.wordpress.net/developers-apis-javascript-api-blueprint-functions-in-api-client/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=27 + + Blueprints Functions and the API Client +

Every Blueprint step you can declare in the JSON object also provides a handler function that can be used directly.

+

For example:

+
import { startPlaygroundWeb, login, installPlugin } from 'https://playground.wordpress.net/client/index.js';
+
+const client = await startPlaygroundWeb({
+	iframe: document.getElementById('wp'),
+	remoteUrl: `https://playground.wordpress.net/remote.html`,
+});
+await client.isReady();
+
+await login(client, {
+	username: 'admin',
+	password: 'password',
+});
+
+await installPlugin(client, {
+	// Resources can only be used with JSON Blueprints.
+	// If you use functions, you must provide the resolved
+	// file.
+	pluginData: await fetch(pluginUrl),
+});
+

For more information and live examples visit the Blueprints Steps page.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api/blueprint-functions-in-api-client

]]> + + 27 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Mount data]]> + https://playground.wordpress.net/developers-apis-javascript-api-mount-data/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=28 + + Mount data +

Mount a directory from the browser

+

You can mount a directory from the browser to Playground using the window.showDirectoryPicker API. Check the Browser compatibility before using this API.

+
window.showDirectoryPicker().then(function (directoryHandle) {
+	window.parent.postMessage({
+		type: 'mount-directory-handle',
+		directoryHandle,
+		mountpoint: '/wordpress/wp-content/uploads/markdown/',
+	});
+});
+

Mount Browser's OPFS Storage

+

You can mount OPFS storage available within the browser as well. Under the hood, we sync the memory filesystem to OPFS at the end of every PHP request served. It's advisable to delay mounting of OPFS after boot as shown below, so that WordPress installation doesn't trigger a sync of over 3000 files slowing down the boot process.

+
const hasWordPressSiteInOPFS = false; // roll your logic to track this
+const blueprint = {
+	preferredVersions: {
+		php: '8.4',
+		wp: 'latest',
+	},
+	features: {
+		networking: true,
+	},
+	login: true,
+	steps: [], // add steps
+};
+
+try {
+	const mountDescriptor: MountDescriptor = {
+		device: {
+			type: 'opfs',
+			path: `my-unique-prefix/my-site`,
+		},
+		mountpoint: '/wordpress',
+		initialSyncDirection: hasWordPressSiteInOPFS ? 'opfs-to-memfs' : 'memfs-to-opfs',
+	};
+
+	const client = await startPlaygroundWeb({
+		iframe: document.getElementById('wp'),
+		remoteUrl: 'https://playground.wordpress.net/remote.html',
+		blueprint: blueprint,
+		shouldInstallWordPress: !hasWordPressSiteInOPFS,
+		mounts: hasWordPressSiteInOPFS ? [mountDescriptor] : [],
+	});
+
+	if (!hasWordPressSiteInOPFS) {
+		await client.mountOpfs(mountDescriptor);
+	}
+
+	await client.isReady();
+	return client;
+} catch (error) {
+	// handle error here
+}
+

For persistence guarantees, check Storage quotes and eviction criterias.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/javascript-api/mount-data

]]> + + 28 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Query API]]> + https://playground.wordpress.net/developers-apis-query-api/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=29 + + Query API +

WordPress Playground exposes a simple API that you can use to configure the Playground in the browser.

+

It works by passing configuration options as query parameters to the Playground URL. For example, to install the pendant theme, you would use the following URL:

+
https://playground.wordpress.net/?theme=pendant
+

You can go ahead and try it out. The Playground will automatically install the theme and log you in as an admin. You may even embed this URL in your website using an <iframe> tag:

+
<iframe src="https://playground.wordpress.net/?theme=pendant"></iframe>
+

Available options

+
| Option             | Default Value         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `php`              | `8.5`                 | Loads the specified PHP version. Accepts `7.4`, `8.0`, `8.1`, `8.2`, `8.3`, `8.4`, `8.5` or `latest`.                                                                                                                                                                                                                                                                                                                                                                       |
+| `wp`               | `latest`              | Loads the specified WordPress version. Accepts the last three major WordPress versions. As of June 1, 2024, that's `6.3`, `6.4`, or `6.5`. You can also use the generic values `latest`, `nightly`, or `beta`.                                                                                                                                                                                                                                                              |
+| `blueprint-url`    |                       | The URL of the Blueprint that will be used to configure this Playground instance.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `networking`       | `yes`                 | Enables or disables the networking support for Playground. Accepts `yes` or `no`.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `plugin`           |                       | Installs the specified plugin. Use the plugin name from the WordPress Plugins Directory URL. For example, if the URL is `https://wordpress.org/plugins/wp-lazy-loading/`, the plugin name would be `wp-lazy-loading`. You can pre-install multiple plugins by saying `plugin=coblocks&plugin=wp-lazy-loading&…`. Installing a plugin automatically logs the user in as an admin. More than one plugin could be installed, just repeating the `plugin` attribute on the URL. |
+| `theme`            |                       | Installs the specified theme. Use the theme name from the WordPress Themes Directory URL. For example, if the URL is `https://wordpress.org/themes/disco/`, the theme name would be `disco`. Installing a theme automatically logs the user in as an admin. Multiples themes could be installed just repeating the `theme` attribute on the URL.                                                                                                                            |
+| `url`              | `/wp-admin/`          | Load the specified initial WordPress page in this Playground instance.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `mode`             | `browser-full-screen` | Determines how the WordPress instance is displayed. Either wrapped in a browser UI or full width as a seamless experience. Accepts `browser-full-screen`, or `seamless`.                                                                                                                                                                                                                                                                                                    |
+| `lazy`             |                       | Defer loading the Playground assets until someone clicks on the "Run" button. Does not accept any values. If `lazy` is added as a URL parameter, loading will be deferred.                                                                                                                                                                                                                                                                                                  |
+| `login`            | `yes`                 | Log the user in as an admin. Accepts `yes` or `no`.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `multisite`        | `no`                  | Enables the WordPress multisite mode. Accepts `yes` or `no`.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `import-site`      |                       | Imports site files and database from a ZIP file specified by a URL.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `import-wxr`       |                       | Imports site content from a WXR file specified by a URL. It uses the WordPress Importer plugin, so the default admin user must be logged in.                                                                                                                                                                                                                                                                                                                                |
+| `site-slug`        |                       | Selects which site to load from browser storage. If the specified site does not exist, the user will be prompted to save a new site with the specified slug.                                                                                                                                                                                                                                                                                                                |
+| `language`         | `en_US`               | Sets the locale for the WordPress instance. This must be used in combination with `networking=yes` otherwise WordPress won't be able to download translations.                                                                                                                                                                                                                                                                                                              |
+| `core-pr`          |                       | Installs a specific https://github.com/WordPress/wordpress-develop core PR. Accepts the PR number. For example, `core-pr=6883`.                                                                                                                                                                                                                                                                                                                                             |
+| `gutenberg-pr`     |                       | Installs a specific https://github.com/WordPress/gutenberg PR. Accepts the PR number. For example, `gutenberg-pr=65337`.                                                                                                                                                                                                                                                                                                                                                    |
+| `gutenberg-branch` |                       | Installs a specific branch from https://github.com/WordPress/gutenberg. Accepts the branch name. For example, `gutenberg-branch=trunk`.                                                                                                                                                                                                                                                                                                                                     |
+| `page-title`       |                       | Customizes the browser tab title. Useful for identifying different Playground instances when working with multiple tabs. The parameter is preserved when navigating between sites.                                                                                                                                                                                                                                                                                          |
+| `can-save`         |                       | Default functionality allows for saving Playgrounds to the user's computer or browser. If you would like to turn off the ability for users to save their Playground, add the `?can-save=no` parameter, and options to save will be removed from the UI.                                                                                                                                                                                                                     |
+| `mcp`              | `no`                  | Starts the MCP (Model Context Protocol) server bridge, allowing external MCP clients to connect to and control the Playground instance. Accepts `yes` or `no`.                                                                                                                                                                                                                                                                                                              |
+| `mcp-port`         | `7999`                | Sets the WebSocket port used by the MCP bridge to communicate with the MCP server. Must be used together with `mcp=yes`. For example, `mcp=yes&mcp-port=8080`.                                                                                                                                                                                                                                                                                                              |
+| `overlay`          |                       | Opens a UI overlay on page load. Currently supports `blueprints` to open the Blueprint Gallery directly. For example, `?overlay=blueprints`. The parameter is removed from the URL when the overlay is closed.                                                                                                                                                                                                                                                              |
+| `filebrowser`      |                       | Opens the Site Manager directly to the File Browser tab. Accepts an optional file path relative to the WordPress document root, and an optional `:<line>` suffix to place the editor cursor on a 1-based line.                                                                                                                                                                                                                                                              |
+

For example, the following code embeds a Playground with a preinstalled Gutenberg plugin and opens the post editor:

+
<iframe src="https://playground.wordpress.net/?plugin=gutenberg&url=/wp-admin/post-new.php&mode=seamless"> </iframe>
+

To open the File Browser tab, use:

+
https://playground.wordpress.net/?filebrowser
+

To open the File Browser tab with a specific file, use a path relative to the WordPress document root:

+
https://playground.wordpress.net/?filebrowser=wp-content/plugins/my-plugin/index.php
+

To place the cursor on a specific 1-based line number, append :<line> to the path:

+
https://playground.wordpress.net/?filebrowser=wp-content/plugins/my-plugin/index.php:20
+

CORS policy

+

To import files from a URL, such as a site zip package, they must be served with Access-Control-Allow-Origin header set. For reference, see: Cross-Origin Resource Sharing (CORS).

+

GitHub Export Options

+

The following additional query parameters may be used to pre-configure the GitHub export form:

+
  • gh-ensure-auth: If set to yes, Playground will display a modal to ensure the
+

user is authenticated with GitHub before proceeding.

+
  • ghexport-repo-url: The URL of the GitHub repository to export to.
  • ghexport-pr-action: The action to take when exporting (create or update).
  • ghexport-playground-root: The root directory in the Playground to export from.
  • ghexport-repo-root: The root directory in the repository to export to.
  • ghexport-content-type: The content type of the export (plugin, theme, wp-content, custom-paths).
  • ghexport-plugin: Plugin path. When the content type is plugin, pre-select the plugin to export.
  • ghexport-theme: Theme directory name. When the content type is theme, pre-select the theme to export.
  • ghexport-path: A path relative to ghexport-playground-root. Can be provided multiple times. When the
+

content type is custom-paths, it pre-populates the list of paths to export.

+
  • ghexport-commit-message: The commit message to use when exporting.
  • ghexport-allow-include-zip: Whether to offer an option to include a zip file in the GitHub
+

export (yes, no). Optional. Defaults to yes.

+

Original Playground docs source: https://playground.wordpress.net/developers/apis/query-api

]]> + + 29 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + + <![CDATA[Debugging with Xdebug in WordPress Playground]]> + https://playground.wordpress.net/developers-xdebug-introduction/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=30 + + Debugging with Xdebug in WordPress Playground +

Xdebug is a debugging extension for PHP that lets you set breakpoints, inspect variables, and step through your code. WordPress Playground includes Xdebug in its WebAssembly-compiled PHP, so you can debug WordPress code running directly in your browser or IDE.

+

Why Xdebug matters for PHP WASM

+

Debugging PHP code in WebAssembly is different from debugging traditional PHP. Without Xdebug, you're limited to var_dump() and error_log() statements. Xdebug gives you a proper debugger with breakpoints, variable inspection, and call stack navigation—the same tools you'd use when debugging PHP on a regular server.

+

XDebug on WordPress Playground

+

For a quick start, check the getting started with Xdebug guide

+

You'll learn to debug:

+
  • Form processing logic
  • Input validation
  • WordPress hooks and filters
+

Two debugging approaches

+

WordPress Playground supports two ways to debug with Xdebug:

+

Chrome DevTools: Debug directly in your browser without any IDE setup. Great for quick debugging sessions or when you want to see everything in one place.

+

IDE integration: Use VSCode or PhpStorm with full IDE features, including code navigation, project-wide search, and advanced breakpoint conditions. Better for complex debugging scenarios.

+

What you'll need

+
  • Node.js installed
  • Chrome or Chromium browser (for DevTools debugging)
  • Visual Studio Code or PhpStorm (for IDE debugging, optional)
  • Basic familiarity with WordPress plugin development
+

Next: Getting Started with Xdebug →

+

Original Playground docs source: https://playground.wordpress.net/developers/xdebug/introduction

]]> + + 30 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Getting Started with Xdebug]]> + https://playground.wordpress.net/developers-xdebug-getting-started/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=31 + + Getting Started with Xdebug +

This guide shows you how to enable Xdebug in WordPress Playground and start debugging your code.

+

PHP WASM CLI vs Playground CLI

+

First, Xdebug is present in two different CLIs:

+
  • @php-wasm/cli: Run standalone PHP scripts. Use this when debugging PHP code without needing a WordPress environment.
  • @wp-playground/cli: Run a full WordPress installation. Useful for debugging WordPress plugins, themes, or core functionality.
+

For this guide, we'll use @wp-playground/cli. If you're not familiar with the tool, we recommend reading the @wp-playground/cli guide, but the same process can also be applied to debugging PHP applications with @php-wasm/cli.

+

Quick start with npx

+

The fastest way to get started is using npx, which doesn't require installation:

+
npx @wp-playground/cli@latest server --xdebug
+

This starts WordPress on http://127.0.0.1:9400 with Xdebug enabled. Now you can connect a debugger.

+

Only one project can be debugged at a time.

+

Starting with IDE integration

+

Similar to the process with DevTools, let's use the same plugin code from before to debug with VS Code, and add the --experimental-unsafe-ide-integration=vscode flag. This flag will optimize the setup process for VS Code. If you're working with PhpStorm, add the --experimental-unsafe-ide-integration=phpstorm flag.

+

This flag is marked as unsafe because it edits the IDE config files to set Xdebug path mappings and web server details. CAUTION: If there are bugs, this feature may cause your IDE configuration files to break. Please consider backing up your IDE configs before using this feature.

+

To debug in VS Code, you'll need the following prerequisites:

+
  1. An extension to add PHP profiling support, for example, PHP Debug or another debugger extension to your preference.
  2. Have a .vscode/ folder.
  3. Enable breakpoints in your IDE. Some IDEs come with this feature disabled, so be aware of this detail.
+

If everything is ready, you run the command:

+
npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount
+

If you don't have a .vscode/launch.json file, the terminal will create a file similar to this:

+
{
+    "configurations": [
+        {
+            "name": "WP Playground CLI - Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/": "${workspaceFolder}/.playground-xdebug-root",
+                "/wordpress/wp-content/plugins/test-xdebug": "${workspaceFolder}/"
+            }
+        }
+    ]
+}
+

Now, you can go to your code, add the breakpoints, start the debugging session named by your IDE, and happy testing.

+

Xdebug in action on VS Code

+

Early Access: DevTools debugger

+

Playground CLI ships an unstable, highly exploratory workflow that enables debugging PHP programs using Chrome DevTools.

+

To try it, use the --experimental-devtools flag:

+
npx @wp-playground/cli@latest server --xdebug --experimental-devtools
+

The terminal will display a URL to connect to Chrome DevTools:

+
Starting a PHP server...
+Setting up WordPress latest
+Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.3.zip
+Fetching SQLite integration plugin...
+Booting WordPress...
+WordPress is running on http://127.0.0.1:9400 with 1 worker(s)
+Starting XDebug Bridge...
+Connect Chrome DevTools to CDP at:
+devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229
+
+Chrome connected! Initializing Xdebug receiver...
+XDebug receiver running on port 9003
+Running a PHP script with Xdebug enabled...
+

By clicking on the provided URL, for example, devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229, you can access DevTools connected to your application, with the ability to inspect all files of a WordPress instance.

+

Chrome Devtools integrated with Xdebug

+

For a more practical example, let's debug a plugin that has the following code:

+
<?php
+/**
+ * Plugin Name: Simple Admin Message
+ * Description: Displays a simple message in the WordPress admin
+ * Version: 1.0
+ * Author: Playground Team
+ */
+
+// Prevent direct access
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+// Display admin notice
+function sam_display_admin_message() {
+    $message = 'Hello! This is a simple admin message.';
+    ?>
+    <div class="notice notice-info is-dismissible">
+        <p><?php _e($message, 'simple-admin-message'); ?></p>
+    </div>
+    <?php
+}
+add_action('admin_notices', 'sam_display_admin_message');
+

In the folder where the plugin is located, let's run the command in our terminal:

+
npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount
+

The Playground CLI(@wp-playground/cli) will automatically detect the plugin folder and mount it. Opening the project in your browser and DevTools, you'll be able to add breakpoints in your plugin's code and test it line by line.

+

Chrome Devtools integrated with Xdebug

+

This feature is in experimental mode. Until it's finished, we'll need your feedback. Please connect with us in the #playground Slack channel and share your thoughts.

+

Original Playground docs source: https://playground.wordpress.net/developers/xdebug/getting-started

]]> + + 31 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Architecture]]> + https://playground.wordpress.net/developers-architecture/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=32 + + Architecture overview +

WordPress Playground consists of the following high-level components:

+ +

Visit each section to learn more about the specific parts of the architecture.

+

Tooling

+

NX: building packages and projects

+

WordPress Playground uses NX, a build system designed for monorepos.

+

The dependencies between Playground packages and projects are too complex for a bundler like Webpack, and NX handles this complexity much better:

Dependency graph

+

To learn more, head over to the NX developer docs.

+

Lerna: publishing packages and projects

+

WordPress Playground includes several NPM packages, a VS Code extension, WordPress plugins, a web app, and other GitHub releases, all managed across two monorepos: the main wordpress-playground and Playground Tools.

+

We use Lerna to build, manage, and publish all JavaScript/TypeScript packages. Lerna handles everything simultaneously: it increments the version number, sets a new tag, and publishes the modified packages to npm.

+

The published packages share the same version number, so when updating a single package, Lerna bumps the version number of all dependent packages.

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture

]]> + + 32 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WebAssembly PHP]]> + https://playground.wordpress.net/developers-architecture-wasm-php-overview/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=33 + + WebAssembly PHP +

WordPress Playground build the PHP interpreter to WebAssembly using Emscripten and a dedicated pipeline.

+

Building C programs to WebAssembly

+

Building PHP to WebAssembly is very similar to building vanilla PHP. The wasm build required adjusting a function signature here, forcing a config variable there, and applying a few small patches, but there's relatively few adjustments involved.

+

Building PHP to WebAssembly

+

However, vanilla PHP builds aren't very useful in the browser. As a server software, PHP doesn't have a JavaScript API to pass the request body, upload files, or populate the php://stdin stream. WordPress Playground had to build one from scratch. The WebAssembly binary comes with a dedicated PHP API module written in C and a JavaScript PHP class that exposes methods like writeFile() or run().

+

Because every PHP version is just a static .wasm file, the PHP version switcher is actually pretty boring. It simply tells the browser to download, for example, php_7_3.wasm instead of, say, php_8_2.wasm.

+

Building different versions of PHP to WebAssembly

+

Networking support varies between platforms

+

When it comes to networking, WebAssembly programs are limited to calling JavaScript APIs. It is a safety feature, but also presents a challenge. How do you support low-level, synchronous networking code used by PHP with the high-level asynchronous APIs available in JavaScript?

+

In Node.js, the answer involves a WebSocket to TCP socket proxy, Asyncify, and patching deep PHP internals like php_select. It's complex, but there's a reward. The Node.js-targeted PHP build can request web APIs, install composer packages, and even connect to a MySQL server.

+

In the browser, networking is supported in two ways:

+
  • A fast transport for wp_safe_remote_get to translate them into fetch() calls.
  • A slower transport for all other network calls that parses the TLS transmission initiated by PHP and translates it to a fetch() call.
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/wasm-php-overview

]]> + + 33 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Compiling PHP]]> + https://playground.wordpress.net/developers-architecture-wasm-php-compiling/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=34 + + Compiling PHP +

The build pipeline lives in a Dockerfile. It was originally forked from seanmorris/php-wasm

+

In broad strokes, that Dockerfile:

+
  • Installs all the necessary linux packages (like build-essential)
  • Downloads PHP and the required libraries, e.g. sqlite3.
  • Applies a few patches.
  • Compiles everything using Emscripten, a drop-in replacement for the C compiler.
  • Compiles php_wasm.c – a convenient API for JavaScript.
  • Outputs a php.wasm file and one or more JavaScript loaders, depending on the configuration.
  • Transforms the Emscripten's default php.js output into an ESM module with additional features.
+

To find out more about each step, refer directly to the Dockerfile.

+

Building

+

To build all PHP versions, run nx recompile-php:all php-wasm-web (or php-wasm-node) in the repository root. You'll find the output files in packages/php-wasm/php-web/public. To build a specific version, run nx recompile-php:all php-wasm-node --PHP_VERSION=8.0 --WITH_JSPI=yes (and repeat with --WITH_JSPI=no).

+

PHP extensions

+

PHP is built with several extensions listed in the Dockerfile.

+

Some extensions, like zip, can be turned on or off during the build. Others, like sqlite3, are hardcoded.

+

If you need to turn off one of the hardcoded extensions, feel free to open an issue in this repo. Better yet, this project needs contributors. You are more than welcome to open a PR and author the change you need.

+

C API exposed to JavaScript

+

The C API exposed to JavaScript lives in the php_wasm.c file. The most important functions are:

+
  • void phpwasm_init() – It creates a new PHP context and must be called before running any PHP code.
  • int phpwasm_run(char *code) – Runs a PHP script and writes the output to /tmp/stdout and /tmp/stderr. Returns the exit code.
  • void phpwasm_refresh() – Destroy the current PHP context and starts a new one. Call it after running one PHP script and before running another.
+

Refer to the inline documentation in php_wasm.c to learn more.

+

Build configuration

+

The build is configurable via the Docker --build-arg feature. You can set them up through the build.js script, just run this command to get the usage message:

+
nx recompile-php php-wasm-web
+

Supported build options:

+
  • PHP_VERSION – The PHP version to build, default: 8.0.24. This value must point to an existing branch of the https://github.com/php/php-src.git repository when prefixed with PHP-. For example, 7.4.0 is valid because the branch PHP-7.4.0 exists, but just 7 is invalid because there's no branch PHP-7. The PHP versions that are known to work are 7.4.* and 8.0.*. Others likely work as well but they haven't been tried.
  • EMSCRIPTEN_ENVIRONMENT – web or node, default: web. The platform to build for. When building for web, two JavaScript loaders will be created: php-web.js and php-webworker.js. When building for Node.js, only one loader called php-node.js will be created.
  • WITH_LIBXML – yes or no, default: no. Whether to build with libxml2 and the dom, xml, and simplexml PHP extensions (DOMDocument, SimpleXML, ..).
  • WITH_LIBZIP – yes or no, default: yes. Whether to build with zlib, libzip, and the zip PHP extension (ZipArchive).
  • WITH_NODEFS – yes or no, default: no. Whether to include the Emscripten's NODEFS JavaScript library. It's useful for loading files and mounting directories from the local filesystem when running php.wasm from Node.js.
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/wasm-php-compiling

]]> + + 34 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[PHP.js JavaScript module]]> + https://playground.wordpress.net/developers-23-architecture-04-wasm-php-javascript-module/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=35 + + PHP.js JavaScript module +

The php.js file generated by the WebAssembly PHP build pipeline is not a vanilla Emscripten module. Instead, it's an ESM module that wraps the regular Emscripten output and adds some extra functionality.

+

Here's the API it exposes:

+
// php.wasm size in bytes:
+export const dependenciesTotalSize = 5644199;
+
+// php.wasm filename:
+export const dependencyFilename = 'php.wasm';
+
+// Run Emscripten's generated module:
+export default function (jsEnv, emscriptenModuleArgs) {}
+

The generated JavaScript module is not meant for direct use. Instead, it can be consumed through the PHP class:

+
// In Node.js:
+const php = new PHP(await loadNodeRuntime('8.0'));
+
+// On the web:
+const php = new PHP(await loadWebRuntime('8.0'));
+

Both of these classes extend the BasePHP class exposed by the @php-wasm/universal package and implement the UniversalPHP interface that standardizes the API across all PHP environments.

+

Loading the PHP runtime

+

The load() method handles the entire PHP initialization pipeline. In particular, it:

+
  • Instantiates the Emscripten PHP module
  • Wires it together with the data dependencies and loads them
  • Ensures is all happens in a correct order
  • Waits until the entire loading sequence is finished
+

Original Playground docs source: https://playground.wordpress.net/developers/23-architecture/04-wasm-php-javascript-module

]]> + + 35 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[PHP Filesystem]]> + https://playground.wordpress.net/developers-architecture-wasm-php-filesystem/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=36 + + PHP Filesystem +

The PHP module has its own filesystem separate from your computer's filesystem. It is provided by Emscripten's FS library and the default APIs is low-level and cumbersome to use. The PHP JavaScript class shipped with WordPress Playground wraps it with a more convenient higher-level API.

+

In general, WordPress Playground uses an in-memory virtual filesystem.

+

However, in Node.js, you can also mount a real directory from the host filesystem into the PHP filesystem.

+

Here's how to interact with the filesystem in WordPress Playground:

+
// Recursively create a /var/www directory
+php.mkdirTree('/var/www');
+
+console.log(php.fileExists('/var/www/file.txt'));
+// false
+
+php.writeFile('/var/www/file.txt', 'Hello from the filesystem!');
+
+console.log(php.fileExists('/var/www/file.txt'));
+// true
+
+console.log(php.readFile('/var/www/file.txt'));
+// "Hello from the filesystem!
+
+// Delete the file:
+php.unlink('/var/www/file.txt');
+

For more details consult the BasePHP class directly – it has some great documentation strings.

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/wasm-php-filesystem

]]> + + 36 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Asyncify and JSPI – Stack Switching in PHP WebAssembly]]> + https://playground.wordpress.net/developers-architecture-wasm-asyncify/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=37 + + Asyncify and JSPI: Stack Switching in PHP WebAssembly +

Asyncify lets synchronous C or C++ code interact with asynchronous JavaScript. Technically, it saves the entire C call stack before yielding control back to JavaScript, and then restores it when the asynchronous call is finished. This is called stack switching.

+

Networking support in the WebAssembly PHP build is implemented using Asyncify. When PHP makes a network request, it yields control back to JavaScript, which makes the request, and then resumes PHP when the response is ready. It works well enough that PHP build can request web APIs, install composer packages, and even connect to a MySQL server.

+

Asyncify crashes

+

Stack switching requires wrapping all C functions that may be found at a call stack at a time of making an asynchronous call. Blanket-wrapping of every single C function adds a significant overhead, which is why we maintain a list of specific function names:

+

https://github.com/WordPress/wordpress-playground/blob/15a660940ee9b4a332965ba2a987f6fda0c159b1/packages/php-wasm/compile/Dockerfile#L624-L632

+

Unfortunately, missing even a single item from that list results in a WebAssembly crash whenever that function is a part of the call stack when an asynchronous call is made. It looks like this:

+

A screenshot of an asyncify error in the terminal

+

Asyncify can auto-list all the required C functions when built without ASYNCIFY_ONLY, but that auto-detection is overeager and ends up listing about 70,000 C functions which increases the startup time to 4.5s. That's why we maintain the list manually.

+

If you are interested in more details, see GitHub issue 251.

+

Fixing Asyncify crashes

+

Pull Request 253 adds a fix-asyncify command that runs a specialized test suite and automatically adds any identified missing C functions to the ASYNCIFY_ONLY list.

+

If you run into a crash like the one above, you can fix it by:

+
  1. Identifying a PHP code path that triggers the crash – the stack trace in the terminal should help with that.
  2. Adding a test case that triggers a crash to packages/php-wasm/node/src/test/php-asyncify.spec.ts
  3. Running: npm run fix-asyncify
  4. Committing the test case, the updated Dockerfile, and the rebuilt PHP.wasm
+

JSPI: The Modern Alternative to Asyncify

+

The JavaScript Promise Integration (JSPI) API handles stack switching natively in V8, eliminating the need for Asyncify's function wrapping. WordPress Playground now ships JSPI builds alongside Asyncify builds for all PHP versions (7.4–8.5).

+

Current status:

+
  • The Playground CLI auto-detects JSPI support and enables it automatically — no manual flags needed
  • Node.js 23+ supports JSPI natively; Node.js 22 requires the --experimental-wasm-jspi flag (handled automatically by the CLI)
  • Node.js 24+ is expected to have JSPI unflagged
  • Browser support varies: JSPI is available in Chrome/Chromium-based browsers behind flags
+

Binary Size Optimization with MAIN_MODULE=2

+

Both Asyncify and JSPI builds are compiled with Emscripten's MAIN_MODULE=2 flag, which performs dead code elimination on exported symbols. Only symbols that dynamic extensions actually need are exported.

+

Impact:

+
  • Total binary size reduced by 122 MB (13.7%)
  • .wasm files reduced by 109 MB (16%)
  • JavaScript glue code reduced by 14.5 MB (63%)
+

This optimization applies across all PHP versions (7.4–8.5) for both Node.js and Web targets. The exported symbol list is centrally managed in the Dockerfile, with conditional exports for specific extensions (e.g., __c_longjmp for Xdebug, _wasm_recv for Memcached).

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/wasm-asyncify

]]> + + 37 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Running PHP apps in the browser with ServiceWorkers and Worker Threads]]> + https://playground.wordpress.net/developers-architecture-browser-concepts/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=38 + + Running PHP apps in the browser with ServiceWorkers and Worker Threads +

On a high level, WordPress Playground works in web browsers as follows:

+
  • The index.html file on playground.wordpress.net loads the remote.html file via an <iframe src="/remote.html">.
  • remote.html starts a Worker Thread and a ServiceWorker and sends back the download progress information.
  • The Worker Thread starts PHP and populates the filesystem with a WordPress patched to run on SQLite.
  • The ServiceWorker starts intercepting all HTTP requests and forwarding them to the Worker Thread.
  • remote.html creates an <iframe src="/index.php">, and the Service Worker forwards the index.php request to the Worker Thread where the WordPress homepage is rendered.
+

Visually, it looks like this:

+

Architecture overview

+

High-level ideas

+

The @php-wasm/web is built on top of the following ideas:

+
  • Browser tab orchestrates everything – The browser tab is the main program. Closing or reloading it means destroying the entire execution environment.
  • Iframe-based rendering – Every response produced by the PHP server must be rendered in an iframe to avoid reloading the browser tab when the user clicks on a link.
  • PHP Worker Thread – The PHP server is slow and must run in a web worker, otherwise handling requests freezes the website UI.
  • Service Worker routing – All HTTP requests originating in that iframe must be intercepted by a Service worker and passed on to the PHP worker thread for rendering.
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/browser-concepts

]]> + + 38 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Browser tab orchestrates the execution]]> + https://playground.wordpress.net/developers-architecture-browser-tab-orchestrates-execution/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=39 + + Browser tab orchestrates the execution +

The main index.html ties the entire application together. It starts all the concurrent processes and displays the PHP responses. The app only lives as long as the main index.html.

+

Keep this point in mind as you read through the rest of the docs. At this point it may seem obvious, by the lines may get blurry later on. This package runs code outside of the browser tab using Web Workers, Service Workers, and, in the future, Shared Workers. Some of these workers may keep running even after the browser tab with index.html is closed.

+

Boot sequence

+

Here's what a boot sequence for a minimal app looks like:

+

The boot sequence

+

The main app initiates the Iframe, the Service Worker, and the Worker Thread. Note how the main app doesn't use the PHP stack directly – it's all handled in the Worker Thread.

+

Here's what that boot sequence looks like in code:

+

/index.html:

+
<script src="/app.ts"></script>
+<iframe id="my-app"></iframe>
+

/app.ts:

+
import { consumeAPI, PHPClient, registerServiceWorker, spawnPHPWorkerThread } from '@php-wasm/web';
+
+const workerUrl = '/worker-thread.js';
+
+export async function startApp() {
+	const phpClient = consumeAPI<PlaygroundWorkerEndpoint>(
+		await spawnPHPWorkerThread(
+			workerUrl, // Valid Worker script URL
+			{
+				wpVersion: 'latest',
+				phpVersion: '8.3', // Startup options
+			}
+		)
+	);
+
+	// Await the two-way communication channel
+	await phpClient.isReady();
+
+	// Must point to a valid Service Worker script:
+	await registerServiceWorker(
+		phpClient,
+		'default', // PHP instance scope, keep reading to learn more.
+		'/sw.js', // Valid Service Worker script URL.
+		'1' // Service worker version, used for reloading the script.
+	);
+
+	// Create a few PHP files to browse:
+	await workerThread.writeFile('/index.php', '<a href="page.php">Go to page.php</a>');
+	await workerThread.writeFile('/page.php', '<?php echo "Hello from PHP!"; ?>');
+
+	// Navigate to index.php:
+	document.getElementById('my-app').src = playground.pathToInternalUrl('/index.php');
+}
+startApp();
+

Keep reading to learn how all these pieces fit together.

+

Data flow

+

Here's what happens whenever the iframe issues a same-domain request:

+

The data flow

+

A step-by-step breakdown:

+
  1. The request is intercepted by the Service Worker
  2. The Service Worker passes it to the Worker Thread
  3. The Worker Thread calls PHP.request to convert that request to a response
  4. The Worker Thread passes the response to the Service Worker
  5. The Service Worker provides the browser with a response
+

At this point, if the request was triggered by user clicking on a link, the browser will render PHPRequestHandler's response inside the iframe.

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/browser-tab-orchestrates-execution

]]> + + 39 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Iframe-based rendering]]> + https://playground.wordpress.net/developers-architecture-browser-iframe-rendering/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=40 + + Iframe-based rendering +

To avoid page reloads, all the PHPRequestHandler responses must be rendered in an iframe. Remember, the entire setup only lives as long as the main index.html. We want to avoid reloading the main app at all costs.

+

In our app example above, index.php renders the following HTML:

+
<a href="page.php">Go to page.php</a>
+

Imagine our index.html rendered it in a <div> instead of an <iframe>. As soon as you click on that link, the browser will try to navigate from index.html to page.php. However, index.html runs the entire PHP app, including the Worker Thread, the PHPRequestHandler, and the traffic control connecting them to the Service Worker. Navigating away from it would destroy the app.

+

Now, consider an iframe with the same link in it:

+
<iframe srcdoc='<a href="page.php">Go to page.php</a>'></iframe>
+

This time, click the link in the browser to load page.php inside the iframe. The top-level index.html, where the PHP application runs, remains unaffected. That's why iframes are crucial for the @php-wasm/web setup.

+

Crash reports

+

Playground doesn't collect crash reports automatically. Instead, it prompts users to submit a crash report when an instance fails to run in the browser.

+

The report includes a log, description, and a URL, and users can modify it before submitting it.

+

The Logger API handles it from there. This simple REST API validates the data and sends it to the Making WordPress #playground-logs Slack channel.

+

Iframes caveats

+
  • target="_top" isn't handled yet, so clicking links with target="_top" will reload the page you’re working on.
  • JavaScript popups originating in the iframe may not always display.
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/browser-iframe-rendering

]]> + + 40 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[PHP Worker Threads]]> + https://playground.wordpress.net/developers-architecture-browser-php-worker-threads/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=41 + + PHP Worker Threads +

PHP is always ran in a web worker to ensure the PHP runtime doesn't slow down the user interface of the main website.

+

Imagine the following code:

+
<button onclick="for(let i=0;i<100000000;i++>) {}">Freeze the page</button>
+<input type="text" />
+

As soon as you click that button the browser will freeze and you won't be able to type in the input. That's just how browsers work. Whether it's a for loop or a PHP server, running intensive tasks slows down the user interface.

+

Initiating web workers

+

Web workers are separate programs that can process heavy tasks outside of the main application. They must be initiated by the main JavaScript program living in the browser tab. Here's how:

+
const phpClient = consumeAPI<PHPClient>(
+	spawnPHPWorkerThread(
+		'/worker-thread.js' // Valid Worker script URL
+	)
+);
+await phpClient.isReady();
+await phpClient.run({ code: `<?php echo "Hello from the thread!";` });
+

Controlling web workers

+

Exchanging messages is the only way to control web workers. The main application has no access to functions or variables inside of a web worker. It can only send and receive messages using worker.postMessage and worker.onmessage = function(msg) { }.

+

This can be tedious, which is why Playground provides a convenient consumeAPI function that abstracts the message exchange and exposes specific functions from the web worker. This is why we can call phpClient.run in the example above.

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/browser-php-worker-threads

]]> + + 41 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Service Workers]]> + https://playground.wordpress.net/developers-architecture-browser-service-workers/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=42 + + Service Workers +

A Service Worker is used to handle the HTTP traffic using the in-browser PHPRequestHandler.

+

Imagine your PHP script renders the following page in the iframe viewport:

+
<html>
+	<head>
+		<title>John's Website</title>
+	</head>
+	<body>
+		<a href="/">Homepage</a>
+		<a href="/blog">Blog</a>
+		<a href="/contact">Contact</a>
+	</body>
+</html>
+

When the user clicks, say the Blog link, the browser would normally send a HTTP request to the remote server to fetch the /blog page and then display it instead of the current iframe contents. However, our app isn't running on the remote server. The browser would just display a 404 page.

+

Enter Service Workers – a tool to intercept the HTTP requests and handle them inside the browser:

+

Service worker data flow

+

Service Worker setup

+

The main application living in /index.html is responsible for registering the service worker.

+

Here's the minimal setup:

+

/app.js:

+
import { registerServiceWorker } from '@php-wasm/web';
+
+function main() {
+	await registerServiceWorker(
+		phpClient,
+		"default", // PHP instance scope
+		"/sw.js",  // Must point to a valid Service Worker implementation.
+		"1"        // Service worker version, used for reloading the script.
+	);
+
+}
+

You will also need a separate /service-worker.js file that actually intercepts and routes the HTTP requests. Here's what a minimal implementation looks like:

+

/service-worker.js:

+
import { initializeServiceWorker } from '@php-wasm/web';
+
+// Intercepts all HTTP traffic on the current domain and
+// passes it to the Worker Thread.
+initializeServiceWorker();
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/browser-service-workers

]]> + + 42 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Scopes]]> + https://playground.wordpress.net/developers-23-architecture-13-browser-scopes/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=43 + + Scopes +

Scopes keep your app working when you open it in two different browser tabs.

+

The Service Worker passes the intercepted HTTP requests to the PHPRequestHandler for rendering. Technically, it sends a message through a BroadcastChannel which then gets delivered to every browser tab where the application is open. This is undesirable, slow, and leads to unexpected behaviors.

+

Unfortunately, the Service Worker cannot directly communicate with the relevant Worker Thread – see PR #31 and issue #9 for more details.

+

Scopes enable each browser tab to:

+
  • Brand the outgoing HTTP requests with a unique tab id
  • Ignore any BroadcastChannel messages with a different id
+

Technically, a scope is a string included in the PHPRequestHandler.absoluteUrl. For example:

+
  • In an unscoped app, /index.php would be available at http://localhost:8778/wp-login.php
  • In an scoped app, /index.php would be available at http://localhost:8778/scope:96253/wp-login.php
+

The service worker is aware of this concept and will attach the /scope: found in the request URL to the related BroadcastChannel communication.

+

A worker thread initiated with a scoped absoluteUrl is said to be scoped:

+
import {
+	PHP,
+	setURLScope,
+	exposeAPI,
+	parseWorkerStartupOptions,
+} from '@php-wasm/web';
+
+// Don't use the absoluteURL directly:
+const absoluteURL = 'http://127.0.0.1'
+
+// Instead, set the scope first:
+const scope = Math.random().toFixed(16)
+const scopedURL = setURLScope(absoluteURL, scope).toString()
+
+const { phpVersion } = parseWorkerStartupOptions<{ phpVersion?: string }>();
+const php = await PHP.load('8.0', {
+	requestHandler: {
+		documentRoot: '/',
+		absoluteUrl: scopedSiteUrl
+	}
+});
+
+// Expose the API to app.ts:
+const [setApiReady, ] = exposeAPI( php );
+setApiReady();
+

Original Playground docs source: https://playground.wordpress.net/developers/23-architecture/13-browser-scopes

]]> + + 43 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Cross-process communication]]> + https://playground.wordpress.net/developers-23-architecture-14-browser-cross-process-communication/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=44 + + Cross-process communication +

@php-wasm/web uses the Comlink library to turns the one-way postMessage available in JavaScript into a two-way communication channel.

+

If postMessage sounds unfamiliar, it's what JavaScript threads use to communicate. Please review the MDN Docs before continuing.

+

By default, postMessage does not offer any request/response mechanics. You may send messages to another thread and you may independently receive messages from it, but you can't send a message and await a response to that specific message.

+

To quote the Comlink library documentation:

+

main.js

+
import * as Comlink from 'https://unpkg.com/comlink/dist/esm/comlink.mjs';
+async function init() {
+	const worker = new Worker('worker.js');
+	// WebWorkers use `postMessage` and therefore work with Comlink.
+	const obj = Comlink.wrap(worker);
+	alert(`Counter: ${await obj.counter}`);
+	await obj.inc();
+	alert(`Counter: ${await obj.counter}`);
+}
+init();
+

worker.js

+
importScripts('https://unpkg.com/comlink/dist/umd/comlink.js');
+
+const obj = {
+	counter: 0,
+	inc() {
+		this.counter++;
+	},
+};
+
+Comlink.expose(obj);
+

Original Playground docs source: https://playground.wordpress.net/developers/23-architecture/14-browser-cross-process-communication

]]> + + 44 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress support]]> + https://playground.wordpress.net/developers-architecture-wordpress/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=45 + + WordPress support +

WordPress, as a PHP application, can run on PHP WebAssembly. However, there are a few caveats.

+

SQLite

+

First, WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground, therefore, ships PHP with the native SQLite driver and leans on SQLite.

+

But how can WordPress run on a different database?

+

Behind the scenes, the official SQLite Database Integration plugin intercepts all MySQL queries and rewrites them in SQLite dialect. The x.0 release ships a new WordPress Playground-informed translation layer that allows WordPress on SQLite to pass 99% of the WordPress unit test suite.

+

WordPress in the browser

+

You can use any WordPress build in the browser. For convenience and to reduce the data transfer size, WordPress Playground ships a few minified WordPress releases that you can use in the browser.

+

WordPress in Node.js

+

In Node.js, you'll typically want to mount WordPress from a disk directory.

+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/wordpress

]]> + + 45 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[How does it work?]]> + https://playground.wordpress.net/developers-23-architecture-16-wordpress-database/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=46 + + Database is supported via MySQL\<\-\>SQLite translation layer +

WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground therefore ships PHP with the native SQLite driver and leans on SQLite.

+

But how can WordPress run on a different database?

+

Behind the scenes, the official SQLite Database Integration plugin intercepts all MySQL queries and rewrites them in SQLite dialect. The 2.0 release ships a new WordPress Playground-informed translation layer that allows WordPress on SQLite to pass 99% of the WordPress unit test suite.

+

Original Playground docs source: https://playground.wordpress.net/developers/23-architecture/16-wordpress-database

]]> + + 46 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Bundling WordPress for the browser]]> + https://playground.wordpress.net/developers-23-architecture-17-browser-wordpress/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=47 + + Bundling WordPress for the browser +

The web bundler Dockerfile turns a vanilla WordPress into a browser-optimized one:

+
  • Makes WordPress run on SQLite using the official drop-in plugin as MySQL is unsupported in the browser.
  • Reduces the WordPress website size from about 70MB to about 10MB, or 5MB compressed.
  • Runs the WordPress installation wizard.
  • Bundles WordPress as a minified zip file.
+

Build a new bundle with nx bundle-wordpress playground-wordpress-builds --wp-version=<version>, e.g.:

+
nx bundle-wordpress playground-wordpress-builds --wp-version=6.1
+

The bundler outputs:

+
  • packages/playground/wordpress-builds/public/wp-6.1.zip – zipped WordPress files
  • packages/playground/wordpress-builds/public/wp-6.1/ – a directory with static assets for the specified WordPress versions
+

Consult the web bundler Dockerfile for more details (like the list of supported WordPress versions) and modify it to customize the default WordPress installation.

+

Original Playground docs source: https://playground.wordpress.net/developers/23-architecture/17-browser-wordpress

]]> + + 47 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Host your own Playground]]> + https://playground.wordpress.net/developers-architecture-host-your-own-playground/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=48 + + Host your own Playground +

You can host the Playground on your own domain instead of playground.wordpress.net.

+

This is useful for having full control over its content and behavior, as well as removing dependency on a third-party server. It can provide a more customized user experience, for example: a playground with preinstalled plugins and themes, default site settings, or demo content.

+

Before you start

+

Self-hosting Playground gives you full control, but requires understanding a few key concepts:

+

What to expect

+
  • Initial setup complexity: Building and deploying Playground involves multiple steps. Allow time for troubleshooting during your first deployment.
  • Static file hosting: Playground is primarily static files (HTML, JS, WASM) with minimal server-side requirements.
  • Browser-based execution: All WordPress processing happens in the user's browser via WebAssembly—your server only delivers files.
+

Performance considerations

+

Loading times depend on several factors:

+
| Factor            | Impact                                                              | Optimization                                |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------------------- |
+| **Plugin size**   | Large plugins (e.g., WooCommerce) can take 30-60 seconds to install | Pre-install plugins in your WordPress build |
+| **Network speed** | WASM files are ~15-30MB                                             | Use CDN with proper caching headers         |
+| **Browser**       | Chrome/Edge perform best; Safari uses fallback mechanisms           | Test across browsers                        |
+| **Device**        | Mobile devices load slower than desktop                             | Warn mobile users about longer load times   |
+

Browser compatibility

+

Playground works across modern browsers, but with some differences:

+
| Browser         | Status              | Notes                                                                              |
+| --------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| Chrome/Edge     | ✅ Best performance | Full support for all features                                                      |
+| Firefox         | ✅ Good             | Reliable performance                                                               |
+| Safari          | ✅ Good             | Recent improvements significantly enhanced reliability                             |
+| Mobile browsers | ⚠️ Limited          | Works, but with higher memory usage, and a 4G connection can impact the experience |
+

Technical note: Safari uses MessagePorts instead of SharedArrayBuffer for streaming responses. This fallback works reliably but adds slight overhead compared to Chrome/Edge.

+

Usage

+

A self-hosted Playground can be embedded as an iframe.

+
<iframe src="https://my-playground.com"></iframe>
+

Or dynamically loaded by passing the remote URL to the Playground Client.

+
import { startPlaygroundWeb } from '@wp-playground/client';
+
+const client = await startPlaygroundWeb({
+	iframe: document.getElementById('wp'),
+	remoteUrl: `https://my-playground.com/remote.html`,
+});
+

Static assets

+

There are several ways to get the static assets necessary to host the Playground.

+

In order of convenience and ease:

+
  • Download pre-built package
  • Fork the repository and build with GitHub Action
  • Build locally
+

Download pre-built package

+

To host the Playground as is, without making changes, you can download the built artifact from the latest successful GitHub Action.

+
  • Click on Deploy Playground website.
  • In the section Artifacts at the bottom of the page, click playground-website.
  • It's a zip package with the same files deployed to the public site.
+

Fork the repository and build with GitHub Action

+

To customize the Playground, you can fork the Git repository.

+

Build it from the fork's GitHub page by going to: Actions -> Deploy Playground website -> Run workflow.

+

Build locally

+

The most flexible and customizable method is to build the site locally.

+

Create a shallow clone of the Playground repository, or your own fork.

+
git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git
+

Enter the wordpress-playground directory.

+
cd wordpress-playground
+

Install dependencies, and build the website.

+
npm install
+npm run build:website
+

This command internally runs the nx task build:wasm-wordpress-net. It copies the built assets from packages remote and website into a new folder at the following path:

+
dist/packages/playground/wasm-wordpress-net
+

The entire service of the Playground consists of the content of this folder.

+

Summary of included files

+

The static assets include:

+
  • Data and WASM files for all available PHP and WordPress versions
  • remote.html - the core of Playground
  • index.html - the shell, or browser chrome
  • Web Worker script
+

You can deploy the content of the folder to your server using SSH, such as scp or rsync.

+

It is a static site, except for these dynamic aspects.

+
  • Apache server directive .htaccess file from the package remote
+

For these to work, you need a server environment with Apache and PHP installed.

+

NGINX configuration

+

As an alternative to Apache, here is an example of using NGINX to serve the Playground.

+

Refer to the source file

+

The example may be outdated. Please check the source file for the latest version.

+

The combined Apache .htaccess file looks like this.

+
AddType application/wasm .wasm
+

An equivalent in NGINX.

+
location ~* .wasm$ {
+  types {
+    application/wasm wasm;
+  }
+}
+

You may need to adjust the above according to server specifics, particularly how to invoke PHP for the path /plugin-proxy.

+

Caddy web server doesn't require any special config to work.

+

Customize bundled data

+

The file wp.zip is a bundle of all the files for the virtual file system in Playground. There's a data file for each available WordPress version.

+

The package at packages/playground/wordpress-builds is responsible for building these data files.

+

Edit the build script in Dockerfile to create a custom bundle that includes preinstalled plugins or content.

+

To rebuild the WordPress builds after customizing the Dockerfile, run the following command:

+
npm run rebuild:wordpress-builds
+

To rebuild the website to include the custom WordPress builds, follow the instructions here.

+

Install plugins

+

Here's an example of installing plugins for the data bundle.

+

Before the section titled Strip whitespaces from PHP files.

+
# === Preinstall plugins ===
+
+RUN cd wordpress/wp-content/mu-plugins && \
+    # Install plugins
+    for plugin_name in example-plugin-1 example-plugin-2; do \
+      curl -L https://downloads.wordpress.org/plugin/{$plugin_name}.latest-stable.zip -o {$plugin_name}.zip && \
+      unzip $plugin_file && \
+      rm $plugin_file && \
+      # Create entry file in mu-plugins root
+      echo "<?php require_once __DIR__.'/$plugin_name/$plugin_name.php';" > $plugin_name.php; \
+    done;
+

You can download plugins from URLs other than the WordPress plugin directory, or use Git to pull them from elsewhere.

+

It's also possible to copy from a local folder. For example, before RUN:

+
COPY ./build-assets/*.zip /root/
+

Then put the plugin zip files in build-assets. In this case, you may want to add their paths to .gitignore.

+

Import content

+

Here's an example of importing content.

+
# === Demo content ===
+
+COPY ./build-assets/content.xml /root/
+RUN cd wordpress ; \
+     echo "Importing content.."; \
+    ../wp-cli.phar --allow-root import /root/content.xml --authors=create
+

This assumes that you have put a WXR export file named content.xml in the folder build-assets. You can add its path to .gitignore.

+

Production deployment checklist

+

Before going live, verify your self-hosted Playground meets these requirements:

+

Server configuration

+
  • [ ] MIME types: Ensure .wasm files are served with application/wasm content type
  • [ ] CORS headers: If embedding cross-origin, configure appropriate CORS headers
  • [ ] Caching: Set long cache times for WASM and static assets (they're versioned)
  • [ ] Compression: Enable gzip/brotli for faster file transfers
  • [ ] HTTPS: Required for service workers and some browser features
+

Performance optimization

+
  • [ ] CDN: Serve static assets from a CDN for faster global delivery
  • [ ] Pre-installed plugins: Bundle frequently-used plugins in your WordPress build
  • [ ] Limit additional downloads: Minimize runtime plugin installations (by blueprints, for example)
+

Troubleshooting

+

Common issues and solutions

+

Playground fails to load or shows blank screen

+

Possible causes:

+
  • Server doesn't serve WASM files with correct MIME type
  • Deployment missing required files
  • JavaScript errors in browser console
+

Solutions:

+
  1. Check browser console for errors (F12 → Console tab)
  2. Verify .wasm files return application/wasm content type
  3. Verify you deployed all build files
+

Slow initial loading (30+ seconds)

+

Possible causes:

+
  • Installing large plugins at runtime
  • Missing CDN or caching configuration
  • User on slow network connection
+

Solutions:

+
  1. Pre-install plugins in your WordPress build instead of runtime installation
  2. Configure CDN with proper caching headers
  3. Show loading indicators to set user expectations
+

Original Playground docs source: https://playground.wordpress.net/developers/architecture/host-your-own-playground

]]> + + 48 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Limitations]]> + https://playground.wordpress.net/developers-limitations/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=49 + + Limitations +

WordPress Playground is under active development and has some limitations you should keep in mind when running it and developing with it.

+

You can track the status of these issues on the Playground Project board.

+

In the browser

+

Temporary by design

+

Playground creates fresh WordPress instances on each page load. Refreshing the browser page discards all database changes, uploads, and modifications.

+

Why this happens: Playground streams WordPress directly to your browser rather than serving it from a traditional server. Each refresh starts a clean slate.

+

To persist your work:

+
  • Save: Enable browser storage via the "Save" button (top right, next to address bar), before refreshing the page via the browser bar.
  • For development: Use Playground CLI which supports persistent local storage
+

Tip

+

The dedicated refresh button inside Playground only reloads WordPress content—it preserves your PHP/WP state. The browser's refresh button (F5 or Cmd+R) destroys the entire instance.

+

Refresh Playground Button

+

<blockquote> <figure> <figcaption><i>1. Exporting Playground:</i></figcaption>

+

Save Button

+

</figure>

+

<figure> <figcaption><i>2. Save button:</i></figcaption>

+

Save Button

+

</figure> </blockquote>

+

Browser support

+

WordPress Playground is designed to work across all major desktop and mobile browsers. This includes:

+
  • Desktop browsers: Chrome, Firefox, Safari, Edge, and other Chromium-based browsers
  • Mobile browsers: Safari (iOS), Chrome (Android), and other mobile browser variants
+

Playground leverages modern web technologies and should function consistently across these browser environments. However, some advanced features may have varying levels of support depending on the specific browser and its version.

+

Performance expectations

+

Loading times vary based on what Playground needs to set up:

+
| Scenario                               | Typical Load Time          |
+| -------------------------------------- | -------------------------- |
+| Fresh WordPress (no plugins)           | 5-10 seconds               |
+| With small plugins                     | 10-20 seconds              |
+| With large plugins (e.g., WooCommerce) | 30-60 seconds              |
+| On mobile devices                      | 1.5-2x slower than desktop |
+

Save Button

+

Factors that affect performance:

+
  • Plugin size: Large plugins take longer to install at runtime
  • Network speed: WASM files are 15-30MB
  • Device memory: Low-memory devices may experience slowdowns
  • Browser: Chrome/Edge perform best; Safari slightly slower
+

<blockquote> <strong>Note:</strong> Opera Mini support is not currently confirmed. </blockquote>

+

When developing with Playground

+

Iframe quirks

+

Playground renders WordPress in an iframe so clicking links with target="_top" will reload the page you’re working on. Also, JavaScript popups originating in the iframe may not always display.

+

Run WordPress PHP functions

+

Playground supports running PHP code in Blueprints using the runPHP step. To run WordPress-specific PHP functions, you’d need to first require wp-load.php:

+
{
+	"step": "runPHP",
+	"code": "<?php require_once('wordpress/wp-load.php'); OTHER_CODE ?>"
+}
+

Using WP-CLI

+

You can execute wp-cli commands via the Blueprints wp-cli step. However, since Playground runs in the browser, it doesn't support the full array of available commands. While there is no definite list of supported commands, experimenting in the online demo will help you assess what's possible.

+

Original Playground docs source: https://playground.wordpress.net/developers/limitations

]]> + + 49 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground Developers Docs]]> + https://playground.wordpress.net/developers/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=50 + + Developers Docs +

Hi! Welcome to WordPress Playground Developer documentation.

+

<p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>

+
  • Documentation – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs.
  • Blueprints – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from the Blueprints docs hub.
  • 👉 Developers (you're here) – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in this Developers docs hub.
  • API Reference – All the APIs exposed by WordPress Playground
+

Navigating the Developers documentation hub

+

This docs hub is focused on Developers info and is divided into the following major sections:

+ +
  • Local Development: Discover the tools provided by Playground to streamline the process of setting up and managing WordPress sites and build your apps.
+ +
  • Architecture: The specifics of WordPress Playground's architecture, including its various components and tools.
+
  • Limitations: Learn more about the current limitations of WordPress Playground, which include disabled network connections, temporary data, iframe quirks, PHP function execution requirements, and partial WP-CLI support.
+

Original Playground docs source: https://playground.wordpress.net/developers/

]]> + + 50 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Build]]> + https://playground.wordpress.net/about-build/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=51 + + Build +

WordPress Playground can help you to create and learn WordPress quickly, even on mobile with no signal. You can use Playground where you work best, whether that’s in the browser, Node.js, mobile apps, VS Code, or elsewhere.

+

Setting up a local WordPress environment quickly

+

You can seamlessly integrate Playground into your development workflow to launch a local WordPress environment quickly for testing your code. You can do this directly from the terminal or your preferred IDE.

+

Save changes done on a Block Theme and create GitHub Pull Requests

+

You can connect your Playground instance to a GitHub repository and create a Pull Request with the changes you’ve made through the WordPress UI, leveraging the Create Block Theme plugin.

+

With this workflow, you could build a block theme completely in your browser and save your changes to GitHub, or you could improve/fix an existing one.

+

Embedded media: https://www.youtube.com/embed/94KnoFhQg1g

+

Some more examples of this workflow:

+ +

Synchronize your playground instance with a local folder and create GitHub Pull Requests

+

Storage Type Device Snapshot

+

With Google Chrome you can synchronize your Playground instance with a local directory, that can be either:

+
  • An empty directory – to save this Playground and start syncing
  • An existing directory – to load it here and start syncing
+

This feature is only available for Google Chrome for now. It won't work with other browsers yet.

+

Regarding changes done on both sides of the connection:

+
  • Files changed in the Playground will be synchronized to your computer.
  • Files changed on your computer will not be synchronized to Playground. You'll need to click the "Sync local files" button.
+

With this workflow, you can create GitHub PRs directly from your changes made in your local directory.

+

See here a little demo of this workflow in action:

+

Embedded media: https://www.youtube.com/embed/UYK88eZqrjo

+

Integrate with other APIs to create new tools.

+

Playground can be combined with different APIs to create amazing tools. The possibilities are endless.

+

You can use WordPress Playground in Node.js to create new tools. The @php-wasm/node package, which ships the PHP WebAssembly runtime, is the package used for https://playground.wordpress.net/, for example.

+

Another interesting app built on top of Playground is Translate Live (see example) which, in combination with OpenAI provides a WordPress translations tool “in place” where translations can be seen and modified in their real context (see example). Read more about this tool at Translate Live: Updates to the Translation Playground

+

Work offline and as a native app

+

When you first visit playground.wordpress.net, your browser automatically caches all the necessary files to use Playground. From that point on, you can access playground.wordpress.net, even without an internet connection, ensuring you can continue working on your projects without interruptions.

+

You can also install Playground on your device as a Progressive Web App (PWA) to launch the Playground directly from your home screen—just like a native app.

+

Read Introducing Offline Mode and PWA Support for WordPress Playground for more info.

+

Embed a WordPress site in non-web environments

+

The How to ship a real WordPress site in a native iOS app via Playground? guide shows how we can leverage Playground to wrap a WordPress site into an IOS app.

+

Original Playground docs source: https://playground.wordpress.net/about/build

]]> + + 51 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[About WordPress Playground]]> + https://playground.wordpress.net/about/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=52 + + About WordPress Playground +

What is WordPress Playground?

+

WordPress Playground is the platform that lets you run WordPress instantly on any device without a host. It allows you to experiment and learn about WordPress without affecting your live website. It's a virtual sandbox where you can play around with different features, designs, and settings in a safe and controlled environment.

+

WordPress Playground is your place to build, test, and launch:

+
  • Build: WordPress Playground can help you to build products with WordPress. Use it from where you work best, whether that's in the browser, Node.js, mobile apps, VS Code, or elsewhere.
  • Test: Upgrade your QA process with WordPress Playground. Quickly test your plugins or themes, experiment in a private sandbox, and create PRs from your WP Playground instance to any repo.
  • Launch: Use WordPress Playground to showcase your product, let users try it live, or launch it in the App Store with zero lead time.
+

Why WordPress Playground?

+

Try themes and plugins on the fly

+

With WordPress Playground, you can explore any theme. You can choose from a wide range of themes and see how they look on your site. You can also modify the colors, fonts, layouts, and other visual elements to create a unique design.

+

In addition to themes, you can experiment with plugins too. With WordPress Playground, you can install and test different plugins to see how they work and what they can do for your site. This allows you to explore and understand the capabilities of WordPress without worrying about breaking anything.

+

Create content on the go

+

Another great feature of WordPress Playground is the ability to create and edit content. You can write blog posts, create pages, and add media like images and videos to your site. This helps you understand how to organize and structure your content effectively.

+

The content you create is limited to the Playground on your device and disappears once you leave it, so you are free to explore and play without risking breaking any actual site.

+

But hey! You can also connect your Playground instance to a GitHub repo and create a PR to persist those changes.

+

It's super safe

+

Overall, WordPress Playground provides a risk-free environment for beginners to learn and get hands-on experience with WordPress. It helps you to gain confidence and knowledge before making changes to your live website.

+

Tip

+

Check the guides section to learn more about how to leverage WordPress Playground to test your themes and plugins and create content on the fly.

+

How does WordPress Playground work?

+

When you first start using WordPress Playground, you'll be provided with a separate space where you can create and customise your own WordPress website. This space is completely isolated from your actual website.

+

Streamed, not served.

+

The WordPress you see when you open Playground in your browser is a WordPress that should function like any WordPress, with a few limitations and the important exception that it's not a permanent server with an internet address which will limit connections to some third-party services (automation, sharing, analysis, email, backups, etc.) in a persistent way.

+

The loading screen and progress bar you see on Playground includes both the streaming of those foundational technologies to your browser and configuration steps from WordPress Blueprints (see examples), so that a full server, WordPress software, Theme & Plugin solutions and configuration instructions can be streamed over-the-wire.

+

What makes Playground different from running WordPress on a web server or local desktop app?

+

Web applications like WordPress have long relied on server technologies to run logic and store data.

+

Using those technologies has meant either running a web server connected to the internet or using those technologies in a desktop service or app (sometimes called a "WordPress local environment") that either leans on a virtual server with the technologies installed or the underlying technologies on the current device.

+

Playground is a novel way to stream server technologies—including WordPress (and WP-CLI)—as files that can then run in the browser.

+

Original Playground docs source: https://playground.wordpress.net/about

]]> + + 52 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Launch]]> + https://playground.wordpress.net/about-launch/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=53 + + Launch +

Reach your clients or customers faster. Showcase your product, let users try it live, or launch it in the App Store with zero lead time.

+

Embed interactive product demos on websites.

+

Leverage blueprints' potential to create interactive demos of your plugins or themes. For example, you can provide a link to your users/clients to showcase how your custom plugin integrates with an adapted theme, demonstrating their combined functionality and appearance.

+

Read more about this at How to use WordPress Playground for interactive demos

+

Get inspiration about the type of interactive demos you can create at the Blueprints Gallery

+

The Blueprints builder tool allows you edit your blueprint online and run it directly in a Playground instance.

+

Embedded media: https://www.youtube.com/embed/lQzozsoJ3aY

+

Another handy tool to create a blueprint is the WordPress Playground Step Library tool that provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!

+

Embed demos in posts and pages with the WordPress Playground block

+

This WordPress Playground block allows you to embed WordPress Playground in your posts and pages. You can also include an interactive code editor to demonstrate and teach your readers how WordPress plugins are built.

+

With this block you have a straightforward and effective way to create live WordPress environments that can be embedded within your blog posts.

+

For any issues or questions about the WordPress Playground Block, please open a GitHub issue in the playground-tools repository.

+

Put a native app running WordPress in the App Store.

+

Check the How to ship a real WordPress site in a native iOS app via Playground? guide for info on this use case

+

Original Playground docs source: https://playground.wordpress.net/about/launch

]]> + + 53 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Test]]> + https://playground.wordpress.net/about-test/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=54 + + Test +

Upgrade your QA process with the ability to review progress in your browser in a single click. When you’re ready, push updates instantly.

+

Test any theme or plugin

+

With Playground, you can test any plugin or theme. Use the Query API to quickly load any plugin or theme published in wordpress.org plugins and themes directories.

+

For example, the following link will load the “pendant” theme and the “gutenberg” plugin on a Playground instance:

+

https://playground.wordpress.net/?theme=pendant&plugin=gutenberg

+

But you can also test more elaborate configurations using blueprints, for example testing a plugin’s code from a gist (see blueprint and live demo)

+

Live preview pull requests

+

Testing pull requests is one of the most exciting use cases for the Playground project. With Playground, you can enable a Live preview link on each Pull Request of a WordPress-related project in GitHub so that developers can see in action the effects of code in that Pull Request. Read more about this at Preview WordPress Core Pull Requests with Playground.

+

There are some public implementations of this use case such as WordPress Core PR previewer and Gutenberg PR previewer. Users can input the PR number or URL to be redirected to a WordPress instance, powered by Playground, where the changes from the PR are applied.

+

You can add automated PR preview buttons to your own plugin or theme repository using the WordPress Playground PR Preview GitHub Action. When someone opens a pull request, the action automatically adds a button that launches a configured WordPress instance with the changes ready to test. For detailed setup instructions and advanced configurations, see the Adding PR Preview Buttons with GitHub Actions guide.

+

Clone your site and experiment in a private sandbox.

+

With the Sandbox Site powered by Playground plugin you can create a private WordPress Playground copy of your site to test plugins safely or do any other experiments on your site’s replica without uploading any data to the cloud and without affecting the original site.

+

Test different WordPress and PHP versions.

+

With Playground, you can quickly test any major WordPress or PHP version by _customizing its settings_ or using a custom blueprint with the preferredVersions property.

+

For example, you can always test the latest development version of WordPress, also called Beta Nightly, from this link: https://playground.wordpress.net/?wp=nightly

+

During the Beta period of any WordPress release, you can also test the latest WordPress Beta or RC release with theme test data and debugging plugins (see blueprint and live demo).

+

You can also load any theme, plugin, or configuration in any of the available WordPress and PHP versions to check how they work in that environment.

+

The WordPress Playground: the ultimate learning, testing, & teaching tool for WordPress provides a great overview of the testing possibilities with Playground.

+

Original Playground docs source: https://playground.wordpress.net/about/test

]]> + + 54 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Changelog]]> + https://playground.wordpress.net/changelog/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=55 + + Changelog +

All notable changes to this project are documented in this file by a CI job that runs on every NPM release. The file follows the Keep a Changelog format.

+

[v3.1.21] (2026-04-20)

+

PHP WebAssembly

+
  • Add PHP 5.2 WebAssembly builds and runtime support. (#3501)
+

Various

+
  • [Docs] Update trusted publisher setup instructions. (#3505)
  • [PHP] Align @php-wasm/\{web,node\}-5-2 with workspace and add READMEs. (#3506)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @JanJakes

+

[v3.1.20] (2026-04-16)

+

Tools

+

GitHub integration

+
  • [Github Actions] Fix GitHub release publishing wrong version. (#3488)
+

Documentation

+
  • [ xdebug ] Add Xdebug use case examples. (#3075)
+

Documentation

+
  • [Docs] Removing documentation fragments. (#3470)
+

PHP WebAssembly

+
  • [PHP] Fix gzip crash – add missing zlib/curl functions to ASYNCIFY_ONLY. (#3491)
+

Bug Fixes

+
  • Fix Safari failing to make cross-origin HTTP requests. (#3440)
  • Restore the missing mounts.spec.ts. (#2478)
+

Reliability

+
  • [php-wasm-node-polyfills] Remove @php-wasm/node-polyfills package. (#3476)
+

Various

+
  • Remove extraneous file and update package-lock.json. (#3477)
  • [Docs] Updating asyncify page. (#3459)
  • [Docs] Updating blueprint bundles page. (#3465)
  • [i18n] Add Bengali translation for blueprints tutorial pages. (#3461)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @fellyph @mho22 @perashanid

+

[v3.1.19] (2026-04-13)

+

Documentation

+
  • [Docs] Removing heading IDs to make documentation compatible to migrate to org. (#3466)
+

PHP WebAssembly

+
  • [ xdebug ] Skip paths alongside path mappings in IDE configs. (#3366)
  • [AI] Add compilation and debugging skills for PHP.wasm. (#3445)
+

Website

+
  • Add custom error message when artifact is expired. (#3453)
  • Define DB_NAME via auto-prepend instead of rewriting wp-config.php. (#3458)
+

Bug Fixes

+
  • Fix broken deploy workflow guards. (#3479)
+

Various

+
  • Exclude loopback requests from trying to pre-fetch. (#3305)
  • Skip running irrelevant actions on forks. (#3473)
  • [Docs] Add overlay parameter to Playground URL options. (#3457)
  • [i18n] Add Bengali translation for blueprints documentation. (#3462)
  • [i18n] Added Gujarati translation for wp-playground agent skill guide. (#3333)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ashfame @brandonpayton @dd32 @fellyph @JanJakes @mho22 @perashanid @Rima1889

+

[v3.1.18] (2026-04-07)

+

[v3.1.17] (2026-04-07)

+

Enhancements

+
  • [CLI] Fix intermittent ENOTDIR crash when applying post-install mounts. (#3468)
+

Documentation

+
  • [Docs] Load assets from githubusercontent to make it compatible with handbook. (#3467)
+

Various

+
  • [cli] Update WordPress version validation to include "beta" as a valid slug. (#3446)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph

+

[v3.1.16] (2026-04-06)

+

Website

+
  • Add WebMCP support to the Playground website. (#3298)
  • Centralized site management API and expose as window.playgroundSites. (#3401)
+

Bug Fixes

+
  • Fix phpMyAdmin and Adminer crash on PHP 8.5. (#3444)
  • [CLI] Fix --skip-sqlite-setup false pre-flight database error. (#3456)
+

Various

+
  • Update SQLite refresh script to support the SQLite monorepo. (#3452)
  • [i18n] Add Bengali translation for blueprints/05-steps.md. (#3432)
  • [i18n] ja translations developer architecture Service Workers and Scopes. (#3431)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @JanJakes @mho22 @noruzzamans @shimotmk

+

[v3.1.15] (2026-03-31)

+

PHP WebAssembly

+
  • [PHP] Fix "Controller is already closed" crash in CLI server. (#3441)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.1.14] (2026-03-30)

+

PHP WebAssembly

+
  • [Redis] va_arg long to va_arg zend_long for WASM32 ABI compatibility. (#3417)
+

Internal

+
  • Allow manual trigger for GitHub Release workflow. (#3430)
  • Create GitHub Release on every npm publish. (#3429)
  • Update fast-xml-parser to fix Dependabot issue. (#3422)
+

Bug Fixes

+
  • [Playground CLI] Support overriding WP_DEBUG using define-bool and define-number. (#3254)
+

Various

+
  • Load SQLite for phpMyAdmin and Adminer using WP configuration. (#3420)
  • Revert "Update SQLite database path (#3428)". (#3435)
  • Update SQLite database path. (#3428)
  • [MCP] Add REST API authentication to request tool. (#3439)
  • [i18n] Add Bengali translation for blueprints tutorial and guide pages. (#3412)
  • [i18n] Add French translation for build-your-first-blueprint.md. (#3358)
  • [i18n] Create index.md and add French translation. (#3357)
  • [i18n] ja translations developer architecture Iframe-based rendering and PHP Worker Threads. (#3404)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @bgrgicak @JanJakes @mho22 @perashanid @shimotmk @wojtekn

+

[v3.1.13] (2026-03-23)

+

Enhancements

+
  • [CLI] Auto restart with --experimental-wasm-jspi support. (#3281)
+

PHP WebAssembly

+
  • Fix Emscripten PIPEFS race condition in proc_open. (#3399)
+

Bug Fixes

+
  • Fix Dependabot exclude paths to match dirs recursively. (#3426)
+

Performance

+
  • CLI: Add site editor performance benchmark. (#3408)
+

###

+
  • CLI]: Consider it a lint error for CLI to depend on large Playground web packages. (#3410)
  • Claude] Harden allow/deny lists and clarify dev server behavior. (#3373)
+

Various

+
  • Bump transitive dependency flatted from 3.4.1 to 3.4.2. (#3424)
  • Remove unnecessary phpMyAdmin guard. (#3413)
  • Support blueprint.json in ZIP at root or inside a directory. (#3223)
  • [Website] Provide better UX for wasm and script download failures. (#3348)
  • [personal-wp] Add Playwright end-to-end tests. (#3405)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @bgrgicak @brandonpayton @wojtekn

+

[v3.1.12] (2026-03-16)

+

Enhancements

+

Personal Playground

+
  • Remove Google Analytics from personal-wp. (#3381)
+

Bug Fixes

+
  • Fix: Force x-safari scheme for Linkedin app. (#3392)
  • Fix: Ignore ERR_STREAM_UNABLE_TO_PIPE in CLI server. (#3397)
+

Personal Playground

+
  • [Web] Fix bugs with running personal WP dev server. (#3391)
+

Various

+
  • Add a notice to open Playground in a separate view. (#3387)
  • CLI: Simplify and optimize process existence check for temp dir cleanup. (#3395)
  • Move WP refresh concurrency group to workflow level. (#3380)
  • Re-enable webkit end-to-end tests. (#3379)
  • [CLI] Use local phars for php command phar tests. (#3382)
  • [personal-wp] Adding open-graph My WordPress. (#3390)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @brandonpayton @fellyph @zaerl

+

[v3.1.11] (2026-03-12)

+

Enhancements

+
  • [CLI] php command to run PHP scripts. (#2641)
+

Various

+
  • [PHP] Mount parent directory for file symlinks so DIR works. (#3377)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.1.10] (2026-03-12)

+

Various

+
  • Use deploy keys instead of username/token for workflow pushes to trunk. (#3374)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.1.9] (2026-03-11)

+

Enhancements

+
  • [MCP] Preserve MCP connection parameters when opening site in new tab. (#3371)
+

PHP WebAssembly

+
  • [Website] Use content-type: Application/octet-stream for CORS proxy requests. (#3364)
  • [PHP] Recompile PHP.wasm ASYNCIFY with MAIN_MODULE set to 2. (#3335)
+

Various

+
  • Ignore worktree and .claude dirs in .nxignore and .gitignore. (#3368)
  • Redirect unscoped WP URLs back to scoped WP URLs in service worker. (#3370)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @mho22

+

[v3.1.8] (2026-03-10)

+

Website

+
  • Fix redirect loop on Safari by awaiting cookie store population and re-scoping redirect URLs. (#3365)
+

Bug Fixes

+
  • Remove ws from root overrides to fix Lerna publish. (#3367)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @mho22

+

[v3.1.7] (2026-03-10)

+

[v3.1.6] (2026-03-10)

+

PHP WebAssembly

+
  • [PHP] Call php.mount instead of php.FS.mount in proxyFileSystem. (#3346)
+

Website

+
  • Support streamed PHP responses in the service worker. (#3361)
  • [Playground Website] Playground MCP server. (#3290)
+

Various

+
  • Correct error message formatting in resources.ts. (#3363)
  • [docs] Adding playwright guide. (#3360)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @fellyph @pkevan

+

[v3.1.5] (2026-03-09)

+

Documentation

+
  • [Docs] Updating run cli demos. (#2833)
  • [docs] Adding runCLI and git action video to the documentation. (#3101)
+

PHP WebAssembly

+
  • [Website] Support CURLFile uploads. (#3341)
  • [tcp-over-fetch] Buffer request body for non-HTTPS fetches. (#3356)
  • [tcp-over-fetch] Strip Content-Encoding from response headers. (#3355)
  • [PHP] Recompile PHP.wasm JSPI with MAIN_MODULE set to 2. (#3332)
+

Website

+
  • Allow web deploy from WP update workflow. (#3343)
+

Various

+
  • Ignore ERR_STREAM_PREMATURE_CLOSE in CLI server. (#3304)
  • Make error logging conditional on WP_DEBUG_LOG. (#3300)
  • [CORS Proxy] Fix FirewallInterferenceError on local dev server. (#3353)
  • [Website] Make Google Analytics configurable via environment variable. (#3322)
  • [Website] Support Git repo URLs in ?plugin= Query API parameter. (#3339)
  • [docs] Adding cli start command. (#3239)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @andreilupu @bcotrim @brandonpayton @dd32 @fellyph @JanJakes @mho22

+

[v3.1.3] (2026-03-02)

+

Tools

+
  • [AI] Add devcontainer configuration. (#3276)
+

Documentation

+
  • Clarify Document-Isolation-Policy comments in service worker. (#3319)
+

PHP WebAssembly

+
  • [ xdebug ] Map paths and skip paths with Xdebug 3.5. (#3115)
  • [PHP] Add cp method to Universal PHP. (#3234)
  • [PHP] Add few more function names and Refactor test files. (#3287)
+

Website

+
  • [Web] Avoid cross-origin policy errors in editor. (#3312)
+

Bug Fixes

+
  • Fix /wp-admin blank page when response crosses Comlink worker boundary. (#3301)
  • [Playground CLI] Return a readable error and hint when given port is already in use. (#3238)
  • [WordPress Builds] Fix semver crash on two-part WordPress versions. (#3299)
  • [WordPress Builds] Remove || true artifact in wordpress build. (#3296)
+

Various

+
  • Add ability to disable save. (#3271)
  • Correct plugin directory reference in documentation. (#3323)
  • Move MountDevice type declaration to @wp-playground/storage. (#3315)
  • Reduce Playground CLI target worker count to five. (#3308)
  • Update .nvmrc from Node 20 to Node 22. (#3297)
  • [AI] Symlink .claude/skills to .agents/skills. (#3293)
  • [docs] Adding skills guide. (#3282)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @dd32 @epeicher @fellyph @fredrikekelund @JanJakes @mho22 @n8finch @zaerl

+

[v3.1.2] (2026-02-23)

+

Tools

+
  • [AI] Add Playground website debugging skill. (#3278)
  • [AI] Improve AGENTS.md configuration. (#3275)
+

Bug Fixes

+
  • Fix Node.js version for WP rebuilds which require JSPI. (#3294)
+

Various

+
  • Add streaming support for large file downloads (&gt;2GB). (#3222)
  • Introduce token-based WP configuration transformer. (#3264)
  • Suppress Vite warning in dev env. (#3292)
  • [AI] Add Nx MCP plugin and workspace guidelines to AGENTS.md. (#3286)
  • [AI] Add path manipulation guidance to AGENTS.md. (#3291)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ashfame @bgrgicak @brandonpayton @epeicher @JanJakes

+

[v3.1.1] (2026-02-18)

+

Bug Fixes

+
  • [CLI] Eliminate duplicate Playground CLI Ready message. (#3288)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.1.0] (2026-02-18)

+

Bug Fixes

+
  • [CLI] Fix native file locking for Windows within same multi-threaded architecture. (#3150)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.0.54] (2026-02-18)

+

Blueprints

+
  • Define $\_SERVER['HTTP_HOST'] in the enableMultisite step. (#3214)
+

Tools

+
  • Upgrade NX from 21.3.12 to 22.5.1. (#3279)
  • [AI] Add shared Claude Code settings. (#3277)
+

Various

+
  • Allow publishing npm packages from non-trunk branches. (#3285)
  • [docs] Correct "OpenAI" spacing. (#3280)
  • [i18n] Add Bengali translation for guides/for-plugin-developers.md. (#3273)
  • [i18n] ja translations developer Limitations. (#3272)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bcotrim @bookchiq @JanJakes @noruzzamans @shimotmk

+

[v3.0.53] (2026-02-16)

+

Various

+
  • Further fixes for selected Node.js versions and related CI errors. (#3265)
  • Use Node.js 22 in refresh workflows to fix .mts loader errors. (#3269)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.0.52] (2026-02-12)

+

[v3.0.51] (2026-02-12)

+

Bug Fixes

+
  • Fix npm publish by adding glob as a devDependency. (#3263)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.50] (2026-02-12)

+

PHP WebAssembly

+
  • Upgrade nx 19 → 21 and lerna 7 → 9 to fix publish. (#3262)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.49] (2026-02-12)

+

Various

+
  • Update NPM packages with vulnerabilities. (#3261)
+

Contributors

+

The following contributors merged PRs in this release:

+

@mho22

+

[v3.0.48] (2026-02-11)

+

Enhancements

+
  • [CLI] Add --phpmyadmin flag for database management. (#3224)
+

PHP WebAssembly

+
  • [PHP-wasm] Convert paths to Posix paths during symlink mounting. (#3253)
+

Website

+
  • Add URL route to open Blueprint Gallery via ?overlay=blueprints. (#3220)
  • Remove breakpoint helpers, rewrite AI-generated comments. (#3259)
+

Bug Fixes

+
  • Avoid blueprints package dependency on @php-wasm/web. (#3257)
+

Various

+
  • Add PHPProcessManager test for request queuing and instance reuse. (#3233)
  • Add ashfame to workflow maintainers list. (#3250)
  • Add clarifying comment. (#3251)
  • Downgrade nvm version to 20.18.3. (#3260)
  • Revert "Update @types/node and node versions in package.json (#3247)". (#3256)
  • Switch to a robust check for node env detection. (#3248)
  • Update @types/node and node versions in package.json. (#3247)
  • Update NPM packages with vulnerabilities. (#3241)
  • [Docs] Adding playground for everyone guide. (#3103)
  • [docs] Updating host own playground page. (#3242)
  • [docs] Updating screenshots and content from web instance page. (#3188)
  • [i18n] Add Bengali translation for guides/index.md. (#3230)
  • [i18n] Add Bengali translation for guides/playground-for-everyone.md. (#3249)
  • [i18n] Add Bengali translation for guides/wordpress-native-ios-app.md. (#3231)
  • [i18n] Add Bengali translation for test.md. (#3229)
  • [i18n] Update translations.md for multiple languages. (#3177)
  • [i18n] ja translations developer architecture PHP browser-concepts an…. (#3228)
  • feat: [website] UI Architecture Improvement Plan #3100 - Code Splitting, Modal Registry, and Responsive Design. (#3109)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @bgrgicak @bph @brandonpayton @fellyph @JanJakes @mho22 @noruzzamans @Omcodes23 @shimotmk

+

[v3.0.47] (2026-02-02)

+

Blueprints

+
  • Fix wp-cli step failing on STDERR output with successful exit codes. (#3210)
+

PHP WebAssembly

+
  • [PHP web] Lower initial memory allocation for PHP instances. (#3192)
  • [PHPProcessManager] Spawn at most 2 PHP instances. (#3187)
  • [PHP] Remove considerPrimary option from acquirePHPInstance. (#3191)
+

Website

+
  • Disable pattern picker modal to prevent iOS Safari OOM crashes. (#3226)
  • Fix Safari PWA cache failures by stripping Range headers. (#3200)
  • Replace .blob() with .arrayBuffer() to avoid disk space errors. (#3212)
  • Retry import("main.js") when it fails in Safari. (#3216)
  • Fix Safari loading stale index.html after deployments. (#3208)
  • Improve OAuth flow for private GitHub repositories. (#3181)
+

Internal

+
  • [php-wasm-progress] Add a throttle of 500 milliseconds to the notify function. (#3198)
+

Bug Fixes

+
  • Fix Bad Gateway and optimize PHP workers. (#3219)
  • Fix Xdebug hang in packaged Electron apps. (#3125)
+

Various

+
  • Load SQLite driver from trunk instead of develop. (#3206)
  • Translate title and description for 08-examples.md. (#3166)
  • [Docs] Document git:Directory resource options. (#3179)
  • [Docs] Update translations and configuration in docusaurus.config.js. (#3176)
  • [Personal-WP] Port Safari fixes from website package. (#3221)
  • [Website] Fix Safari failing to import main module after deployments. (#3215)
  • [Website] Fix plugin-proxy artifact lookup for busy repos. (#3211)
  • [docs] Enable Bengali at the language switcher dropdown. (#3207)
  • [i18n] Add Bengali translation for about/launch.md. (#3183)
  • [i18n] Add Bengali translation for intro.md. (#3194)
  • [i18n] Add Bengali translation for quick-start-guide.md. (#3196)
  • [i18n] Add Bengali translation for resources.md. (#3201)
  • [i18n] Add Bengali translation for web-instance.md. (#3202)
  • [website] Switch error modal Kapa widget to hcaptcha. (#3209)
+

Personal Playground

+
  • [Personal-WP] Fix ?plugin= URL parameter not installing plugins. (#3218)
  • [Personal-WP] Fix broadcast message loop in tab coordinator. (#3217)
  • [Personal-WP] Improve recovery mode and add direct OPFS file browser access. (#3182)
  • [personal-wp] Add app catalog. (#3173)
  • [personal-wp] Add deployment workflow for my.wordpress.net. (#3184)
  • [personal-wp] Add multi-tab coordination. (#3163)
  • [personal-wp] Backup reminder UI. (#3162)
  • [personal-wp] Fix backup status showing "Infinity days since backup". (#3213)
  • [personal-wp] Skip CORS proxy for localhost requests. (#3199)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @beryl-dlg @epeicher @fellyph @JanJakes @mho22 @noruzzamans

+

[v3.0.46] (2026-01-26)

+

PHP WebAssembly

+
  • [PHP] Fix PHP web asyncify build socket function exports. (#3168)
+

Various

+
  • [i18n] Add Bengali translation for about/build.md. (#3165)
  • [website] Fix broken end-to-end tests because of sqlite db integration update. (#3172)
+

Personal Playground

+
  • [personal-wp] Add Health Check recovery. (#3157)
  • [personal-wp] Introduce a Personal Playground mode. (#3155)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @noruzzamans

+

[v3.0.45] (2026-01-22)

+

Tools

+

PHP WebAssembly

+
  • [PHP] Redis as a dynamic extension for Node.js. (#3129)
+

PHP WebAssembly

+
  • [PHP] Add php-memcached as a dynamically loadable extension for Node.js. (#3133)
+

Website

+
  • More reliably relay blueprints to kapa. (#3153)
+

Bug Fixes

+
  • Fix "Cannot read properties of undefined (reading 'data')" with nx. (#3151)
+

Various

+
  • Added changes to correct automatically translated text in French for …. (#3159)
  • Corrections to automattic translation for 08-examples.md. (#3161)
  • Update lock file in dev-tools. (#3154)
  • [PHP] Use synchronous connect() for Asyncify builds. (#3160)
  • [i18n] Add Bengali translation for about/index.md. (#3149)
  • [i18n] Add Bengali translation for releases.md. (#3142)
  • [i18n] ja translations developer architecture PHP Filesystem and Asyncify. (#3141)
+

Personal Playground

+
  • [website] Refactor out an Overlay component from saved-playgrounds-overlay. (#3152)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @beryl-dlg @noruzzamans @shimotmk

+

[v3.0.44] (2026-01-20)

+

Enhancements

+
  • [CLI] Enable defining WordPress constants via CLI flags. (#3128)
+

PHP WebAssembly

+
  • [PHP] gethostbyname – native DNS resolution in Node.js builds. (#2988)
+

Website

+
  • Fix sitemap.xml redirect to wp-sitemap.xml. (#3140)
+

Internal

+
  • Update CLAUDE.md with Node.js version guidance. (#3144)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.43] (2026-01-19)

+

Enhancements

+
  • Add CLAUDE.md for AI assistant guidance. (#3136)
+

PHP WebAssembly

+
  • Remove support for PHP 7.2 and 7.3. (#3127)
  • [PHP] Add mmap support to proxyFS. (#3126)
  • [PHP] Cleanup 7.2 and 7.3-specific build code. (#3137)
+

Website

+
  • Always offer to save the site when unrecognized ?site-slug= is used. (#3135)
+

Various

+
  • Updating @vitejs/plugin-react to version 5.1.2 in package.json. (#3110)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph

+

[v3.0.42] (2026-01-15)

+

Enhancements

+
  • Clean up CLI output and simplify mount tracking. (#3122)
+

Various

+
  • [Docs] Updating limitations page. (#3108)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph

+

[v3.0.41] (2026-01-14)

+

Enhancements

+
  • Update Node.js version in .nvmrc to v22.12.0. (#3114)
  • [CLI] Add high-level start command for easy local WordPress development. (#3040)
  • [CLI] Deprecate --debug switch in favor of --verbosity=debug. (#3084)
  • [CLI] @wp-playground/cli start persist sites. (#3119)
+

PHP WebAssembly

+
  • [Node] Improve error messages when dynamic imports fail in Node vm contexts. (#3121)
  • [PHP] Fix external dynamic imports issue in PHP.wasm Web. (#3093)
+

Website

+
  • Customizable page title via ?page-title query parameter. (#3116)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph @mho22

+

[v3.0.40] (2026-01-12)

+

Documentation

+
  • [docs] Replace PNG images with WEBP format for improved performance. (#3105)
+

Various

+
  • Document how to publish new npm packages. (#3068)
  • [docs] Updating images from Release page to webp. (#3107)
  • [i18n] Add Bengali translation for contributor-day.md. (#3096)
  • [i18n] Add Bengali translation for translations.md. (#3106)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph @noruzzamans

+

[v3.0.39] (2026-01-07)

+

PHP WebAssembly

+
  • [CLI] Fix \_\_dirname not defined error in intl extension. (#3094)
+

Various

+
  • Gujarati translation: For-plugin-developers documentation. (#3091)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @iamsohilvahora

+

[v3.0.38] (2026-01-06)

+

[v3.0.37] (2026-01-06)

+

PHP WebAssembly

+
  • [PHP] Refactor files following up on split PHP.wasm packages. (#3085)
+

Bug Fixes

+
  • Exclude wordpress-builds/public path in dependabot. (#3088)
+

Various

+
  • Update express dependency to 4.22.0 to fix qs security issue. (#3089)
  • [i18n] Docs: Add Bengali translation for contributor-day-table-lead.md. (#3087)
+

Contributors

+

The following contributors merged PRs in this release:

+

@mho22 @noruzzamans

+

[v3.0.36] (2026-01-05)

+

[v3.0.35] (2025-12-29)

+

PHP WebAssembly

+
  • [PHP] Use platform: "browser" in esbuild configuration for web builds. (#3083)
+

Internal

+
  • [PHP] Remove unnecessary createRequire() banner from the remaining builds. (#3081)
+

Various

+
  • [i18n] Translate code md to bangla. (#3082)
  • [i18n] ja translations developer architecture PHP.js JavaScript module. (#3080)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @noruzzamans @shimotmk

+

[v3.0.34] (2025-12-24)

+

PHP WebAssembly

+
  • [PHP] Enable dynamic-import for published CJS packages. (#3077)
  • [PHP] Remove unnecessary createRequire() from @php-wasm/web build scripts. (#3076)
+

Website

+
  • Add quick navigation popover to address bar. (#3070)
  • Add standalone playground block demo page. (#3071)
+

Internal

+
  • [CI] Extract npm package integration tests to reusable scripts. (#3078)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.33] (2025-12-22)

+

Website

+
  • Add save status indicator to the toolbar. (#3067)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.32] (2025-12-18)

+

PHP WebAssembly

+
  • [PHP] Split php-wasm packages into per-PHP-version packages. (#3062)
+

Website

+
  • Await the iframe load event in playground.goTo(). (#3066)
  • Skip WordPress installation when WordPress files already exist. (#3065)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.31] (2025-12-17)

+

[v3.0.30] (2025-12-17)

+

Documentation

+
  • Rephrase Opcache module injection comments. (#3053)
+

PHP WebAssembly

+
  • [ Intl ] Parallelize memoizedFetch methods when enabling Intl in PHP.wasm web. (#3058)
+

Bug Fixes

+
  • Update package lock files in WordPress builds themes to fix current security issues. (#3057)
+

Contributors

+

The following contributors merged PRs in this release:

+

@mho22

+

[v3.0.29] (2025-12-17)

+

Tools

+
  • Add WordPress Playground DevTools browser extension. (#3056)
+

Website

+
  • Use a kapa.ai widget for blueprint error troubleshooting. (#2987)
+

Internal

+
  • Add CI workflow to build and release the DevTools extension. (#3059)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk

+

[v3.0.28] (2025-12-17)

+

[v3.0.27] (2025-12-16)

+

Internal

+
  • [Meta] Normalize ws package version override in package.json. (#3055)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.26] (2025-12-16)

+

[v3.0.25] (2025-12-16)

+

Website

+
  • Blueprint Editor: Update the URL when typing. (#2959)
+

Bug Fixes

+
  • Fix npm trusted publisher by upgrading to Lerna 9 and npm 11.5.1+. (#3052)
+

Various

+
  • [CI] Fix flaky end-to-end test for blueprint share button. (#3051)
  • [CI] Restore GH_TOKEN for pushing to protected branch. (#3049)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.24] (2025-12-16)

+

Website

+
  • Target temporary Playground in Import ZIP, Import from GitHub. Don't overwrite a saved site. (#2990)
+

Internal

+
  • [CI] Enable trusted publisher-based publishing. (#3048)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.23] (2025-12-16)

+

Enhancements

+
  • Improve variable name and simplify comment in Document-Isolation-Policy rewriter. (#3044)
  • [CLI] Define CLI --flags for each command individually. (#2930)
  • [CLI] Explore spawning new OS processes in CLI spawnProcess. (#3001)
  • [CLI] Readable commands help message. (#2927)
  • [CLI] SinglePHPInstanceManager, spawn OS subprocesses in the spawn handler in Blueprint V2 worker. (#3004)
  • [CLI] Support TERM=dumb. (#2929)
+

Blueprints

+
  • Don't treat extra output during plugin activation as a failure. (#2904)
  • Preserve more error information on failed fetch. (#2946)
  • Support multiline SQL queries in the runSql step. (#2928)
  • Updated runPHPWithOptions example. (#2986)
  • [ Intl ] Implement Intl in blueprints. (#2979)
+

Tools

+
  • Correct issues related to unsupported parameter property in strip-only mode. (#2945)
  • [ xdebug ] Add --experimental-unsafe-ide-integration option in PHP.wasm CLI. (#2947)
+

PHP WebAssembly

+
  • [ Intl ] Implement Intl in Playground CLI. (#3011)
  • [ php-wasm ] Disable profiling data file generation at runtime. (#2998)
  • [PHP] Add php-wasm-cli smoke test for proc_open in CI. (#3013)
  • [PHP] Require explicit spawn handler for process spawning. (#3008)
+

GitHub integration

+
  • Add mho22 to GitHub workflows actors. (#3046)
  • Update Lerna from 6.6.2 to 7.1.3 in order to run Release NPM packages Github Action. (#3038)
  • [Website] Add support for private github repos via git:Directory. (#2856)
+

Blueprints

+
  • [Blueprint Editor] Add multiline string editor modal. (#2962)
  • [Blueprint editor] Blueprint Validation. (#2967)
+

Blueprints Builder

+
  • [Website] Add "Copy link" button to Blueprint editor. (#3029)
+

Website

+
  • [Website] Blueprint bundle editor. (#2942)
+

Documentation

+
  • Removed trailing space contained within link text. (#2911)
  • [Docs] Adding blueprints meta info reference. (#3026)
  • [Docs] Document how to use Playground CLI as a developer. (#2925)
  • [Docs] Move XDebug IDE integration closer to the top, explain the DevTools workflow is highly exploratory. (#2975)
  • [Docs] Updating repository preview info. (#2890)
  • [Docs] Use pull_request_target in the GitHub action PR Preview doc page. (#2915)
  • [docs] Removing GitHub proxy references. (#3009)
  • [docs] Updating resource page. (#3003)
  • [i18n] ja translations developer architecture. (#3000)
+

Experiments

+

GitHub integration

+
  • [ playground-storage ] Add vite-plugin-dts to Playground Storage. (#3035)
+

Website

+
  • [ Vite ] Regroup ignore-*-imports Vite plugin inside a vite-extension. (#2999)
+

File Synchronization

+
  • [Website] fs-journal: Replace recursion with a loop to stop exceeding the call stack. (#2912)
+

PHP WebAssembly

+
  • Add file locking integration tests for php-wasm/node. (#2908)
  • Follow up on PHP 8.5 - Post process with wasm-opt in dynamic extensions. (#3017)
  • PHP 8.5 support. (#2950)
  • Remove custom processManager support in PHPRequestHandler. (#3005)
  • [ Vite ] Regroup preserve-*-loaders-imports Vite plugin inside a vite-extension. (#3002)
  • [ php-wasm ] Add intl dynamic extension to @php-wasm/web. (#2591)
  • [ php-wasm ] Remove static intl extension artifacts. (#2970)
  • [PHP WASM] Transfer ArrayBuffer instead of cloning in PHPResponse serialization. (#3036)
  • [PHP web] Remove runtimes from internal map after initialization to prevent memory leaks. (#3023)
  • [PHP.wasm] Upgrade emscripten version from 4.0.5 to 4.0.19. (#2910)
  • [PHP] Move setImmediate polyfill to loadWebRuntime. (#3024)
  • [PHP] Upgrade GD to 2.3.3. (#2944)
+

Website

+
  • Blueprint editor. (#2815)
  • Correct out of memory issue. (#3021)
  • Enforce HTTPS in fetchWithCorsProxy(). (#2901)
  • Rewrite COEP/COOP headers as Document-Isolation-Policy in supporting browsers. (#3028)
  • Deprecate github-proxy.com with automatic migration to native resources. (#3007)
  • Improve error reporting. (#2874)
  • Move dynamic extension files in assets/extensions directory. (#2984)
  • MySQL admin tool improvements. (#2971)
  • Prevent Query API defaults from overriding login info provided by the Blueprint. (#2871)
  • Replace WordPress nightly with trunk. (#2916)
  • Saved Playgrounds overlay redesign. (#2985)
  • Stop CSP frame-ancestors from breaking embedded Playgrounds. (#2980)
  • Updating Run Blueprint button. (#2953)
  • [Analytics] Track install and error events. (#1984)
  • [Blueprints] Detect network firewall interference during requests. (#3031)
+

Blueprints

+
  • Rewrite scoped URLs when importing a Playground export. (#2989)
+

Internal

+
  • Add .orig and .rej files to .gitignore for patching leftovers. (#2981)
  • Disable nx cache. (#2941)
  • Inject Playground commit ID to the built index.html. (#2918)
  • [CI] Explore fixing two notoriously flaky tests. (#2935)
  • [CI] Fix flaky API documentation end-to-end test. (#2963)
  • [CI] Preserve artifacts from failed API documentation end-to-end tests. (#2960)
  • [CI] Rebalance unit test groups. (#2933)
  • [CI] Reduce CLI log output in CI jobs. (#2934)
  • [CI] Speed up end-to-end tests. (#2961)
  • [CI] Stabilize flaky CI tests. (#2931)
  • [Website] Fix flaky phpMyAdmin test. (#2977)
+

Bug Fixes

+
  • Fix SQLite plugin logging to respect skip option. (#2924)
  • Fix runPHPWithOptions demo. (#2978)
  • [Docs] Fix API reference. (#2905)
  • [Docs] Fix documentation site build failures. (#2913)
+

###

+
  • Xdebug ] Relocate xdebug into shared library directory. (#3045)
+

Various

+
  • Add SQLITE_ENABLE_COLUMN_METADATA and update SQLite. (#2948)
  • Add file locking tests for Playground CLI. (#2920)
  • Add non-blocking F_SETLKW based on F_SETLK. (#2972)
  • [Blueprints] Add dispose functions in afterEach hooks in tests. (#2921)
  • [Docs] Updating the resource page and adding new playground videos. (#2914)
  • [Storage] Fix fileExists() to return true for directories. (#2968)
  • [Storage] Require explicit recursive flag for mkdir (and tweak the semantics of writeFile and listFiles). (#2969)
  • [Website] Database panel with Adminer & phpMyAdmin. (#2926)
  • [i18n] Add contributor day leadership guide in Portuguese. (#2995)
  • [i18n] complete pt_br translation of blueprints documentation. (#3015)
  • [i18n] ja translations developer architecture WebAssembly PHP and Compiling PHP. (#3033)
  • i18n: Full Translation of "For Plugin Developers" to Spanish. (#2900)
  • i18n: Minor fixes on resources.md Spanish translation. (#2898)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @andr3ribeiro @bgrgicak @brandonpayton @epeicher @fellyph @JanJakes @jeffpaul @mho22 @shimotmk @SirLouen @Utsav-Ladani @wojtekn

+

[v3.0.22] (2025-11-17)

+

Enhancements

+

Boot Flow

+
  • [Boot] Verify permalink structure is actually set. (#2902)
+

Blueprints

+
  • V1] Rewrite github.com/owner/repo/raw URLs. (#2892)
+

Documentation

+
  • Document the new GitHub Preview button action. (#2893)
  • [Docs] Adding link at the documentation sidebar for PR preview link page. (#2895)
  • [Docs] Documentation Expansion for php-wasm/node. (#2780)
  • [Docs] Updating sidebar to add Xdebug pages. (#2881)
+

PHP WebAssembly

+
  • Try avoiding URL.canParse for older version of Safari. (#2887)
+

Website

+
  • Remove "preview WordPress core branch" feature. (#2894)
  • Support previewing WordPress and Gutenberg branches, not just PRs. (#2868)
+

Bug Fixes

+
  • [CLI] Fix null and "latest" WP version resolution and improve unzip error message. (#2889)
  • [CLI] Fix run-cli leak which was revealed by repeated runCLI() calls during test. (#2888)
+

###

+
  • CLI] Allow API consumers to rely upon option validation and default values. (#2883)
+

Various

+
  • Minor stylistic and punctuation improvements. (#2884)
  • Revise error messages and coding guidelines. (#2879)
  • Update footer labels in localization file. (#2878)
  • [i18n] Add Japanese translations to Blueprints JSON and the API Client and Mount data. (#2882)
  • [i18n] Adding Italian translations. (#2865)
  • [i18n] Create contributor-day-table-lead.md for Gujarati. (#2866)
  • i18n: Full Translation of "Build" to Spanish. (#2906)
  • i18n: Minor fixes on web-instance.md Spanish translation. (#2899)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph @mehrazmorshed @praful2111 @shimotmk @SirLouen @Successfulsebunya

+

[v3.0.21] (2025-11-10)

+

Bug Fixes

+
  • Docs: Fix grammar, typos, and formatting issues across documentation. (#2877)
  • Docs: Fix typo in resources.md. (#2876)
  • docs: Fix MDN link for Access-Control-Allow-Origin header. (#2875)
+

Various

+
  • [Docs] Adding ask AI Button. (#2858)
  • [i18n] Add Japanese translations to Blueprints JSON and the API Client. (#2873)
+

Contributors

+

The following contributors merged PRs in this release:

+

@fellyph @hmbashar @huzaifaalmesbah @shimotmk

+

[v3.0.20] (2025-11-06)

+

Enhancements

+
  • [CLI] Add --wordpress-install-mode flag. (#2803)
+

Tools

+

PHP WebAssembly

+
  • [PHP.wasm] Major overhaul of URL rewriting and setting $\_SERVER variables. (#2864)
+

PHP WebAssembly

+
  • [PHP.wasm] ImageMagick extension. (#2834)
+

Bug Fixes

+
  • [CLI] Make messaging clearer for errors and Xdebug IDE integration. (#2869)
+

Various

+
  • [Docs] Add xdebug testing page. (#2840)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph

+

[v3.0.19] (2025-11-04)

+

Enhancements

+
  • [CLI] Support .0 versions, e.g. 6.4.0. (#2848)
+

Documentation

+
  • [Docs] Remove kapa AI button. (#2849)
+

PHP WebAssembly

+
  • Fix unmount of nested mounts in PHP runtime hotswap. (#2859)
+

Website

+
  • Controlled iframe for the latest Guteneberg version. (#2857)
  • [TCP Proxy] Produce the correct request path in parseHttpRequest(). (#2852)
+

Bug Fixes

+
  • [CLI] Avoid breaks during Playground boot when --xdebug enabled. (#2835)
  • [CLI] Fix incorrect Xdebug mappings for absolute host paths. (#2860)
+

Various

+
  • Translate to bangla in contributing index file. (#2851)
  • [i18n] Add Japanese translations to Playground API Client. (#2854)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph @noruzzamans @shimotmk

+

[v3.0.18] (2025-10-31)

+

PHP WebAssembly

+
  • Remove old, unused .wasm files from @php-wasm/web. (#2847)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.0.17] (2025-10-31)

+

PHP WebAssembly

+
  • Remove old, unused php-wasm .wasm files. (#2846)
+

Website

+
  • Remove client package from the list of offline mode assets. (#2841)
+

Bug Fixes

+
  • [CLI] Fix temp dir cleanup when Playground CLI server is killed. (#2836)
+

Various

+
  • Translate contributor-badge page to bangla. (#2843)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton @noruzzamans

+

[v3.0.16] (2025-10-31)

+

Enhancements

+
  • [ xdebug ] Add --experimental-unsafe-ide-integration option in Playground CLI. (#2777)
+

Tools

+

PHP WebAssembly

+
  • Add support for AVIF in GD. (#2814)
+

Documentation

+
  • [Docs] Adding data persistence information. (#2798)
  • [i18n] Adding cli flags to Portuguese and Spanish. (#2829)
+

PHP WebAssembly

+
  • [PHP] SOAP extension. (#2832)
+

Website

+
  • Make saved sites sidebar more narrow. (#2826)
  • Add refresh button to the left of address bar. (#2828)
  • Wider site info on smaller breakpoints. (#2830)
+

Various

+
  • Translate documentation content to Bangla language. (#2839)
  • [Docs] Updating CLI flags list. (#2812)
  • [i18n] Adding Luganda structure. (#2774)
  • [i18n] Create contributor-day.md for Gujarati. (#2791)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @Dhruval-678 @fellyph @mho22 @noruzzamans

+

[v3.0.15] (2025-10-27)

+

Tools

+

Import/Export

+
  • [Blueprints] Use \_SERVER['HTTPS'] in the import step. (#2802)
+

Website

+
  • Add Playground logo and 'import' menu to the sidebar. (#2806)
  • Ask for a Playground name before saving. (#2768)
  • File browser and code editor. (#2813)
  • Move the sidebar icon to the right. (#2811)
  • Refresh button icons next to the browser bar. (#2807)
  • Resizable sidebar. (#2809)
  • Restore the visible button selection in the sidebar. (#2804)
  • Retain address bar when opening the sidebar. (#2808)
+

Various

+
  • [i18n] Add Japanese translations to remote.html vs index.html. (#2817)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @shimotmk

+

[v3.0.14] (2025-10-21)

+

Various

+
  • [i18n] Add Japanese translations to JavaScript API. (#2800)
+

Contributors

+

The following contributors merged PRs in this release:

+

@shimotmk

+

[v3.0.13] (2025-10-20)

+

Enhancements

+
  • Playground CLI: Print temp dir and mounts when --verbosity=debug. (#2799)
+

Blueprints

+
  • Support creating a local .git directory via git:Directory resource. (#2787)
  • ensure git:Directory resource returns non-empty-name. (#2779)
+

Documentation

+
  • [Docs] Adding table lead guide documentation. (#2708)
  • [docs] Removing deprecated run method reference. (#2778)
  • [i18n] Updating translation guide for Portuguese and Spanish. (#2773)
+

Internal

+
  • Document the rationale for setting php.ini values in wordpress/src/boot.ts. (#2784)
+

Various

+
  • Add some improvements in the Spanish translations. (#2788)
  • [i18n] Add Japanese translations to Query API. (#2781)
  • [i18n] Adding French translation to guides/index.md. (#2790)
  • [i18n] Adding quick start guide and web instance pages in Spanish. (#2785)
  • [i18n] Fixing typos in French translation of documentation.md. (#2792)
  • [i18n] Updating Contributor badge and Contributor day pages. (#2782)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @amieiro @beryl-dlg @brandonpayton @fellyph @shimotmk

+

[v3.0.12] (2025-10-13)

+

Internal

+
  • [CI] Remove a few predefined runner files before releasing npm packages. (#2775)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.11] (2025-10-13)

+

[v3.0.10] (2025-10-13)

+

Enhancements

+
  • Update form-data npm dependency via package.json overrides. (#2761)
  • Update sha to 2.4.12. (#2729)
  • Update tmp package to the latest version. (#2730)
  • [XDebug Bridge] Read files from VFS when a PHP instance is provided. (#2722)
+

Blueprints

+
  • Accept branch names and tags in git:Directory resource. (#2760)
+

Tools

+
  • [CLI] Respond with HTTP 500 response when the request handler throws an error. (#2715)
+

Documentation

+
  • Add docblock for createInvertedReadableStream. (#2726)
  • Adding Kapa AI script tag. (#2727)
  • [Docs] Updating resources page. (#2771)
  • [i18n] Adding Bengali Structure. (#2754)
+

PHP WebAssembly

+
  • [ xdebug ] Configure xdebug for phpstorm compatibility. (#2747)
+

Website

+
  • Adding new icons to Playground web instance. (#2696)
  • Allow remote.html from same origin as Playground client script. (#2765)
  • Make deployment script more usable for self-hosting. (#2764)
+

Internal

+
  • Add Dependabot configuration for npm updates. (#2733)
  • [Meta] Fix package-lock.json after dependabot. (#2745)
+

Bug Fixes

+
  • Fixing old documentation regarding PHP code examples. (#2721)
  • [i18n] Fix issue related to link in french translation. (#2748)
+

Various

+
  • Deploy web app less often to reduce cache invalidation. (#2762)
  • [Meta] Fix package-lock.json after dependabot. (#2746)
  • [i18n] Add Japanese translations to APIs overview. (#2770)
  • [i18n] Add translation to page title in resources.md. (#2728)
  • [i18n] Adding French translation to intro.md. (#2724)
  • [i18n] Fixing typos in French translation quick-start-guide.md. (#2725)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @brandonpayton @fellyph @mho22 @shimotmk @wojtekn @zaerl

+

[v3.0.9] (2025-10-06)

+

Tools

+
  • Fix local package repository command running issue. (#2720)
+

Various

+
  • [i18n] Added Gujarati Translation for Local Development 02-vscode-extension.md File. (#2718)
  • [i18n] Added Gujarati Translation for Local Development 03-php-wasm-node File. (#2719)
  • docs: Add browser support information to limitations documentation. (#2711)
+

Contributors

+

The following contributors merged PRs in this release:

+

@getdave @mho22 @shail-mehta

+

[v3.0.8] (2025-10-02)

+

Documentation

+
  • [i18n] Added Gujarati Translation for Documentation Contributions. (#2610)
+

Website

+
  • [PHP Playground] Attach client to https://playground.wordpress.net/remote.html. (#2717)
+

Internal

+
  • Add name to Playground Website and Website extras cli packages. (#2716)
+

Various

+
  • [i18n] Fixing typos in French translation of quick-start-guide.md. (#2712)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @dilipom13

+

[v3.0.7] (2025-10-01)

+

Tools

+

PHP WebAssembly

+
  • [PHP] Add "ls" and "pwd" CLI commands. (#2701)
+

Documentation

+
  • Revert Quick guide to the English version. (#2709)
  • [i18n] Add French translation for quick-start-guide.md. (#2710)
+

PHP WebAssembly

+
  • Preserve chroot across all worker-managed PHP instances. (#2704)
  • [PHP] Allow removing CWD during runtime rotation. (#2714)
  • [PHP] Do not reap() PHP in the worker until the streaming response ends. (#2703)
  • [PHP] Move registerWorkerListeners() from a specific worker to the parent PHPWorker. (#2705)
  • [PHP] Support subprocesses in cli() calls. (#2702)
+

Website

+
  • IDE-like PHP playground. (#2699)
+

Internal

+
  • [PHP utils] Export splitShellCommand. (#2706)
+

Bug Fixes

+
  • CORS proxy: Fix custom origin validation during deployment. (#2698)
+

Various

+
  • [i18] Add French translation for launch.md. (#2697)
  • [i18n] Add French translation for quick-start-guide.md. (#2692)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @brandonpayton @fellyph

+

[v3.0.6] (2025-09-29)

+

Documentation

+
  • [i18n] Add French translation for resources.md. (#2680)
+

Website

+
  • [Client] Enable calling playground.runStream() and .cli() from the client. (#2688)
+

Various

+
  • Update Playground JS API tutorial Link. (#2685)
  • [i18n] Add Japanese translations to Playground CLI. (#2683)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @jdahir0789 @shimotmk

+

[v3.0.5] (2025-09-25)

+

Bug Fixes

+
  • Playground CLI: Log unhandled rejections and stop them from crashing workers. (#2682)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v3.0.4] (2025-09-25)

+

Experiments

+

GitHub integration

+
  • [CLI] Polyfill the Buffer class without making it an empty object in CLI. (#2681)
+

PHP WebAssembly

+

Website

+
  • [Website] Disable curl_share_init by default (to make Composer work). (#2679)
+

Website

+
  • Resolve the Blueprint declaration for the 'View Blueprint' button. (#2675)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.3] (2025-09-23)

+

Blueprints

+
  • Replace randomString() with randomFilename() in installAsset(). (#2677)
+

Documentation

+
  • [Docs] Adding steps to translate documentation with GitHub UI. (#2666)
  • [i18n] Add French translation for documentation.md. (#2670)
  • [i18n] Adding Architecture page to Brazilian Portuguese. (#2667)
+

PHP WebAssembly

+
  • [PHP Worker] listen to all PHP instances events via worker.addEventListener(). (#2673)
+

Website

+

Blueprints

+
  • Flatten the stored runtime configuration format. (#2671)
  • Report Blueprint v2 progress. (#2674)
  • [Blueprints] Separate computing the runtime configuration from compiling a Blueprint. (#2672)
+

Various

+
  • [i18n] Add Japanese translations to VS Code extension. (#2668)
  • [i18n] Add Japanese translations to php-wasm/node. (#2669)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @beryl-dlg @fellyph @shimotmk

+

[v3.0.2] (2025-09-22)

+

Blueprints

+
  • [Website] Split Playground remote initialization logic into Blueprint-version specific workers. (#2652)
+

Documentation

+
  • [i18n] Added Gujarati Translation for Local Development 01-wp-now.md file. (#2664)
+

Website

+

Blueprints

+
  • Add Blueprint v2 handlers (noop). (#2657)
  • Declare the correct Blueprints v2 types. (#2655)
  • Isolate resolveBlueprintFromURL() calls. (#2654)
  • [Client] Expose Blueprints v2 runner via a feature flag. (#2658)
+

Various

+
  • [i18n] Added Missing Description in Intro and Quick Start Guide Pages for Gujarati Language. (#2660)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @shail-mehta

+

[v3.0.1] (2025-09-19)

+

Blueprints

+
  • [Client] Explicit Blueprints v1 handler. (#2651)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v3.0.0] (2025-09-19)

+

Breaking Changes

+

Blueprints

+
  • [Blueprints] Rename Blueprints v1 types, add Blueprint v2 types. (#2648)
+

Blueprints

+
  • Move Blueprints v1-specific files to v1 subdirectory. (#2644)
  • Rename BlueprintDeclaration to BlueprintV1Declaration. (#2645)
  • V1] Use the wordpress-importer plugin for the importWxr step. (#2640)
+

Documentation

+
  • [i18n] Added Gujarati Translation for 01 What are Blueprints and What you can do with them File. (#2617)
  • [i18n] Added Gujarati Translation for Local Development Intro.md file. (#2623)
  • [i18n] Tagalog translations for using blueprints page. (#2628)
  • [i18n] Tagalog translations of API Consistency. (#2629)
  • [i18n] Tagalog version of Blueprints/Steps/Shorthands. (#2630)
+

Experiments

+

PHP WebAssembly

+
  • Playground CLI: Mount /wordpress, /internal, and /tmp dirs within real temporary dir. (#2446)
+

PHP WebAssembly

+
  • Function mismatch fix in GD jpeg extension for PHP below 8.0. (#2634)
  • [PHP] Add unit tests for nested mounts. (#2639)
+

Website

+
  • [WordPress] Separate bootWordPress() from bootRequestHandler(). (#2650)
+

Blueprints

+
  • [Blueprints] Log step names without parsing. (#2649)
+

Bug Fixes

+
  • [Xdebug Bridge] Fix issue if non existent file is read. (#2625)
+

Reliability

+
  • Fix Playground CLI boot from native dirs on Windows. (#2642)
+

Various

+
  • Keep wordpress-importer.zip for older versions of Playground. (#2647)
  • Update build.md. (#2638)
  • [Documentation] Adding troubleshooting sections for WP-CLI database connections. (#2333)
  • [i18n] Add Japanese translations to wp-now NPM package. (#2615)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akkspros @brandonpayton @fellyph @mho22 @rollybueno @shail-mehta @shimotmk

+

[v2.0.22] (2025-09-16)

+

Enhancements

+
  • Statically analyzable build. (#2632)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v2.0.21] (2025-09-15)

+

Enhancements

+
  • [CLI] Build worker thread with stable filenames. (#2631)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v2.0.20] (2025-09-15)

+

Tools

+

Blueprints

+
  • Fix to ensure that Site Editor templates are associated with the correct taxonomy upon import. (#2584)
+

PHP WebAssembly

+
  • Translate 'localhost' to 127.0.0.1 in MySQL connections. (#2627)
  • [PHP] Rebuild with sync fd_close on the web. (#2620)
+

Website

+
  • [Web Client] Remove onBeforeBlueprint. (#2622)
+

Internal

+
  • [CI] Do not block CI tests on linter. (#2619)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk

+

[v2.0.19] (2025-09-11)

+

PHP WebAssembly

+
  • [Intl] Correct intl errors during compilation and build. (#2613)
+

Bug Fixes

+
  • Playground CLI: Skip WP install when using existing WP files. (#2616)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @mho22

+

[v2.0.18] (2025-09-08)

+

Documentation

+
  • Added Gujarati Translation for Code.md File. (#2606)
  • Tagalog translations of Blueprints -&gt; Blueprint Data Format. (#2609)
  • [Translations] Adding local environment section to pt-BR. (#2572)
+

Bug Fixes

+
  • Fixing header from Gujarati translation. (#2614)
  • [Xdebug Bridge] Fix create hash error in xdebug bridge. (#2612)
+

Contributors

+

The following contributors merged PRs in this release:

+

@fellyph @mho22 @rollybueno @shail-mehta

+

[v2.0.17] (2025-09-08)

+

Documentation

+
  • Add Japanese translations to Local Development. (#2604)
+

Various

+
  • Added Gujarati Translation for Blueprints Tutorials Index.md file. (#2607)
  • Added Gujarati Translation for How to Run Blueprints. (#2611)
+

Contributors

+

The following contributors merged PRs in this release:

+

@shail-mehta @shimotmk

+

[v2.0.16] (2025-09-04)

+

Enhancements

+
  • Add structured issue templates for bugs, enhancements, and documentation. (#2571)
  • Allow installing multiple themes via URL, as required by parent/child themes. (#2581)
+

Blueprints

+
  • Move blueprints.phar to the Blueprints package. (#2471)
  • Move runBlueprintV2 to the blueprints package. (#2594)
+

Tools

+
  • [XDebug Bridge] Highlight syntax of php scripts from mime type in Devtools. (#2566)
  • [XDebug Bridge] Load files in Devtools before running PHP with Xdebug enabled. (#2527)
+

Documentation

+
  • Added Gujarati Translation for Index.md File. (#2576)
  • Added Gujarati Translation for JSON API and Function API File. (#2577)
  • Adding french translation guide. (#2541)
  • Adding more internal links between pages. (#2499)
  • Adding reference to multiple theme URL parameter. (#2593)
  • Adding runCLI section to the Playground CLI page. (#2583)
  • Updating runCLI demo at wp-playground/cli README file. (#2553)
  • Updating wp versions blueprints. (#2573)
  • [Docs] Adding how to contribute to the WordPress Playground. (#2597)
+

PHP WebAssembly

+
  • Increase file locking safety. (#2506)
  • [ php-wasm ] Add intl dynamic extension to @php-wasm/node ASYNCIFY #2501. (#2557)
  • [PHP] Expose php.cli() on the web. (#2590)
  • [PHP] Include CLI SAPI in the web PHP.wasm build. (#2589)
  • [PHP] Inline rotatePHPRuntime() into the PHP class. (#2559)
  • [PHP] Rotate the spawn handler in hotSwapPHPRuntime(). (#2588)
+

Website

+
  • A specific error when a GitHub artifact is not found. (#2596)
  • Apply base URLs to relative redirection URLs. (#2595)
+

Various

+
  • Add Japanese translations to Quick Start Guide for Developers. (#2587)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @dd32 @fellyph @mho22 @shail-mehta @shimotmk

+

[v2.0.15] (2025-09-01)

+

Documentation

+
  • Added Gujarati Translation for intro-devs.md file. (#2574)
+

Experiments

+

File Synchronization

+
  • [Website] Renaming stored Playgrounds. (#2486)
+

Bug Fixes

+
  • Fix error from adding blank target to external links. (#2575)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @draganescu @shail-mehta

+

[v2.0.14] (2025-08-29)

+

PHP WebAssembly

+
  • Add test to verify mount() correctly handles files (closes #503). (#2564)
  • Use unique tmp.zip filename in unzipFile() to avoid conflicts in async calls. (#2567)
  • [ php-wasm ] Add intl dynamic extension to @php-wasm/node JSPI. (#2501)
  • [WordPress][CLI] Allow requesting internal URLs via http_request_host_is_external. (#2569)
+

Various

+
  • Tagalog translations of Blueprints -&gt; Tutorial -> Build Your 1st Blueprint. (#2546)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @jnealey88 @mho22 @rollybueno

+

[v2.0.13] (2025-08-26)

+

Enhancements

+
  • [CLI] --site-url option for Playground CLI. (#2558)
+

Tools

+
  • [XDebug Bridge] Fetch all array keys when inspecting an array. (#2409)
+

PHP WebAssembly

+
  • [PHP web] Export setErrNo() to make less work as pager. (#2554)
+

Website

+
  • [Web] tolerate empty e.target in addTargetBlankToExternalLinks. (#2555)
+

Bug Fixes

+
  • Playground CLI: Wire up execution modes for Blueprints v2. (#2519)
+

Reliability

+
  • [php-wasm-logger] Filter logs by severity in Logger and assign severity based on verbosity argument in CLIs. (#2436)
+

Various

+
  • Added Gujarati Translation for Index.md file. (#2550)
  • Use SQLite AST driver also with Blueprints v2. (#2538)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @JanJakes @mho22 @shail-mehta

+

[v2.0.12] (2025-08-25)

+

Enhancements

+
  • Playground CLI: Support --auto-mount=path option. (#2525)
+

Documentation

+
  • Added Gujarati Translation for Contributor Badge File. (#2549)
  • Added Gujarati Translation for coding-standards.md file. (#2507)
  • Japanese translations: Blueprints Unifying assets folder. (#2536)
  • Updating Translation Documentation Page. (#2534)
+

Various

+
  • Add Japanese translations to WordPress Playground Developers documentation. (#2551)
  • Add Japanese translations to WordPress Playground badge. (#2545)
  • Added Gujarati translation for about, build, test, launch pages. (#2533)
  • Added Original Comment and Description in Launch.md file. (#2542)
  • Tagalog translations of Blueprints -&gt; Getting Started. (#2547)
+

Contributors

+

The following contributors merged PRs in this release:

+

@aslamdoctor @brandonpayton @fellyph @rollybueno @sandipr942 @shail-mehta @shimotmk

+

[v2.0.11] (2025-08-21)

+

Tools

+

Blueprints

+
  • [Blueprints] Use the local worker in Builder in development mode. (#2495)
+

Documentation

+
  • Adding blueprints documentation description. (#2524)
+

PHP WebAssembly

+
  • Fix corrupt zip download from Site Editor export. (#2531)
+

Bug Fixes

+
  • Fix wrong license page within the languages es, pt-BR and ja. (#2483)
+

Various

+
  • Add Japanese translations to Build your first Blueprint. (#2529)
  • Add Japanese translations to How to run Blueprints. (#2526)
  • Added Gujarati Translation for web-instance.md file. (#2532)
  • Unifying assets folder. (#2521)
+

Contributors

+

The following contributors merged PRs in this release:

+

@aslamdoctor @brandonpayton @fellyph @josevarghese @mho22 @shimotmk

+

[v2.0.10] (2025-08-18)

+

Documentation

+
  • Add Japanese translations to Blueprints 101 and What are Blueprints?. (#2511)
  • Adding the documentation meta description to the main folder. (#2504)
  • Translating fragments documentation and adding Contributor badge page. (#2503)
  • Add GitDirectoryReference resource documentation. (#2492)
+

PHP WebAssembly

+
  • Re-enable and fix native file locking tests. (#2505)
+

Website

+

Documentation

+
  • Fix customize bundle instructions in "Host Own Playground" documentation. (#2510)
+

Bug Fixes

+
  • Fix: "referrences" should be "references". (#2514)
+

Various

+
  • Add Japanese documentation meta description to the main folder. (#2518)
  • Add Japanese translations to Introduction. (#2489)
  • Add docs-description blueprints tutorial and What are Blueprints?. (#2512)
  • Added Gujarati Translation for Launch.md file. (#2480)
  • Added Gujarati Translation for quick-start-guide.md. (#2494)
  • Adding Contributor Badge page at the documentation. (#2491)
  • Tagalog translations of Blueprints -&gt; Tutorial -> What are Blueprints?. (#2520)
  • Translation: Blueprints -&gt; Tutorial -> How to run Blueprints. (#2522)
  • Updated Typos in contributor-badge.md File. (#2493)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @fellyph @juanmaguitar @mukeshpanchal27 @ravigadhiya007 @rollybueno @shail-mehta @shimotmk

+

[v2.0.9] (2025-08-11)

+

Breaking Changes

+
  • [Website] Default demo content. (#2412)
+

Enhancements

+
  • [PHP Playground] Select WordPress version. (#2472)
+

Blueprints

+
  • [WordPress] Support auto-login with customize.php as a landing page. (#2467)
+

Documentation

+
  • Tagalog: Add translations for Blueprints Tutorial. (#2477)
  • Tagalog: Translations of Blueprints documentation page. (#2476)
+

Website

+
  • Open external links in a new tab/window. (#2468)
+

Internal

+
  • Skip flaky end-to-end tests. (#2475)
+

Various

+
  • Add Japanese translations to Blueprint Examples and Troubleshoot and debug. (#2474)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @rollybueno @shimotmk @zaerl

+

[v2.0.8] (2025-08-07)

+

Blueprints

+
  • Fallback to URL-based file name when fetching remote ZIP files. (#2470)
+

Documentation

+
  • [Docs] Adding Resources, Web instance, and guides pages on Brazilian Portuguese. (#2351)
  • [Docs] Enabling language switcher. (#2465)
+

PHP WebAssembly

+
  • Fix resolving mounted symlinks in secondary PHP instances. (#2444)
  • [XDebug Bridge] List additional ASYNCIFY_ONLY functions to prevent unreachable crashes when using Devtools. (#2454)
+

Website

+
  • [Browser] Do not use the Buffer class in web browsers. (#2469)
  • Add PHP Playground. (#2463)
  • Suppress PHP warnings when pre-fetching WordPress updates. (#2458)
+

Bug Fixes

+
  • Fix invalid filename "&lt;7.4" on Windows. (#2461)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph @JanJakes @mho22

+

[v2.0.7] (2025-08-05)

+

Tools

+
  • [ CLI ] Rename CLI binaries in @php-wasm/cli and @wp-playground/cli. (#2441)
+

Documentation

+
  • Updating Docusaurus version from 3.7 to 3.8. (#2457)
  • [Docs] Adding fixes to broken URLs. (#2451)
  • [Docs] Bump PHP version to avoid WordPress PHP version Warning. (#2443)
+

PHP WebAssembly

+
  • Patch the premature "request in progress" semaphore release. (#2455)
+

Bug Fixes

+
  • Re-enable Playground CLI tests. (#2445)
+

Various

+
  • Add check for SQLite driver missing in target folder. (#2440)
  • Adding CLI reference to Playground README. (#2433)
  • Adding Gujarati Intro documentation. (#2450)
  • Bump WordPress old version demo to version 6.2.1. (#2460)
  • Removing blog references on Docusaurus. (#2456)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph @mho22 @nikunj8866 @zaerl

+

[v2.0.6] (2025-08-04)

+

Documentation

+
  • Adding Contribution pages Spanish translation. (#2431)
+

PHP WebAssembly

+
  • Fix file locking for PROXYFS nodes that wrap NODEFS. (#2437)
+

Bug Fixes

+
  • Translations: Fix command typo in docs. (#2449)
+

Various

+
  • Add Japanese translations to Blueprint Bundles and API Consistency. (#2438)
  • Translations: Clean up version from PR #2336. (#2448)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @fellyph @rollybueno @shimotmk @vipul0425

+

[v2.0.5] (2025-07-28)

+

Bug Fixes

+
  • Fix fcntl() F_GETLK fatal due to undefined flock struct address. (#2432)
+

Various

+
  • Add Japanese translations to contributing index and sidebar. (#2434)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @shimotmk

+

[v2.0.4] (2025-07-25)

+

Public API

+

Blueprints

+
  • Distribute @wp-playground/client without any package.json dependencies. (#2426)
+

Tools

+
  • Fix ESLint 9 linting in VSCode. (#2417)
  • [ xdebug ] Add --experimental-devtools option in Playground CLI. (#2411)
+

PHP WebAssembly

+
  • [PHP] Dispatch request.error for all non-zero-exit request handler errors. (#2429)
+

Website

+
  • Query Monitor plugin support. (#2415)
+

Internal

+
  • Skip flaky end-to-end tests in Firefox and Webkit. (#2425)
+

Bug Fixes

+
  • [Xdebug Bridge] Correct error related to unresolved promises in bridge. (#2422)
+

Various

+
  • Documentation add sidebar to blueprints bundles. (#2397)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @mho22 @shimotmk

+

[v2.0.3] (2025-07-24)

+

Tools

+
  • [ xdebug ] Add --experimental-devtools option in php-wasm CLI. (#2408)
+

Bug Fixes

+
  • Playground CLI Allow /wordpress subdirs to be mounted before WP install. (#2382)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @mho22

+

[v2.0.2] (2025-07-23)

+

Tools

+

PHP WebAssembly

+
  • [ xdebug ] Bridge DBGP session with CDP server. (#2402)
+

Internal

+
  • [Build] Preserve optionalDependencies in built package.json. (#2410)
+

###

+
  • Comlink] Throw the original error in the error handler. (#2407)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v2.0.1] (2025-07-23)

+

Blueprints

+
  • Rewrite paths in the wp-cli step. Improve error reporting. (#2406)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v2.0.0] (2025-07-23)

+

Enhancements

+
  • [Playground CLI] Improve error reporting. (#2401)
  • [Playground CLI] Kebab-case yargs options declarations. (#2399)
+

Blueprints

+
  • Expose Blueprints v2 runner in Playground CLI. (#2394)
  • Extract Blueprint v1-specific parts of Playground CLI. (#2392)
  • [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. (#2396)
+

Tools

+
  • [XDebug] Add a mock @php-wasm/xdebug-bridge package. (#2398)
+

Documentation

+
  • Adding Brazilian Portuguese translation for developer documentation. (#2391)
+

Website

+
  • [Remote] Use CORS proxy in embedded Playgrounds. (#2369)
+

Bug Fixes

+
  • CLI: Fix --login option and "landingPage" Blueprint property. (#2344)
+

Various

+
  • Add Japanese translations to steps and steps shorthands. (#2386)
  • Add OPCache support. (#2400)
  • [Node] Gracefully handle connection errors in the outbound network proxy. (#2370)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @fellyph @shimotmk @zaerl

+

[v1.2.3] (2025-07-21)

+

Enhancements

+
  • [Playground CLI] Consolidate auto mounting logic. (#2360)
  • [Playground CLI] Move mounting code to mount.ts. (#2362)
+

Blueprints

+
  • [CLI] Move Blueprints v2 to Playground CLI package. (#2364)
+

Public API

+

Blueprints

+
  • [Client] Accept wasm.wordpress.net as an official origin. (#2368)
+

Tools

+
  • Make PHP 8.3 the default version. (#2371)
+

PHP WebAssembly

+
  • Add --xdebug option in php-wasm CLI and wp-playground CLI. (#2346)
+

Documentation

+
  • Adding Playground CLI page and removing wp-now references. (#2337)
  • Adding pt-br About and Launch Page. (#2358)
  • Adding three new flags on the CLI README file. (#2325)
  • Adding video content in Japanese to resources page. (#2354)
  • Updating web instance page documentation. (#2365)
+

PHP WebAssembly

+
  • [PHP-wasm Node] Remove unused node creation code from createNodeFsMountHandler. (#2379)
  • [PHP-wasm] File mounting in NODEFS. (#2338)
  • [PHP] Improve error logging. (#2357)
  • [PHP] Isomorphic, reusable spawn handler. (#2359)
  • [PHP] Refresh the latest PHP versions before recompiling. (#2372)
  • [php-wasm/universal] Try require() before dynamic imprt in comlink-sync.ts. (#2363)
+

Website

+
  • Deploy public web app after WP major/beta update. (#2378)
+

Bug Fixes

+
  • Allow the WP update and changelog workflows to commit to trunk again. (#2377)
  • Fix failing WP update workflows. (#2376)
+

Various

+
  • Add Japanese translations to Resources References. (#2352)
  • Add new logo and open graph image. (#2350)
  • Adding Portuguese version for Code Standards, Code, and Documentation.. (#2343)
  • Adding new icons and og:Image for the Playground Web instance. (#2367)
  • Update Japanese translations to main directory. (#2375)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @fellyph @mho22 @shimotmk

+

[v1.2.2] (2025-07-14)

+

Enhancements

+
  • Add --internal-cookie-store option for Playground CLI. (#2323)
+

Tools

+

PHP WebAssembly

+
  • [ php-wasm ] Add xdebug shared extension to @php-wasm/node ASYNCIFY. (#2326)
+

Documentation

+
  • Add Japanese translations to Using Blueprints. (#2330)
  • Add Japanese translations to Blueprint data Format. (#2340)
  • Adding new videos about WordPress Playground. (#2348)
  • Translate How to contribute pages to Brazilian Portuguese. (#2329)
  • Updating Translation Guide. (#2342)
  • Updating slack channel from #meta-playground to #playground. (#2345)
+

PHP WebAssembly

+
  • Support multiple workers for NODEFS /wordpress mounts – Asyncify. (#2317)
  • [PHP] Support non-blocking read streams. (#2339)
+

Bug Fixes

+
  • Fix: Set an explicit path for docsaurus.config.js. (#2335)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @fellyph @mho22 @rollybueno @shimotmk

+

[v1.0.38] (2025-05-22)

+

Various

+
  • Revert "[ php-wasm ] add Intl support (#150)". (#154)
  • Use the new SQLite driver. (#144)
  • [ php-wasm ] Add intl support. (#155)
  • [ php-wasm ] Intl : Improve integration. (#159)
  • [ php-wasm ] add Intl support. (#150)
  • [CLI] Enable users to automatically mount their current working directory into Playground. (#39)
  • [PHP-wasm Node] Fix Identifier '\_\_filename' has already been declared. (#143)
  • [Website] Support data URLs in blueprint-url query parameter. (#158)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @JanJakes @mho22

+

[v1.0.37] (2025-05-15)

+

Various

+
  • Define DB_NAME constant when it's missing. (#140)
  • Support limiting files added to self-hosted packages. (#149)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @JanJakes

+

[v1.0.36] (2025-05-08)

+

Various

+
  • Document mounting OPFS storage _after_ the boot. (#141)
  • QUERY_STRING should default to empty string. (#139)
  • Remove null steps that are added. (#135)
  • [CLI] Fix package entry point path. (#136)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ashfame @bgrgicak @sejas

+

[v1.0.35] (2025-05-08)

+

[v1.0.34] (2025-05-08)

+

Various

+
  • Document mounting OPFS storage _after_ the boot. (#141)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ashfame

+

[v1.0.33] (2025-05-08)

+

Various

+
  • Add MySQL network calls to Asyncify tests. (#108)
  • Format the plugin-proxy file. (#127)
  • Plugin proxy: Allow all repos from WordPress, Automattic and Woocommerce organizations. (#128)
  • QUERY_STRING should default to empty string. (#139)
  • Remove null steps that are added. (#135)
  • Remove unused dependencies. (#116)
  • [CLI] Fix package entry point path. (#136)
  • [PHP-wasm Node] Add support for resolving wasm paths in Windows. (#129)
  • [PHP-wasm Node] Dynamically mount symlinks. (#125)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @bgrgicak @ingeniumed @sejas

+

[v1.0.32] (2025-05-06)

+

Various

+
  • Add MySQL network calls to Asyncify tests. (#108)
  • Format the plugin-proxy file. (#127)
  • Plugin proxy: Allow all repos from WordPress, Automattic and Woocommerce organizations. (#128)
  • Remove unused dependencies. (#116)
  • [PHP-wasm Node] Add support for resolving wasm paths in Windows. (#129)
  • [PHP-wasm Node] Dynamically mount symlinks. (#125)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @ingeniumed

+

[v1.0.31] (2025-04-29)

+

Bug Fixes

+
  • Fix changelog version order. (#100)
  • Fix openssl library paths in php-wasm build. (#102)
+

Various

+
  • Add private fork links to the changelog. (#98)
  • Allow public access to A8C Playground instance. (#119)
  • Make php-wasm and Playground CLI's fast to run with Node.js. (#107)
  • Playground CLI: Add skipSqliteSetup flag for MySQL support. (#97)
  • Prep the WP update workflows to be re-enabled. (#110)
  • Support building for additional remote origins. (#122)
  • Tweak Blueprint test string to match WP 6.8. (#117)
  • Update Nx, Vite, and ESLint dependencies. (#35)
  • Upgrade octokit to 3.1.2 to fix vulnerability. (#106)
  • Use Node as the Vitest environment. (#96)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton @ivan-ottinger @wojtekn

+

[v1.0.30] (2025-04-07)

+

Bug Fixes

+
  • Fix changelog workflow and backfill changelog entries from recent versions. (#83)
+

Various

+
  • Consider unexpected undefined symbols to be errors. (#86)
  • Ignore ca-bundle created by @php-wasm/cli. (#88)
  • Support Node.js args to built-script executor. (#92)
  • Support quickly testing php-wasm CLI changes with bun. (#85)
  • Update Emscripten version to 4.0.5. (#93)
  • Update Playground Node version to 20.9.0. (#89)
  • Upgrade express to 4.21.2. (#90)
  • [PHP-wasm] Use statfs from NODEFS in the Node version. (#94)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton @wojtekn

+

[v1.0.29] (2025-03-11)

+

Various

+
  • Blueprint bundles. (#75)
  • CORS Proxy: fetch() with credentials: "include". (#66)
  • Exif support for PHP-wasm. (#72)
  • Remove Data Liberation PHP modules. (#79)
  • Stop suppressing 64bit integer PHP warnings as 64bit longs are now suppoted. (#76)
  • [Blueprints] setSiteLanguage fetch translation package URL from WP.org. (#81)
  • [Website] Drop the static &lt;link rel="manifest"&gt; tag and generate one in JavaScript instead. (#78)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v1.0.28] (2025-03-05)

+

Various

+
  • 64bit integer support, drop PHP 7.0 and 7.1 support. (#74)
  • FS Journal: Handle renaming OPFS files via delete + create (instead of file.move()). (#64)
  • GitHub: Cache node_modules per arch to avoid nx error. (#70)
  • Merge from public Playground repo. (#59)
  • OPFS site creation: Use the same "is this directory a site?" check as the site list. (#65)
  • Stop adding source maps to offline assets list. (#68)
  • Support mobile access to private Playground instance. (#73)
  • TLS-&gt;HTTP Proxy: Support outbound request body. (#61)
  • TLS: Only use the server_name extension during server hello. (#62)
  • Website: Blueprints as PWAs with a dynamic manifest.json file. (#67)
  • Website: Preserve the mode query arg when opening OPFS site. (#63)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton

+

[v1.0.27] (2025-02-25)

+

Bug Fixes

+
  • Fix php-wasm build error for WITH_SOURCEMAPS=yes. (#44)
  • Fix php-wasm source map base. (#46)
  • Fix private website deployment workflow. (#57)
  • Fix up private website deployment workflow after initial commit. (#29)
+

Various

+
  • Add WITH_DEBUG option for building php-wasm with DWARF debug info. (#47)
  • Add janjakes to GitHub workflows actors. (#33)
  • Add a dedicated workflow for deploying private playground. (#28)
  • Add remote data blocks to the allowlist. (#30)
  • Allow ashfame to run self-hosted package release workflow. (#22)
  • Allow deploying custom supported domains for CORS proxy. (#54)
  • CORS proxy: Make allowed origins configurable. (#43)
  • Make further fixes for unreliable end-to-end tests. (#9)
  • Move DNS polyfills to a PHP extension and add missing constants. (#27)
  • New playground CLI function interface. (#40)
  • Replace some hardcoded refs to playground.wordpress.net web app. (#42)
  • Restore safety condition for CORS proxy deployment workflow. (#55)
  • Revert "Add the launch browser flag to CLI". (#24)
  • Revert "Support file URL resources in command line environment". (#41)
  • Schedule private deployment and use private environment. (#37)
  • Stop assuming CLI stdout is a TTY write stream. (#51)
  • Store WordPress site cookies in the browser instead of a custom Cookie Store. (#20)
  • Support file URL resources in command line environment. (#34)
  • Switch to relative paths in app manifest. (#36)
  • Switch to runner with more CPU and RAM. (#45)
  • Treat zip files as zip files regardless of file name. (#58)
  • Try more Playwright workers since we have a runner with more resources. (#48)
  • Update private Playground instance to use dedicated CORS proxy. (#56)
  • Use rsync instead of scp in website deploy workflow. (#26)
  • Use specified SQLite version also for PHP &lt; 7.4. (#32)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @ingeniumed @JanJakes @zaerl

+

[v1.0.26] (2025-02-04)

+

Bug Fixes

+
  • Fix workflow for deploying self-hosted packages. (#6)
+

Various

+
  • Add the launch browser flag to CLI. (#18)
  • [Fix] Zip spec compliance for exported backup file. (#7)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ashfame @brandonpayton @zaerl

+

[v1.0.25] (2025-02-04)

+

Various

+
  • Add missing node external to Playground CLI. (#19)
  • Add self-hosted package publishing. (#5)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v1.0.24] (2025-02-03)

+

[v1.0.23] (2025-01-27)

+

[v1.0.22] (2025-01-20)

+

[v1.0.21] (2025-01-13)

+

Enhancements

+
  • [Data Liberation] Add EPub to Blocks converter. (#2097)
  • [Data Liberation] Block markup consumers and producers. (#2121)
  • [Data Liberation] Filesystem entity reader. (#2125)
  • [Data Liberation] Recognize self-closing blocks in WP_Block_Markup_Processor. (#2120)
  • [Data Liberation] Refactor Entity Readers class diagram. (#2096)
+

PHP WebAssembly

+
  • PHP 8.4 support. (#2038)
  • Rewrote fileToUint8Array function to be also NodeJS/Deno compatible. (#2117)
  • [PHP] Restore /internal files and Filesystem mounts after hotswapPhpRuntime is called. (#2119)
+

Bug Fixes

+
  • [CORS Proxy] Support chunked encoding when running in Apache/Nginx/etc. (#2114)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @mbuella

+

[v1.0.20] (2025-01-06)

+

Website

+
  • Avoid login issue in deployment end-to-end tests. (#2065)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v1.0.19] (2024-12-30)

+

[v1.0.18] (2024-12-23)

+

Enhancements

+
  • [Data Liberation] Add HTML to Blocks converter. (#2095)
  • [Data Liberation] Add Markdown parsing libraries. (#2092)
  • [Data Liberation] Build markdown importer as phar. (#2094)
  • [Data Liberation] Move Markdown importer to a separate package. (#2093)
+

Blueprints

+
  • Prevent WSOD when autologin is enabled and a plugin logs a notice. (#2079)
+

Tools

+

GitHub integration

+
  • [Website] GitHub export modal: Correctly compute the root path when exporting the entire site. (#2103)
+

Website

+
  • Enable separate source maps for all package builds. (#2088)
+

Bug Fixes

+
  • Fix README.md typos. (#2091)
+

Various

+
  • Add small comment about lazy init of WXR reader. (#2102)
  • [Blueprints] Prevent plugin activation error if plugin redirects during activation or produces an output. (#2066)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @zaerl

+

[v1.0.17] (2024-12-17)

+

Tools

+

Blueprints Builder

+
  • Use transparent CORS proxy in Blueprint Builder. (#2089)
+

PHP WebAssembly

+
  • Build @php-wasm packages as dual ESM + CJS. (#2087)
+

###

+
  • Add ESLint rule to avoid unintentional dependency on @wp-playgrounds/wordpress-builds. (#2048)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton

+

[v1.0.16] (2024-12-16)

+

Enhancements

+
  • Allow Authorization header pass-through with X-Cors-Proxy-Allowed-Request-Headers. (#2007)
  • [Cors Proxy] Support Transfer-Encoding: Chunked. (#2077)
  • [Website] Enable CORS proxy for all fetches. (#2076)
+

Tools

+

Blueprints

+
  • [Blueprints] Preserve the first char of all filenames sourced from GitDirectoryReference. (#2070)
+

Import/Export

+
  • [Blueprints] Support Data Liberation importer in the importWxr step. (#2058)
+

PHP WebAssembly

+

Website

+
  • [Webiste] Switch the CORS Proxy URL to wordpress-playground-cors-proxy.net. (#2074)
+

Website

+
  • Bugfix: Delist data-liberation-core.phar from the preloaded offline mode assets. (#2072)
  • Don't show the error reporting modal on the initial load. (#2068)
  • Prevent the initial flash of "You have no Playgrounds" message. (#2069)
  • Remove old PR preview HTML files and add redirects to new preview modals. (#2081)
+

Internal

+
  • [Meta] Remove GitHub Board Automation workflow. (#2073)
+

Bug Fixes

+
  • Temporary: Skip more CI-only deployment test failures. (#2071)
+

Various

+
  • Ensure that Site Editor templates are associated with the correct taxonomy. (#1997)
  • PR Preview: Document and simplify targetParams. (#2052)
  • Revert "Remove old PR preview HTML files and add redirects to new preview modals". (#2082)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ajotka @akirk @brandonpayton @maxschmeling

+

[v1.0.15] (2024-12-09)

+

Enhancements

+
  • Shorten and simplify path to CORS proxy. (#2063)
  • Support users choosing how to handle URLs for sites that do not exist. (#2059)
+

Tools

+

GitHub integration

+
  • Add zaerl to GitHub workflows actors. (#2041)
+

PHP WebAssembly

+
  • [Networking] Decrypt TLS 1.2 alert messages. (#2060)
+

Website

+
  • Fix CORS proxy deploy workflow. (#2049)
  • Nightly build bugfix – ship the actual nightly build, not the latest release. (#2056)
  • Remove duplicate "Saved Playgrounds" label. (#2044)
+

Various

+
  • Add deploy workflow for standalone CORS proxy. (#2022)
  • Restore CORS support to CORS proxy. (#2023)
  • [Data Liberation] "Fetch from a different URL" button for failed media downloads, Interactivity API support. (#2040)
  • [Data Liberation] Sync WP_HTML API with WordPress 6.7.1 (and add a new test). (#2062)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @zaerl

+

[v1.0.14] (2024-12-02)

+

Blueprints

+
  • Resolve the latest WordPress version from the API instead of assuming it's the same as the last minified build. (#2027)
+

Tools

+

Blueprints Builder

+
  • Add installPlugin support for single plugin files. (#2033)
+

PHP WebAssembly

+
  • Networking: Preserve the content-type header when fetch()-ing. (#2028)
+

Website

+
  • [Web] Re-enable wp-cron. (#2039)
+

Various

+
  • [Data Liberation] WP_Stream_Importer: User-driven incremental import. (#2013)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton

+

[v1.0.13] (2024-11-25)

+

Enhancements

+
  • E2E: Disable a flaky deployment test. (#2016)
  • [Data Liberation] Add WXR import CLI script. (#2012)
  • [Data Liberation] Re-entrant WP_Stream_Importer. (#2004)
  • [Data Liberation] wp-admin importer page. (#2003)
+

Blueprints

+
  • SetSiteLanguage step – download the latest RC translations for Nightly and Beta builds of WordPress. (#1987)
  • Use the major WordPress version to download RC/beta translations. (#2017)
+

Tools

+

Pull Request Previewer

+
  • Fix path of PR preview URL in production. (#2014)
  • Support submitting PR preview modal with ENTER key. (#2015)
+

Website

+
  • Move WordPress & Gutenberg PR Preview to Playground website. (#1938)
  • Restore basic element styles for modal dialog content. (#2021)
+

Bug Fixes

+
  • Fix test.md link. (#2005)
+

Various

+
  • [Data Liberation] WP_Stream_Importer with support for WXR and Markdown files. (#1982)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ajotka @bgrgicak @brandonpayton @StevenDufresne @zaerl

+

[v1.0.12] (2024-11-18)

+

Website

+
  • [Service Worker] Support redirects to relative URLs in Safari. (#1978)
+

Blueprints

+
  • [Query API] Use the exact redirect URL provided in the ?url= query param. (#1945)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v1.0.11] (2024-11-11)

+

[v1.0.10] (2024-11-08)

+

Enhancements

+
  • [CLI] Set debug constants during boot. (#1983)
+

Bug Fixes

+
  • [CLI] Restore the "login" argument handler. (#1985)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak

+

[v1.0.9] (2024-11-04)

+

Enhancements

+
  • [Data Liberation] Fork humanmade/WordPress-Importer. (#1968)
  • [Data Liberation] Merge both XML processors into a single WP_XML_Processor. (#1960)
  • [Data liberation] Add blueprints-library as a submodule. (#1967)
+

Tools

+

Import/Export

+
  • [Data Liberation] WP_WXR_Reader. (#1972)
+

Documentation

+
  • Rewrite clone examples to use HTTPS instead of SSH. (#1963)
+

Website

+
  • Consistent width of settings, logs, and blueprint gallery sidebars. (#1964)
+

Bug Fixes

+
  • Fix: Import & Export from Github causes reloading the playground even before accept this step. (#1908)
  • [WordPress build] Only build the latest patch version of WordPress. (#1955)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ajotka @bgrgicak

+

[v1.0.8] (2024-10-30)

+

Enhancements

+
  • [Data liberation] wp_rewrite_urls(). (#1893)
+

PHP WebAssembly

+
  • [PHP.wasm for Node] Fix php.js import path in the published npm package. (#1958)
+

Website

+
  • Restore .d.ts files missing from the published @wp-playground/remote npm package. (#1949)
+

Various

+
  • [Data Liberation] Add XML API, Stream API, WXR URL Rewriter API. (#1952)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @psrpinto

+

[v1.0.7] (2024-10-28)

+

[v1.0.6] (2024-10-28)

+

Website

+
  • Query API: Preserve multiple ?plugin= query params. (#1947)
  • [Remote] Enable releasing @wp-playground/remote by making it public. (#1948)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v1.0.5] (2024-10-25)

+

Enhancements

+
  • [CORS Proxy] Rate-limits IPv6 requests based on /64 subnets, not specific addresses. (#1923)
+

Blueprints

+
  • Reload after autologin to set login cookies during boot. (#1914)
  • Skip empty lines in the runSql step. (#1939)
+

Documentation

+
  • Clarified wp beta to also include rc version. (#1936)
+

PHP WebAssembly

+
  • Enable CURL in Playground Web. (#1935)
  • PHP: Implement TLS 1.2 to decrypt https:// and ssl:// traffic and translate it into fetch(). (#1926)
+

Website

+
  • Hide Settings menu after clicking "Restore from .zip. (#1904)
  • Publish @wp-playground/remote (types only). (#1924)
+

Bug Fixes

+
  • CORS Proxy: Index update_at column because it is used for lookup. (#1931)
  • CORS Proxy: Reject targeting self. (#1932)
  • Docs: Fix typo. (#1934)
  • Explicitly request no-cache to discourage WP Cloud from edge caching CORS proxy results. (#1930)
  • Remove test code added in #1914. (#1928)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ajotka @bgrgicak @bph @brandonpayton @ockham @psrpinto

+

[v1.0.4] (2024-10-21)

+

Enhancements

+
  • Support CORS proxy rate-limiting. (#1879)
+

Blueprints

+
  • Allow multisites to load wp-admin pages with the landingPage attribute. (#1913)
+

Tools

+

GitHub integration

+
  • Blueprints: Use ? instead of / to CORS Proxy URLs. (#1899)
+

Import/Export

+
  • Kickoff Data Liberation: Let's Build WordPress-first Data Migration Tools. (#1888)
+

Experiments

+

File Synchronization

+
  • [Remote] Preserve PHP constants when saving a temporary site. (#1911)
+

Website

+
  • Do not display "You have no Playgrounds" message before loading the site. (#1912)
  • Fix build error that only appeared during deployment. (#1896)
  • Fix use of secrets on WP Cloud site. (#1909)
  • Maintain Query API parameters on temporary Playground settings update. (#1910)
  • Stop adding all CORS proxy files to website build. (#1895)
  • Stop responding with default MIME type. (#1897)
  • Stop short-circuiting web host PHP execution. (#1898)
  • Fix progress reporting during Playground load. (#1915)
  • Include CORS proxy with website builds. (#1880)
  • [Blueprints] Stop escaping landingPage URLs when loading WP Admin. (#1891)
+

Bug Fixes

+

Boot Flow

+
  • Prefer pretty permalinks like WP install does. (#1832)
+

Various

+
  • Improve self-host documentation. (#1884)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ashfame @bgrgicak @brandonpayton

+

[v1.0.3] (2024-10-14)

+

Enhancements

+
  • Website: Remove unused React components. (#1887)
+

Tools

+

Blueprints Builder

+
  • Blueprints sidebar section for single-click Playground presets. (#1759)
+

Website

+
  • Replace 100vh with 100dvh to fix an "unscrollable" state on mobile devices. (#1883)
  • Use modal for Site settings form on mobile – mobile Safari l…. (#1885)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v1.0.2] (2024-10-09)

+

PHP WebAssembly

+
  • PHP.wasm: Load correct php.wasm paths in the built Node.js packages. (#1877)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v1.0.1] (2024-10-09)

+

[v1.0.0] (2024-10-09)

+

Blueprints

+
  • Directory Resources. (#1793)
  • Login step – handle passwordless autologin via a PHP mu-plugin. (#1856)
+

Tools

+

Blueprints

+
  • GitDirectoryResource. (#1858)
  • GitDirectoryResource: Accept "/", "", "." as root paths. (#1860)
+

GitHub integration

+
  • Native git support: LsRefs(), sparseCheckout(), GitPathControl. (#1764)
+

Website

+
  • Add core-pr and gutenberg-pr Query API parameters. (#1761)
+

PHP WebAssembly

+
  • Refreshless website deployments – load remote.html using the network-first strategy. (#1849)
  • JSPI: Pass all unit tests, remove stale PHP builds. (#1876)
  • [Remote] Remove the "light" PHP.wasm bundle and only ship the "kitchen-sink" build. (#1861)
+

Website

+
  • Restore the single-click "Edit Settings" flow. (#1854)
  • Restrict CORS proxy to requests from Playground website origin. (#1865)
+

Documentation

+
  • Add /release redirect to WP beta/RC blueprint. (#1866)
+

Internal

+
  • Make isomorphic-git submodule use https, not ssh. (#1863)
+

Bug Fixes

+
  • [CLI] Fix isWordPressInstalled() in CLI by inlining the auto_login.php in index.ts instead of using import ?raw. (#1869)
+

Various

+
  • Add documentation around the GPL license and implications for contribution. (#1776)
  • Allow installing Plugins/Themes into an arbitrary folder. (#1803)
  • Improve documentation. (#1862)
  • [Website] Fix "undefined" as className. (#1870)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @ajotka @bgrgicak @brandonpayton @dd32 @n8finch

+

[v0.9.46] (2024-10-07)

+

Enhancements

+
  • Webapp upgrade protocol: Disable HTTP caching and reload other browser tabs to prevent fatal errors after new deployments. (#1822)
+

Documentation

+
  • Docs: Disable localeDropdown until more pages are translated. (#1824)
  • Docs: Review playground documentation translations page. (#1826)
  • Docs: Playground PR previews through GitHub actions. (#1825)
+

Website

+
  • Use site slug as a stable scope. (#1839)
  • Close Playground Manager by default. (#1831)
  • Fix go-to-site menu items to reveal site view. (#1833)
+

Various

+
  • Add Install instructions to the Playwright README. (#1837)
  • Resolve end-to-end failures. (#1844)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @akirk @brandonpayton @juanmaguitar

+

[v0.9.45] (2024-09-30)

+

Blueprints

+
  • Translate GitHub.com file URLs into CORS-accessible raw.githubusercontent.com. (#1810)
+

Tools

+
  • [UX] Stored Playgrounds (no more data loss), multiple Playgrounds, UI WebApp Redesign. (#1731)
+

Documentation

+
  • Docs: Translation i18n messages - JSON files. (#1807)
+

Website

+
  • Prevent creation of two temporary sites. (#1817)
  • Stop address bar from adding trailing slash to query params. (#1820)
+

Bug Fixes

+
  • Fix broken Playwright tests. (#1819)
+

Various

+
  • Add Playwright tests for UI redesign changes. (#1769)
  • Docs: Contributions to translations. (#1808)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @juanmaguitar

+

[v0.9.44] (2024-09-24)

+

Bug Fixes

+
  • Docs: Fix links intro fr. (#1795)
+

Various

+
  • Add missing functions required to succesfully connect with MySQL DB. (#1752)
+

Contributors

+

The following contributors merged PRs in this release:

+

@jeroenpf @juanmaguitar

+

[v0.9.43] (2024-09-23)

+

Documentation

+
  • Docs: Better paths for links. (#1765)
  • Docs: I18n setup. (#1766)
  • Docs: Remove the outdated "data rependencies" page. (#1785)
+

Website

+
  • Fix troubleshoot-and-debug link. (#1782)
+

Various

+
  • Update link for contributor day. (#1775)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @juanmaguitar @n8finch

+

[v0.9.42] (2024-09-17)

+

PHP WebAssembly

+
  • FS: Use the correct rm/rmdir method when moving files between mounts. (#1770)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.41] (2024-09-16)

+

[v0.9.40] (2024-09-16)

+

Enhancements

+
  • Extend allowable resources available via WordPress/WordPress. (#1721)
+

Tools

+
  • Update actions/upload-artifact version to 4. (#1748)
+

Documentation

+
  • Docs/Blueprints resources: Grammar and typo fixes. (#1741)
+

PHP WebAssembly

+
  • @php-wasm/universal : Add Phar support in php-wasm. (#1716)
+

Website

+
  • Add the components package with PathMappingControl. (#1608)
+

Bug Fixes

+
  • Fix CLI --skipWordPressSetup option. (#1760)
+

Reliability

+
  • Improve Playground CLI logging and fix quiet mode. (#1751)
+

Various

+
  • Docs/Guides: Guides introductions and some minor adjustments. (#1754)
  • Docs/Guides: Normalized and fixed guides links. (#1756)
  • Docs/Guides: Providing content for your demo. (#1747)
  • Docs/Guides: WordPress Playground for plugin developers. (#1750)
  • Docs/Guides: WordPress Playground for theme developers. (#1732)
  • Docs: Links redirections. (#1758)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @juanmaguitar @mho22 @peterwilsoncc

+

[v0.9.39] (2024-09-09)

+

Bug Fixes

+
  • Use the correct imports in the generated .d.ts files. (#1742)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.38] (2024-09-09)

+

Internal

+
  • Fix changelog updates for latest doc structure. (#1734)
+

Various

+
  • Add support for handling symlinks in the request handler. (#1724)
  • Docs: Playground block in launch section. (#1722)
  • documentation - Blueprints - Resources: Highlight installPlugin and installTheme steps and most common resouces for them. (#1733)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @jeroenpf @juanmaguitar

+

[v0.9.37] (2024-09-05)

+

PHP WebAssembly

+
  • Add more asyncify-listed PHP functions to fix Studio crash. (#1729)
+

Website

+
  • Add initial site info view. (#1701)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.36] (2024-09-03)

+

Bug Fixes

+
  • Fix logger test for inconsistent short month. (#1727)
+

Reliability

+
  • Avoid errors due to log message formatting. (#1726)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.35] (2024-08-29)

+

Enhancements

+
  • Allow specifying a WordPres/WordPress branch and pulling from GitHub. (#1705)
+

PHP WebAssembly

+
  • Fix: Exit http server on php exit. (#1714)
+

Various

+
  • Enable networking for WordPress and Gutenberg PR viewers. (#1715)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ironprogrammer @kozer @peterwilsoncc

+

[v0.9.34] (2024-08-28)

+

PHP WebAssembly

+
  • @php-wasm/node: Publish index.d.ts. (#1713)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.33] (2024-08-28)

+

Internal

+
  • @php-wasm/util: Publish TypeScript types. (#1711)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.32] (2024-08-26)

+

Website

+
  • Make the site switcher work again. (#1698)
  • WebApp Redesign: Interact with sites list via redux. (#1679)
  • deployment: Fix builder redirect. (#1696)
+

Bug Fixes

+
  • Docs: Fix typo and replace en dash with hyphen for consistency. (#1702)
  • Fix broken documentation links. (#1694)
  • Remove Playground branding from site list. (#1700)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @eliot-akira @mirka

+

[v0.9.31] (2024-08-20)

+

Enhancements

+

Boot Flow

+
  • A boot() method to explicitly initialize the PHP worker. (#1669)
+

Website

+
  • Fix builder redirect. (#1693)
+

Internal

+
  • Avoid GH board automation permissions error. (#1691)
  • Refresh sqlite-database-integration from develop branch. (#1692)
+

Bug Fixes

+

Boot Flow

+
  • Fix sqlite-database-integration rename fatal. (#1695)
+

Documentation

+
  • Docs: Fix links to proper pages. (#1690)
+

Various

+
  • Documentation structure overhaul. (#1602)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @juanmaguitar

+

[v0.9.30] (2024-08-19)

+

Website

+
  • Ask users to report errors if Playground load fails. (#1686)
+

Bug Fixes

+
  • Avoid Blueprint schema formatting changes by build. (#1685)
+

Various

+
  • [Website] Improves the messaging around exporting a zip if needed, when connecting to GitHub. (#1689)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton @jonathanbossenger

+

[v0.9.29] (2024-08-12)

+

Tools

+
  • Add max-len rule. (#1613)
+

Experiments

+

GitHub integration

+
  • Add site manager view and sidebar. (#1661)
  • Add sites from the site manager. (#1680)
+

PHP WebAssembly

+
  • Offline mode end-to-end tests. (#1648)
+

Website

+
  • Add nice redirects for the new documentation site. (#1681)
  • Fix site manager button styles. (#1676)
+

Bug Fixes

+
  • Revert "Offline mode end-to-end tests". (#1673)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v0.9.28] (2024-08-05)

+

Blueprints

+
  • Add support for loading wpCli without running blueprint steps. (#1629)
+

Documentation

+
  • Blueprints: Add resetData step to documentation. (#1658)
  • Docs: Redirect from /docs to https://wordpress.github.io/wordpress-playground. (#1671)
+

Website

+
  • Suppress unavoidable Deprecated notices - Networking. (#1660)
  • UI: Explain the Logs modal. (#1666)
+

Blueprints

+
  • Precompile Ajv Blueprint validator to avoid CSP issues. (#1649)
+

Internal

+
  • Reinstantiate Changelog generation in GitHub CI. (#1657)
+

Various

+
  • Rollback artifact creation to enable downloading a pre-built package …. (#1624)
  • Update WordPress packages. (#1672)
  • Update ws package version to fix DOS vulnerability. (#1635)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @PiotrPress

+

[v0.9.27] (2024-07-29)

+

Enhancements

+
  • Support offline mode after the first Playground page load. (#1643)
+

Devrel

+
  • Remove puzzle app package. (#1642)
+

PHP WebAssembly

+
  • Cache Playground assets to enable offline support. (#1535)
  • Rotate PHP runtime after runtime crash. (#1628)
  • Throw error when PHP run() receives no code to run. (#1646)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton

+

[v0.9.26] (2024-07-22)

+

Blueprints

+
  • Add missing blueprints library dep. (#1640)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.25] (2024-07-22)

+

Tools

+
  • Make sure NPM packages declare dependencies. (#1639)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.24] (2024-07-22)

+

Bug Fixes

+
  • Fix plugin-proxy response codes. (#1636)
  • Stop publishing @wp-playground/wordpress-builds package. (#1637)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton

+

[v0.9.23] (2024-07-22)

+

PHP WebAssembly

+
  • Route requests more like a normal web server. (#1539)
+

Website

+
  • Remove old, unused website deployment workflow. (#1633)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.22] (2024-07-19)

+

Bug Fixes

+
  • Remove WP 6.2 support after WP 6.6 release. (#1632)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.9.21] (2024-07-19)

+

Website

+
  • Fix manifest.json URLs. (#1615)
+

Internal

+
  • Fix joinPaths root edge case. (#1620)
+

Various

+
  • Disable PHP 7.0 and 7.1 version switcher end-to-end tests. (#1626)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton

+

[v0.9.20] (2024-07-16)

+

Enhancements

+

Boot Flow

+
  • Backfill the assets removed from minified WordPress bundles. (#1604)
  • Register service worker before spawning the worker thread. (#1606)
+

Website

+
  • Disable website features that don't work while offline. (#1607)
  • Generate a list of assets to cache for offline support. (#1573)
+

Internal

+
  • Build: Ship the default TypeScript .d.ts declaration files, not rollups. (#1593)
+

Bug Fixes

+

Boot Flow

+
  • Fix recursive calls to backfillStaticFilesRemovedFromMinifiedBuild. (#1614)
+

Various

+
  • Add/allow import site gutenberg pr. (#1610)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @smithjw1

+

[v0.9.19] (2024-07-15)

+

Breaking Changes

+
  • Set web worker startup options with messages instead of query strings. (#1574)
+

Blueprints

+
  • Add an Import Theme Starter Content step. (#1521)
  • Add setSiteLanguage step to change the language. (#1538)
  • Mark shorthand properties as stable, not deprecated. (#1594)
+

Documentation

+
  • Add Blueprint 101 to Documentation. (#1556)
+

PHP WebAssembly

+

Website

+
  • Download all WordPress assets on boot. (#1532)
+

Website

+ +

Various

+
  • Revert "Set web worker startup options with messages instead of query strings". (#1605)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @bph @dd32

+

[v0.9.18] (2024-07-09)

+

Website

+
  • Remove the unused isSupportedWordPressVersion export. (#1592)
+

Internal

+
  • Build: Polyfill \_\_dirname in php-wam/node ESM via banner option. (#1591)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.16] (2024-07-09)

+

Internal

+
  • Build: Source external deps from package.json. (#1590)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.15] (2024-07-09)

+

Internal

+
  • Build: Use regular expressions to mark packages as external. (#1589)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.14] (2024-07-09)

+

Devrel

+
  • Remove Puzzle app from the Playground website. (#1588)
+

Internal

+
  • Vite build: Mark all imported modules as external to avoid bundling them with released packages. (#1586)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v0.9.13] (2024-07-08)

+

PHP WebAssembly

+
  • php-wasm/node: Ship as ESM and CJS. (#1585)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.12] (2024-07-08)

+

[v0.9.11] (2024-07-08)

+

PHP WebAssembly

+
  • Build: Treat all dependencies of php-wasm/node as external. (#1584)
+

Various

+
  • Autopublish npm packages every week. (#1542)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.10] (2024-07-08)

+

Internal

+
  • Revert "Use NPM for publishing packages instead of Lerna ". (#1582)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.9] (2024-07-08)

+

Internal

+
  • Use NPM for publishing packages instead of Lerna. (#1581)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.9.4] (2024-07-03)

+

Documentation

+
  • Update the Blueprint data format doc. (#1510)
+

Contributors

+

The following contributors merged PRs in this release:

+

@ndiego

+

[v0.9.3] (2024-07-03)

+

Tools

+

Blueprints

+
  • Importing regression fix – support old exported Playground ZIPs. (#1569)
+

Documentation

+
  • Add GitHub development instructions. (#1551)
+

Internal

+
  • Meta: GitHub Boards Automation. (#1549)
  • Meta: GitHub-sourced Mindmap. (#1559)
+

###

+
  • Add cache version number. (#1541)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak

+

[v0.9.1] (2024-06-26)

+

PHP WebAssembly

+
  • Networking access: Fix wp_http_supports() to work without the kitchen-sink extension bundle. (#1504)
  • Networking: Remove CORS workarounds for WordPress.org API. (#1511)
  • Backfill remote asset listing when needed. (#1531)
+

Website

+
  • Remove "small window mode". (#1540)
  • Detect actual, loaded WP version. (#1503)
+

Various

+
  • Remove deprecation note from shorthand steps. (#1507)
  • Remove trailing semicolon from example URL for loading playground with network access. (#1520)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bph @brandonpayton @dd32 @oskosk

+

[v0.7.20] (2024-05-21)

+

Breaking Changes

+
  • [Breaking] Refactor PHP.ini management, remove php.setPhpIniPath() and php.setPhpIniEntry(). (#1423)
+

Enhancements

+
  • CLI: Distinguish between mount and mountBeforeInstall options. (#1410)
  • CLI: Support fetching WordPress zips from custom URLs. (#1415)
  • Introduce a new @wp-playground/common package to avoid circular depencies. (#1387)
  • Website: Ship the SQLite database integration plugin. (#1418)
+

Boot Flow

+
  • Playground CLI: Don't create /wordpress/wp-config.php on boot. (#1407)
+

Blueprints

+
  • Define constants in auto_prepend_file, silence warnings related to redefining those constants. (#1400)
  • Detect silent failures when activating plugins and theme. (#1436)
  • Re-activate single-file plugins when enabling a multisite. (#1435)
  • Throw an error when activating a theme or plugin that doesn't exist. (#1391)
  • Write sunrise.php to /internal in enableMultisite step. (#1401)
+

Tools

+
  • Add VSCode branch protection. (#1408)
  • Show error log if Playground fails to start. (#1336)
+

Blueprints

+
  • Unzip: Only delete a temporary zip file after unzipping, do not delete the original zip. (#1412)
+

GitHub integration

+
  • GitHub export: Create new commits in your fork when writing to the upstream repo isn't allowed. (#1392)
+

Import/Export

+
  • Support wp_crop_image in import wxr. (#1357)
+

Devrel

+ +

Documentation

+
  • Docs: Use step function names instead of TypeScript type names. (#1373)
  • Updated the GitHub issue link to open in a new tab. (#1353)
  • Use step id name. (#1377)
+

Experiments

+
  • Explore: Setup SQLite database integration without creating wp-content/db.php. (#1382)
+

PHP WebAssembly

+
  • Add shareable extension-to-MIME-type mapping. (#1355)
  • Document php ini functions. (#1430)
  • JSPI: Enable the origin trial on Chrome. (#1346)
  • PHP: Add libjpeg and libwebp support. (#1393)
  • PHP: Always set the auto_prepend_file php.ini entry, even when the auto_prepend_file.php file exists. (#1388)
  • PHP: Move internal shared directories to /internal/shared. (#1386)
  • PHP: Remove mentions of a custom PHP extension. (#1422)
  • PHP: Remove the MODE_EVAL_CODE execution mode. (#1433)
  • PHP: Support php.mv() between devices via recursive copy. (#1411)
  • PHP: Use /internal/shared/php.ini by default. (#1419)
  • PHP: Use auto_prepend_file to preload mu-plugins (instead of creating them in wp-content/mu-plugins). (#1366)
+

Website

+
  • Improve log modal styles, a11y, error message wording. (#1369)
  • Move puzzle app to a Playground package. (#1385)
  • Add secrets on-demand for more endpoints. (#1362)
  • Boot: Move WordPress zip extraction logic to a common unzipWordPress() utility. (#1427)
  • Derive MIME types for PHP served files from shared JSON. (#1360)
  • Fix constant names for GH export oauth. (#1378)
  • Playground Boot: Align the boot process between remote.html and CLI. (#1389)
  • Remote.html: Install WordPress if it isn't installed yet. (#1425)
  • Remote.html: Preload the SQLite database plugin, but only execute it if there's no custom db.php inside wp-content. (#1424)
  • Simplify website deployment workflows. (#1404)
  • Update rsync command to clean up more completely. (#1361)
+

Blueprints

+
  • Provide non-gzipped wp-cli.phar file with website build. (#1406)
  • Simplify runPhpWithZipFunctions() setup. (#1434)
+

Internal

+
  • Fix changelog automation. (#1413)
+

Bug Fixes

+
  • Add name to Puzzle package. (#1443)
  • Fixed images not loading on the page. (#1352)
  • Restore nightly wordpress build. (#1437)
+

Reliability

+
  • Disable console logging when running tests. (#1368)
+

###

+
  • Lint: Disable console warnings for paths where they're not useful. (#1421)
+

Various

+
  • Add links to kitchen sink (PHP extensions), networking. (#1363)
  • Reorganize and update documentation. (#1354)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @flexseth @ironnysh @josevarghese

+

[v0.7.15] (2024-04-30)

+

Website

+
  • Avoid edge-caching conditionally redirected resources. (#1351)
  • Fix deploy-time check for file with PHP-handled redirect. (#1350)
+

Contributors

+

The following contributors merged PRs in this release:

+

@brandonpayton

+

[v0.7.10] (2024-04-30)

+

PHP WebAssembly

+
  • PHP.wasm Node: Revert a part of #1289, do not import a .wasm file. (#1348)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.7.5] (2024-04-30)

+

Internal

+
  • Meta: Move the minified WordPress to the new @wp-playground/wordpress-builds package. (#1343)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.7.3] (2024-04-29)

+

PHP WebAssembly

+ +

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.7.2] (2024-04-29)

+

Breaking Changes

+
  • PHP: Remove setSapiName, setPhpIniEntry, setPhpIniPath methods from the remote PHP API client. (#1321)
  • Remove the wp-playground/node package. (#1323)
+

PHP WebAssembly

+
  • Breaking: Loopback Request Support. (#1287)
+

Tools

+
  • Centralize log storage. (#1315)
+

Documentation

+
  • Link to Installing Nx Globally in the README. (#1325)
+

PHP WebAssembly

+
  • Add PHPResponse.forHttpCode() shorthand. (#1322)
  • Asyncify: List ZEND_FETCH_OBJ_R_SPEC_CV_CV_HANDLER. (#1342)
  • Curl extension for the Node.js build of PHP.wasm. (#1273)
  • Explore curl support. (#1133)
  • PHP Process Manager. (#1301)
  • PHPProcessManager: Clear nextInstance when the concurrency limit is exhausted. (#1324)
  • Spawn handler: Wrap the program call with try/catch, exit gracefully on error. (#1320)
+

Website

+
  • Add initial workflow for deploying the website to WP Cloud. (#1293)
  • Eliminate 404s due to nested files-to-serve-via-php dir. (#1333)
  • Stop WP rewrite rules from matching files like wp-admin.css. (#1317)
  • Stop using PHP to serve most static files on WP Cloud. (#1331)
  • WP Cloud: Relay secrets for error logger. (#1337)
+

Documentation

+
  • Document WP Cloud website setup. (#1338)
+

Reliability

+
  • Add log methods, log handlers, and separate log collection. (#1264)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @juanmaguitar @mho22

+

[v0.7.1] (2024-04-24)

+

[v0.7.0] (2024-04-24)

+

Breaking Changes

+

PHP WebAssembly

+
  • Breaking: Remove PHPBrowser. (#1302)
+

Enhancements

+
  • Bump TypeScript to 5.4.5. (#1299)
  • Semaphore: Add timeout option. (#1300)
+

Blueprints

+
  • Builder: Fix stuck loader bar. (#1284)
  • Remove setPhpIniEntry step. (#1288)
+

Tools

+

GitHub integration

+
  • GitHub: Don't delete all the files when exporting a theme. (#1308)
  • Urlencode branch name. (#1275)
+

Blueprints

+
  • Blueprints builder: Support ?blueprint-url. (#1309)
+

Documentation

+
  • Use new learning resources in Playground documentation. (#1276)
+

PHP WebAssembly

+
  • Browser: Remove setSpawnHandler function from the public API. (#1303)
  • PHP: Add a cwd argument to hotSwapPHPRuntime(). (#1304)
  • PHP: Remove addServerGlobalEntry() method, accept $\_SERVER as php.run() property. (#1286)
  • PHPRequestHandler: Add a generic PHP argument. (#1310)
  • nit: Clean up after node PHP popen() test. (#1280)
+

Website

+
  • Add more info to crash reports. (#1253)
  • Memoize fetch() responses when requesting php.wasm. (#1306)
  • Progress monitoring: Use a custom instantiateWasm handler to avoid monkey-patching WebAssembly.instantiateStreaming. (#1305)
  • Remove sandbox attribute from iframe. (#1313)
  • Service Worker: Fetch credentialless to play more nicely with server caches (#1311). (#1311)
+

Internal

+
  • Automate Changelog generation after each npm release. (#1312)
  • CI: Fix intermittent documentation build failures. (#1307)
+

Bug Fixes

+
  • Add styles to ensure iframes are responsive. (#1267)
  • Docs: Fix the Blueprint example of the Gutenberg PR preview. (#1268)
  • Docs: Move Steps Shorthands to a separate page to fix Steps TOC. (#1265)
+

Reliability

+
  • Add network error message. (#1281)
  • Explore logging to a file. (#1292)
+

Various

+
  • Add PDF to infer mime type list. (#1298)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @ironnysh @peeranat-dan

+

[v0.6.16] (2024-04-17)

+

Blueprints

+
  • Replace set_current_user call with wp_set_current_user to fix a PHP notice. (#1262)
+

Tools

+
  • Install themes and plugins using the ReadableStream API. (#919)
+

Documentation

+
  • Docs: Update WordPress versions used in the documentation, document using older releases. (#1235)
+

PHP WebAssembly

+
  • Filter Requests library to use the Fetch handler. (#1048)
+
  • PHP: Handle request errors in PHPRequestHandler, return response code 500. (#1249)
  • PHP: Reset exit code before dispatching a request. (#1251)
+

Various

+
  • Add documentation for shorthand alternatives of Blueprint steps. (#1261)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @dd32 @ironnysh @kozer

+

[v0.6.15] (2024-04-16)

+

Blueprints

+
  • Add ifAlreadyInstalled to installPlugin and installTheme steps. (#1244)
  • Support a landingPage value without the initial slash. (#1227)
+

PHP WebAssembly

+
  • Investigate OOB: Run unit tests with instrumented PHP 8.0 code. (#1220)
  • Unit tests: Restore site-data.spec.ts. (#1194)
  • Web PHP: Increase memory limit to 256 M. (#1232)
+

Website

+
  • Browser: Display PHP output when Fatal Error is trigerred. (#1234)
  • Fix accessibility issues found by Axe. (#1246)
  • Request Handler: Urldecode the requested path. (#1228)
+

Bug Fixes

+
  • fix: Set required engine version to 18.18.0. (#1214)
+

Various

+
  • Blueprints/json example. (#1188)
  • Doc: Update 01-index.md. (#1216)
  • Move DefineSiteUrlStep doc warning so it displays in documentation. (#1245)
  • Updated link to native WordPress importer. (#1243)
  • documentation update proposal: Provide more info on features, extensions?. (#1208)
  • php-wasm/node: Update express to newest version, and move it to devDependencies. (#1218)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @artpi @bph @brandonpayton @eliot-akira @flexseth @ironnysh @kirjavascript

+

[v0.6.14] (2024-04-11)

+

Bug Fixes

+
  • Revert changes to the documentation build. (#1226)
+

Reliability

+
  • Update error modal description label. (#1224)
+

Various

+
  • Try memory leak workaround with zeroed mem. (#1229)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton

+

[v0.6.13] (2024-04-10)

+

PHP WebAssembly

+
  • Try to repro memory out of bounds errors in CI. (#1199)
+

Bug Fixes

+
  • Fix docs-site build. (#1222)
+

Contributors

+

The following contributors merged PRs in this release:

+

@bgrgicak @brandonpayton

+

[v0.6.11] (2024-04-09)

+

Tools

+
  • Avoid Service Worker update issues on localhost. (#1209)
+

Import/Export

+
  • importWxr: Preserve backslashes in the imported content. (#1213)
+

PHP WebAssembly

+
  • Catch DNS errors to avoid unhandled exceptions. (#1215)
+
  • Revert "Avoid partial munmap memory leak". (#1195)
  • Try to repro memory out of bounds errors in CI. (#1198)
+

Various

+
  • Adjust link to LICENSE file. (#1210)
  • Try to reproduce the memory access error with files from 096a017. (#1212)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @emmanuel-ferdman @fluiddot

+

[v0.6.10] (2024-04-04)

+

Blueprints

+
  • Rename importFile to importWxr, switch to humanmade/WordPress importer. (#1192)
+

Tools

+

Blueprints

+
  • Explorations: Stream API. (#851)
+

PHP WebAssembly

+
  • Avoid partial munmap memory leak. (#1189)
+

Website

+
  • Make kitchen sink extension bundle the default. (#1191)
+

Bug Fixes

+
  • Fix cross-device mv by switching to copy. (#846)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @brandonpayton @seanmorris

+

[v0.6.9] (2024-04-03)

+

Tools

+
  • Devex: Expose window.playground for quick testing and debugging. (#1125)
+

GitHub integration

+
  • Website: Query API options to preconfigure the GitHub export form. (#1174)
+

Documentation

+
  • Update the wp-cli step code example. (#1140)
+

PHP WebAssembly

+
  • Add PHP iterator and yield support. (#1181)
  • Fix fileinfo support. (#1179)
  • Fix mbregex support. (#1155)
  • PHP.run(): Throw JS exception on runtime error, remove throwOnError flag. (#1137)
+

Website

+
  • Add error report modal. (#1102)
  • Ensure PromiseRejectionEvent has reason before logging it. (#1150)
  • Request handler: Remove everything after # from the URL. (#1126)
  • Web: Make the "Apply changes" button work in Playground settings form. (#1122)
+

Plugin proxy

+
  • Allow requests to WordPress.org. (#1154)
+

Internal

+
  • Refresh WordPress with the latest SQLite integration plugin. (#1151)
+

Bug Fixes

+
  • Fix typo in blueprints/public/schema-readme.md. (#1134)
  • Priority: Fix broken link to VS Code extension. (#1141)
+

Various

+
  • Docs/update - Add implied step. (#1144)
  • Give brandonpayton permission to run Playground GH workflows. (#1139)
  • Logger API: Add rate limiting. (#1142)
  • Remove --disable-all configuration option in PHP compile process. (#1132)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @brandonpayton @flexseth @jblz @mho22

+

[v0.6.8] (2024-03-21)

+

Blueprints

+
  • Allow optional metadata. (#1103)
+

Tools

+
  • Add VSCode Chrome debugging support. (#1088)
  • Website: Support Base64-encoding Blueprints passed in the URL. (#1091)
+

Documentation

+
  • Docs: Expand Details section. (#1109)
  • Update activate-theme.ts to use themeFolderName. (#1119)
+

PHP WebAssembly

+
  • Blueprints: Explore switching to the PHP implementation. (#1051)
  • Explore weird register_shutdown_function behavior. (#1099)
  • Fix post_message_to_js memory out of bounds. (#1114)
  • Fix shutdown errors. (#1104)
  • Fixing build regression [BISON COMPILE]. (#871)
  • PHP : Set appropriate SCRIPT variables in $\_SERVER superglobal. (#1092)
+

Website

+
  • Add logger API. (#1113)
  • Add multisite rewrite rules. (#1083)
  • Service worker: Improve error reporting in non-secure contexts. (#1098)
+

Bug Fixes

+
  • Fix experimental notice in FF ESR. (#1117)
  • Fix php bison dep for building on non-arm64 architectures. (#1115)
+

Reliability

+
  • Add fatal errror listener. (#1095)
+

Various

+
  • Update examples and demos in the documentation. (#1107)
+

Contributors

+

The following contributors merged PRs in this release:

+

@0aveRyan @adamziel @bgrgicak @brandonpayton @ironnysh @mho22 @seanmorris @StevenDufresne

+

[v0.6.7] (2024-03-06)

+

Website

+
  • Node polyfills: Only apply them in Node.js, not in web browsers. (#1089)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.6.6] (2024-03-06)

+

Website

+
  • Comlink API: Pass the context argument to windowEndpoint, not wrap. (#1087)
  • Fix: Playground not starting due to a race condition. (#1084)
  • Hide the "This is experimental WordPress" notice on click. (#1082)
  • Set the API context when using Comlink.wrap(). (#1085)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel

+

[v0.6.5] (2024-03-05)

+

Tools

+

Plugin proxy

+
  • Add Sensei to the allowed repositories for plugin proxy. (#1079)
+

Blueprints

+
  • Snapshot Import Protocol v1. (#1007)
+

Internal

+
  • Build the php-wasm/util package as both ESM and CJS. (#1081)
+

Reliability

+

Blueprints

+
  • Add unit tests to the mkdir step. (#1029)
+

Various

+
  • Website query API: Continue plugin installs on error. (#605)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @eliot-akira @reimic @renatho

+

[v0.6.4] (2024-03-04)

+

Enhancements

+
  • Add logging support to Playground. (#1035)
+

Blueprints

+
  • PHP Blueprints: Display progress. (#1077)
  • Set progress caption and communicate failures in the import file step. (#1034)
+

Tools

+

Blueprints

+
  • PHP Blueprints demo page. (#1070)
  • PHP: Do not prepend a whitespace when encoding body as multipart form data. (#1033)
+

PHP WebAssembly

+
  • Fix response header escaping. (#1050)
  • Fix: Networking broken when extra PHP extensions are enabled. (#1045)
  • PHP.wasm: Yield 0 bytes read on fd_read failure to improve PHP's fread() and feof() behavior. (#1053)
  • PHP: Support $env and $cwd proc_open arguments. (#1064)
  • Parse shell commands in createSpawnHandler. (#1065)
  • Prototype: Spawning PHP sub-processes in Web Workers. (#1031)
  • Spawning PHP sub-processes in Web Workers. (#1069)
+

Website

+
  • Add Google Analytics events to Playground. (#1040)
  • Fix error on reload site click. (#1041)
+

Internal

+
  • Rebuild WordPress every 20 minutes, short-circuit if no new version is found. (#1061)
  • Rebuild WordPress within an hour of a beta release. (#1059)
+

Bug Fixes

+
  • Fix the login message so it doesn't override another. (#1044)
+

Various

+
  • Add arguments to default node spawn method. (#1037)
  • Add bgrgicak to deployment allowlists. (#1057)
  • Allow for CORS requests to api.wordpress.org to pass. (#1009)
  • Default URL rewrites to /index.php. (#1072)
  • Remove repository specific Code of Conduct. (#1038)
  • Ship WordPress 6.5 beta 1. (#1036)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @dd32 @desrosj @johnbillion @mho22

+

[v0.6.3] (2024-02-12)

+

Blueprints

+ +

PHP WebAssembly

+
  • Calls proc_open two times in a row. (#1012)
  • Experiment: Build PHP with OPFS support. (#1030)
  • PHP: Pass request body as UInt8Array. (#1018)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @mho22

+

[v0.6.2] (2024-02-08)

+

PHP WebAssembly

+
  • Networking: Swap Requests transports using the http_api_transports instead of patching the Requests library. (#1004)
  • Remove crypto.randomUUID dependency in favor of a custom function. (#1016)
  • Remove x-request-issuer header on cross-origin requests. (#1010)
  • Update wp_http_fetch.php. (#1002)
+

Website

+
  • Remote.html: Always install the playground mu-plugin. (#1005)
+

Various

+
  • 32bit integer workaround. (#1014)
  • Test/hello world blueprint. (#908)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bgrgicak @jdevalk @sejas @stoph

+

[v0.6.1] (2024-02-05)

+

Website

+

Blueprints

+
  • Remove the applyWordPressPatches step, enable the Site Health Plugin. (#1001)
+

Various

+
  • Add crypto to Polyfills improving Blueprint compatibility for Node. (#1000)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @sejas

+

[v0.6.0] (2024-02-05)

+

Enhancements

+
  • Add wp-cli and code editor examples to the demos page. (#965)
  • WordPress: Preserve PHP attributes and wp-config.php whitespace. (#964)
+

Blueprints

+
  • Add enableMultisite step. (#888)
  • Set_current_user to admin before activating plugins and themes. (#984)
+

Tools

+
  • Use .zip files instead of .data files for loading WordPress. (#978)
+

Blueprints

+
  • Throw on failure. (#982)
+

PHP WebAssembly

+
  • Support wp-cli in the browser. (#957)
+

PHP WebAssembly

+
  • Correcting OOB & Prevent Crash on Saving Large Post. (#870)
  • Memory leak: Add rotatedPHP to kill and recreate PHP instances after a certain number of requests. (#990)
  • PHP : Add args and descriptors dynamic arrays in proc open function. (#969)
  • PHP.wasm: Fix stack overflow in wasm_set_request_body. (#993)
+

Website

+
  • Add .htaccess file to prevent caching of index.html and enable importing the client.js library. (#989)
  • Add og meta tags and meta description. (#980)
  • CORS headers for client/index.js. (#893)
  • wp-cli: Respect quotes when parsing shell commands. (#966)
+

Internal

+
  • Remove the interactive block playground. (#988)
+

Bug Fixes

+
  • Fix "WP-CLI" typos. (#971)
  • Fix footer styling issue in the "Code is Poetry" in wordpress.github.io/wordpress-playground. (#959)
  • WordPress build: Add newlines after PHP annotations. (#986)
+

Various

+
  • Add a blueprint example. (#946)
  • Add terminal to playground site. (#161)
  • Match the .nvmrc node version to the changes made in commit ec2605b. (#972)
  • PHP : Dispatch available descriptor specs in js_open_process function. (#963)
  • PHP : Give access to command arguments if array type is given in php ^7.4 proc_open function. (#944)
  • Rebuild WordPress. (#987)
  • Update the networking disabled error messages in wp-admin for plugins and themes. (#936)
+

Contributors

+

The following contributors merged PRs in this release:

+

@adamziel @bph @ironnysh @marcarmengou @mho22 @rowasc @seanmorris @swissspidy @tyrann0us

+

[v0.5.9] - 2021-09-29

+

Changed

+

– Breaking: Remoddsaved the PHPBrowser class (##1302)

+

Added

+

– Added CHANGELOG.md to keep track of notable changes (##1302)

+

Original Playground docs source: https://playground.wordpress.net/changelog

]]> + + 55 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Code contributions]]> + https://playground.wordpress.net/contributing-code/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=56 + + Code contributions +

Like all WordPress projects, Playground uses GitHub to manage code and track issues. The main repository is at https://github.com/WordPress/wordpress-playground and the Playground Tools repository is at https://github.com/WordPress/playground-tools/.

+

Contribute to Playground Tools

+

This guide includes links to the main repository, but all the steps and options apply for both. If you're interested in the plugins or local development tools—start there.

+

Browse the list of open issues to find what to work on. The Good First Issue label is a recommended starting point for first-time contributors.

+

Be sure to review the following resources before you begin:

+ +

Contribute Pull Requests

+

Fork the Playground repository and clone it to your local machine. To do that, copy and paste these commands into your terminal:

+
git clone -b trunk --single-branch --depth 1 --recurse-submodules
+
+# replace `YOUR-GITHUB-USERNAME` with your GitHub username:
+git@github.com:YOUR-GITHUB-USERNAME/wordpress-playground.git
+cd wordpress-playground
+npm install
+

Create a branch, make changes, and test it locally by running the following command:

+
npm run dev
+

Playground will open in a new browser tab and refresh automatically with each change.

+

Tip: Troubleshooting: File watcher limit on Linux

+

On Linux, you might see an error like ENOSPC: System limit for number of file watchers reached when running npm run dev. This happens because the Playground repository has more files than the default system limit allows to watch.

+

To fix this, first check your current limit:

+
cat /proc/sys/fs/inotify/max_user_watches
+

If it's around 65,536 or lower, increase it by running:

+
sudo sysctl fs.inotify.max_user_watches=131070
+sudo sysctl -p
+

Then try npm run dev again. This is a common issue on Debian, Ubuntu, and other Linux distributions.

+

When your'e ready, commit the changes and submit a Pull Request.

+

Formatting

+

We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.

+

Running a local Multisite

+

WordPress Multisite has a few restrictions when run locally. If you plan to test a Multisite network using Playground's enableMultisite step, make sure you either change wp-now's default port or set a local test domain running via HTTPS.

+

To change wp-now's default port to the one supported by WordPress Multisite, run it using the --port=80 flag:

+
npx @wp-now/wp-now start --port=80
+

There are a few ways to set up a local test domain, including editing your hosts file. If you're unsure how to do that, we suggest installing Laravel Valet and then running the following command:

+
valet proxy playground.test http://127.0.0.1:5400 --secure
+

Your dev server is now available on https://playground.test.

+

Debugging

+

Use VS Code and Chrome

+

If you're using VS Code and have Chrome installed, you can debug Playground in the code editor:

+
  • Open the project folder in VS Code.
  • Select Run > Start Debugging from the main menu or press F5/fn+F5.
+

Debugging PHP

+

Playground logs PHP errors in the browser console after every PHP request.

+

Original Playground docs source: https://playground.wordpress.net/contributing/code

]]> + + 56 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Coding principles]]> + https://playground.wordpress.net/contributing-coding-standards/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=57 + + Coding principles +

Error messages

+

A good error message informs the user of the following steps to take. Any ambiguity in errors thrown by Playground Public APIs will prompt the developers to open issues.

+

Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps?

+
  • Network error: "Your internet connection twitched. Try to reload the page.
  • 404: "Could not find the file".
  • 403: "The server blocked access to the file".
  • CORS: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers.
+

We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.

+

Public API

+

Playground aims to keep the narrowest possible API scope.

+

Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it.

+
  • Don't expose unnecessary functions, classes, constants, or other components.
+

Blueprints

+

Blueprints are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order.

+

Guidelines

+

Blueprint steps should be concise and focused. They should do one thing and do it well.

+
  • If you need to create a new step, try refactoring an existing one first.
  • If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps.
  • Assume the step would be called more than once.
  • Assume it would run in a specific order.
  • Add unit tests to verify that.
+

Blueprints should be intuitive and straightforward.

+
  • Don't require arguments that can be optional.
  • Use plain argument. For example, slug instead of path.
  • Define constants in virtual JSON files—don't modify PHP files.
  • Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema.
  • Write a function to handle a Blueprint step. Accept the argument of the type you defined.
  • Provide a usage example in the doc string. It's automatically reflected in the docs.
+

Original Playground docs source: https://playground.wordpress.net/contributing/coding-standards

]]> + + 57 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground Contributor Badge]]> + https://playground.wordpress.net/contributing-contributor-badge/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=58 + + Playground Contributor Badge +

This page provides detailed information on the Playground Contributor Badge and the process of requesting it on your WordPress.org profile.

+

---

+

Getting Started

+

Any contribution to the WordPress Playground project is highly valued. The Playground team recognizes contributions across several key areas:

+
  • Playground Code: Making code changes and reviewing the core project.
  • Playground UI: Improving the user interface of the web experience.
  • Documentation: Writing, updating, and reviewing documentation.
  • Translation: Translating any part of the project.
  • Blueprints Gallery: Creating new blueprints or improving existing ones.
+

Playground Contributor Badge

+

To get a Playground Contributor Badge, you must have made at least one eligible contribution from the list above. The team may choose to award the badge for other contributions or a combination of the above at the team’s discretion.

+

Playground Contributor Badge

+

Playground Team Badge

+

If you are currently a contributor and have been actively involved in the Playground project for the past twelve months, you are eligible for a Playground Team Badge.

+

Playground Contributor Badge

+

Requesting a Profile Badge

+

If you meet the criteria, you can request a badge. Please include links to resources (such as GitHub pull requests, issues, or translated strings) that show you have met the criteria. Send a request at the links bellow:

+ +

Request form

+

Playground Contributor Badge

+

To access the request, the user should be logged in with their WordPress.org account and open the Request Membership tab, after submitting the required information. A Playground Team Representative will confirm your contribution and assign the badge. The team will perform a weekly review of contributions and award badges at that time. Updates on new badges awarded will be posted during the Playground Team meeting.

+

Original Playground docs source: https://playground.wordpress.net/contributing/contributor-badge

]]> + + 58 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[How to Lead a Contributor Day Table]]> + https://playground.wordpress.net/contributing-table-lead-guide/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=59 + + Contributor Day Table Leadership Guide +

This guide helps table leads prepare for and manage a WordPress Playground contributor table at WordCamp events.

+

Before Contributor Day

+

Pre-Work Checklist

+
  • Curate "Good First Issues": Review and update the good first issues list on GitHub. These should be straightforward tasks that new contributors can complete independently. If you find a bug that is not on the list but could be part of it, contact the playground team at the Slack channel.
  • Coordinate with the Playground Team: Confirm if Playground team members are available online to provide remote support during the event, especially for flagship WordCamps. Due to timezone differences, align in advance at the #playground channel to check their availability.
  • Connect with Local Contributors: Identify regular contributors in the region attending the event. Check on the #playground Slack Channel if an active community member is participating in the contributor day. This is an opportunity to gather feedback and strengthen community connections.
  • Check the Playground Repository: If you never contribute with the WordPress Playground Repository, you should get familiar with this a good section at the documentation that can guide you to understand the project is Developers > Architecture it will contain information how the project is organized. If you have any questions, please get in touch with the team at the Playground Slack channel.
+

Starting the Day

+

Setup and Onboarding

+
  1. Create Your Agenda: Prepare a flexible checklist of key activities while allowing for organic collaboration. Share it in the project documentation if helpful.
+
  1. Guide Contributors to Slack: Direct everyone to the #playground channel on WordPress Slack. This centralizes communication and enables asynchronous collaboration with late arrivals.
+
  1. Post a Welcome Message: Share an initial message in the Slack channel announcing your presence (in-person or online) and welcoming contributions from everyone.
+
  1. Share Essential Links: Post these resources in the #playground channel:
+ +
  1. Introduce the GitHub Repository: Provide a brief walkthrough of the repository structure, highlighting different packages and their purposes for first-time contributors.
+

During the Day

+

Managing Contributions

+

Encourage Different Contribution Types:

+

Check the contributors' levels, try to understand based on their level how they can contribute to the project in the short window of a contributor day. Ask if the participants need help and redirect them to the related documentation page. Also, encourage them to ask questions at the #playground Slack channel. Here are some suggestions for ways of contributing:

+
  • Documentation improvements and translations.
  • Carefully crafted issues describing problems with actionable solutions.
  • Blueprint creation and plugin demos at the WordPress plugin repository.
  • Testing and product feedback.
+

Foster Collaboration: Look for cross-table opportunities. For example, contributors at the Polyglots/Translation table might translate Playground documentation, or the Core Test team could provide valuable Playground feedback.

+

Collect Feedback: Ask contributors about their experience and note improvement suggestions. Report this in the #playground Slack Channel if possible.

+

After the Event

+

Follow-Up and Support

+
  1. Review Pull Requests: List PRs created during the day and assess their completion likelihood. Most contributions have a short momentum window—engagement within the first two weeks is critical.
+
  1. Set Clear Expectations: For incomplete PRs, follow this approach:
+
  • After one month of inactivity, leave a comment asking if the author plans to complete the work.
  • If no response after two more weeks, inform them that the PR may be taken over by another contributor or closed.
+
  1. Stay Active on Slack: Continue supporting new contributors through the #playground channel, answering questions and helping them become regular contributors.
+
  1. Reflect and Improve: Review collected feedback and your experience to refine this guide for future events. Feel free to submit a Pull Request to this guide!
+

Getting Help

+ +

For more information on contributing to WordPress Playground, see the Contributor Day guide.

+

Original Playground docs source: https://playground.wordpress.net/contributing/table-lead-guide

]]> + + 59 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordCamp Contributor Day]]> + https://playground.wordpress.net/contributing-contributor-day/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=60 + + WordCamp Contributor Day +

WordCamp Contributor Day is an event where the WordPress community comes together to contribute to the WordPress project. This guide focuses on how you can contribute to the WordPress Playground project or how the Playground can assist you in contributing to WordPress Core.

+

Who Can Contribute?

+

Some events will have a dedicated table for the project. The WordPress Playground contributor tables welcome all kinds of contributions, not just from developers. Whether you are a writer, coder, tester, plugin or theme developer, marketer, site owner, or any other type of user, you are encouraged to contribute.

+

We value diverse contributions across various areas, including community building, testing, documentation, and design.

+

How to Contribute to the Playground Project

+

This section outlines how you can contribute directly to the WordPress Playground project and its associated tools:

+
  • Documentation: Enhance our documentation by improving existing content, developing new guides, or translating materials into different languages.
  • Blueprints: Create plugin demos for plugins at the WordPress Plugin repository, or develop new Blueprints to enrich our project documentation.
  • Testing the Playground Environment: Engage in testing the WordPress Playground project itself. You can do this by carefully crafting new issues that describe problems you encounter and suggesting actionable solutions. Test our WordPress web instance (the playground.wordpress.net site), or explore the various applications powered by Playground. Test these tools, observe their functionality, and provide detailed feedback.
  • Product Feedback: Your insights are invaluable for improving the Playground experience. This includes general feedback on the web instance, the application, and any server-side tools.
+

All feedback, including reported issues and test results, can be submitted through our GitHub repository.

+

Follow-up and Continued Engagement

+

While many tasks are completed during the event, your contribution journey doesn't have to end there. You are welcome to continue working on your issues or pull requests after Contributor Day. We anticipate ongoing activity from contributors who take on tasks beyond the event. Please note that if a pull request shows no activity for one month, it may be considered abandoned and subsequently closed.

+

Getting Help and Staying Engaged

+

During Contributor Day, you can find direct assistance and interact with us at the dedicated Playground table. For continuous support and community interaction, you can connect with us on the #playground channel on WordPress Slack or via GitHub.

+

How to use Playground at Contributor Day

+

Now we are going to cover how the Playground can assist you during the Contributor Day. The WordPress Playground VS Code extension and @wp-playground/cli streamline the process of setting up a local WordPress environment. WordPress Playground powers both—no Docker, MySQL, or Apache required.

+

Keep reading to learn how to use these tools for local development when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all Make WordPress teams are fully supported.

+

Getting Started

+

VS Code Playground extension

+

The Visual Studio Code Playground extension is a friendly zero-setup development environment.

+
  1. Open VS Code and navigate to the Extensions tab (View > Extensions).
  2. In the search bar, type _WordPress Playground_ and click Install.
  3. To interact with Playground, click the new icon in the Activity Bar and hit the Start WordPress Server button.
  4. A new tab will open in your browser within seconds.
+

@wp-playground/cli NPM package

+

@wp-playground/cli is a CLI tool that allows you to spin up a WordPress site with a single command. No Docker, MySQL, or Apache are required.

+

Prerequisites

+

@wp-playground/cli requires Node.js 20.18 or newer and NPM. If you haven’t yet, download and install both before you begin.

+

Depending on the Make WordPress team you contribute to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to switch between versions. Find the installation guide here.

+

Running @wp-playground/cli

+

You don’t have to install @wp-playground/cli on your device to use it. Navigate to your plugin or theme directory and start @wp-playground/cli with the following commands:

+
cd my-plugin-or-theme-directory
+npx @wp-playground/cli@latest server --auto-mount
+

Ideas for contributors

+

Create a Gutenberg Pull Request (PR)

+
  1. Fork the Gutenberg repository in your GitHub account.
  2. Then, clone the forked repository to download the files.
  3. Install the necessary dependencies and build the code in development mode.
+
git clone git@github.com:WordPress/gutenberg.git
+cd gutenberg
+npm install
+npm run dev
+

If you’re unsure about the steps listed above, visit the official Gutenberg Project Contributor Guide. Note that in this case, @wp-playground/cli replaces wp-env.

+

Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using @wp-playground/cli:

+
cd gutenberg
+npx @wp-playground/cli@latest server --auto-mount
+

When you’re ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository.

+

Test a Gutenberg PR

+
  1. To test other Gutenberg PRs, checkout the branch associated with it.
  2. Pull the latest changes to ensure your local copy is up to date.
  3. Next, install the necessary dependencies, ensuring your testing environment matches the latest changes.
  4. Finally, build the code in development mode.
+
# copy the branch-name from GitHub #
+git checkout branch-name
+git pull
+npm install
+npm run dev
+
+# In a different terminal inside the Gutenberg directory *
+npx @wp-playground/cli@latest server --auto-mount
+

Test a Gutenberg PR with Playground in the browser

+

You don’t need a local development environment to test Gutenberg PRs—use Playground to do it directly in the browser.

+
  1. Copy the ID of the PR you’d like to test (pick one from the list of open Pull Requests).
  2. Open Playground’s Gutenberg PR Previewer and paste the ID you copied.
  3. Once you click Go, Playground will verify the PR is valid and open a new tab with the relevant PR, allowing you to review the proposed changes.
+

Translate WordPress Plugins with Playground in the browser

+

You can translate supported WordPress Plugins by loading the plugin you want to translate and use Inline Translation. If the plugin developers have added the option, you'll find the Translate Live link on the top right toolbar of the translation view. You can read more about this exciting new option on this Polyglots blog post.

+

Get help and contribute to WordPress Playground

+

Have a question or an idea for a new feature? Found a bug? Something’s not working as expected? We’re here to help:

+ +

Original Playground docs source: https://playground.wordpress.net/contributing/contributor-day

]]> + + 60 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Documentation Contributions]]> + https://playground.wordpress.net/contributing-documentation/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=61 + + Documentation contributions +

WordPress Playground's documentation site is maintained by volunteers like you, who'd love your help.

+

All documentation-related issues are labeled [[Type] Documentation](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22%5BType%5D%20Documentation%22) or [[Type] Developer Documentation](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22%5BType%5D%20Developer%20Documentation%22) in the WordPress/wordpress-playground repository. Browse the list of open issues to find one you'd like to work on. Alternatively, if you believe something is missing from the current documentation, open an issue to discuss your suggestion.

+

How can I contribute?

+

You can contribute by opening an issue in the project repository and describing what you'd like to add or change.

+

If you feel up to it, write the content in the issue description, and the project contributors will take care of the rest.

+

Would you like to see the documentation in your language? Check the Translation section.

+

Forking the repo, edit files locally and opening Pull Requests

+

If you are familiar with markdown, you can fork the wordpress-playground repo and propose changes and new documentation pages by submitting a Pull Request.

+

The process of creating a branch to open new PRs with translated pages on the WordPress/wordpress-playground repository is the same as contributing to other WordPress repositories such as Gutenberg: https://developer.wordpress.org/block-editor/contributors/code/git-workflow/

+

The documentation files (.md files) are stored in Playground's GitHub repository, under /packages/docs/site/docs for English and /packages/docs/site/i18n for other languages.

+

Edit in the browser

+

If logged in GitHub, you can also edit existing files (or add new ones) and submit a PR directly from the GitHub UI:

+
  1. Find the page you'd like to edit or the directory of the chapter you'd like to add a new page to.
  2. Click the Add Files button to add a new file, or click on an existing file and then click the pencil icon to edit it.
  3. GitHub will ask you to fork the repository and create a new branch with your changes.
  4. An editor will open where you can make the changes.
  5. When you're done, click the Commit Changes button and submit a Pull Request.
+

That's it! You've just contributed to the WordPress Playground documentation.

+

This approach means you don't need to clone the repository, set up a local development environment, or run any commands.

+

The downside is that you won't be able to preview your changes. Keep reading to learn how to review your changes before submitting a Pull Request.

+

Local preview

+

Clone the repository and navigate to the directory on your device. Now run the following commands:

+
npm install
+npm run build:docs
+npm run dev:docs
+

The documentation site opens in a new browser tab and refreshes automatically with each change. Continue to edit the relevant file in your code editor and test the changes in real-time.

+

Original Playground docs source: https://playground.wordpress.net/contributing/documentation

]]> + + 61 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Contributing to WordPress Playground project]]> + https://playground.wordpress.net/contributing/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=62 + + Contributing to WordPress Playground project +

WordPress Playground is an open-source project that welcomes contributors of all kinds, from code to design, documentation to triage.

+

How can I contribute?

+ +

Guidelines

+
  • As with all WordPress projects, we want to ensure a welcoming and respectful environment for everyone. Please read our community's Code of Conduct to learn more.
  • Code contributors should review the coding principles.
  • You maintain copyright over any contribution you make. By submitting a Pull Request, you agree to release that code under WordPress Playground License.
+

Triaging issues

+

Want to help sort through open issues and resolve potential bugs? Here's how:

+
  1. Review the list of open issues and find the ones that you can help with. Same goes for the Playground Tools repository.
  2. Read through the description and comments.
  3. If it's a bug you can reproduce, add a descriptive comment or a potential fix.
  4. Otherwise, add a comment with any additional information that may be helpful.
+

A note on contributing and the GPL license

+

WordPress Playground and the WordPress project are strongly rooted in free and open source software. Specifically, WordPress Playground is licenced under GPLv2 (or later) from the Free Software Foundation. You can read the text of the license here and if that feels overwhelming, WordPress.org has a friendly GPL Primer.

+

As such, please be aware of the implications that your contributions will fall under:

+
  • When you contribute, you agree to license your contributions under the GPLv2 (or later) license
  • The GPL license has strong copyleft provisions that ensure all derivative works remain open-source and under the same license terms, thereby promoting a collaborative development environment.
  • The GPL license encourages contributing any changes, bug fixes, or new features back to the original codebase.
  • The GPL license ensures that the project remains free and open-source, not only in terms of cost but also with respect to the freedom to use, modify, and distribute the software.
+

If you have any questions about how the above might affect your contributions, please feel free to reach out on WP Slack and the meta-playground channel.

+

Thank you again for your contributions! 🎉

+

Original Playground docs source: https://playground.wordpress.net/contributing

]]> + + 62 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Releasing packages]]> + https://playground.wordpress.net/contributing-releases/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=63 + + Releasing packages +

Playground publishes its packages to npm using automated CI workflows. This page explains how the release process works and what you need to know when adding new packages.

+

Automated releases

+

The npm packages are published automatically every Monday via GitHub Actions, or manually by maintainers using the workflow dispatch. The workflow bumps versions using Lerna, tags the release, and publishes all public packages to npm.

+

The CI authenticates with npm using OpenID Connect (OIDC) trusted publishing. This is more secure than using long-lived npm tokens because it generates short-lived credentials for each workflow run and ties package provenance directly to the GitHub repository.

+

Adding a new package

+

When you add a new npm package to the monorepo, the automated release workflow won't be able to publish it on the first run. This is an npm security feature: OIDC trusted publishing only works for packages that already exist and have been configured to trust the GitHub repository.

+

Here's what you need to do:

+

1. Publish the package manually

+

First, authenticate with npm on your local machine:

+
npm login
+

Then publish the package for the first time:

+
cd packages/your-new-package
+npm publish --access public
+

This creates the package on the npm registry under your account.

+

2. Configure trusted publishing

+

After the initial publish, go to the package's settings on npmjs.com and set up OIDC trusted publishing:

+
  1. Navigate to your package on npmjs.com
  2. Go to Settings → Configure Trusted Publishers
  3. Add a new trusted publisher with these settings. All of them are case-sensitive!
+
  • Repository owner: WordPress
  • Repository name: wordpress-playground
  • Workflow filename: publish-npm-packages.yml
  • Environment: npm
+

Setting up OIDC trusted publishing on npm

+

3. Transfer ownership (if needed)

+

If you published under your personal account, transfer the package to the @aspect organization or ensure the appropriate team has publish access.

+

Once configured, subsequent releases will work automatically through the CI workflow.

+

Why OIDC can't publish new packages

+

npm's OIDC implementation requires the package to already exist before a trusted publisher can be configured. This is a chicken-and-egg situation by design—it prevents someone from hijacking a package name through a GitHub workflow before the legitimate owner can claim it.

+

The manual first publish establishes ownership, and trusted publishing then provides secure, token-free authentication for all future releases.

+

Original Playground docs source: https://playground.wordpress.net/contributing/releases

]]> + + 63 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Contributions to translations]]> + https://playground.wordpress.net/contributing-translations/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=64 + + Contributions to translations +

Help make WordPress Playground accessible to a global audience by translating its documentation. This guide provides everything you need to know to get started. Contributing translations follows the same workflow as any other documentation change. You can either fork the WordPress/wordpress-playground repository and create a pull request (PR) with your changes or edit pages directly using the GitHub UI.

+

For a detailed guide on the contribution workflow (forking, creating PRs, etc.), please see our documentation contribution guide

+

How Translations Work

+

Playground's documentation site is built with Docusaurus, which handles the internationalization (i18n) features.

+

To learn more about how Docusaurus manages translations, see the Internationalization section of the official Docusaurus documentation.

+

Configuration

+

Available languages are defined in the packages/docs/site/docusaurus.config.js file. For example:

+
i18n: {
+  defaultLocale: 'en',
+  path: 'i18n',
+  locales: ['en', 'fr'],
+  localeConfigs: {
+	en: {
+		label: 'English',
+		path: 'en',
+	},
+	fr: {
+		label: 'French',
+		path: 'fr',
+	},
+  },
+}
+

File Structure

+

All translated documentation pages are located within the packages/docs/site/i18n/ directory, organized by language code.

+

For a language to work correctly, its file structure must mirror the original English documentation found in packages/docs/site/docs.

+

For example, the Spanish (es) translation for docs/main/intro.md must be placed at: packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md.

+

If a translated file does not exist for a specific language, Docusaurus will automatically fall back to the English version of that page.

+

Generating Translation Files

+

When adding a new language, you can generate the necessary JSON files for UI strings (like button labels and navigation items) by running the following command from the packages/docs/site directory:

+
npm run write-translations -- --locale <LANGUAGE_CODE>
+

With the proper i18n docusaurus.config.js configuration and files under i18n when running npm run build:docs from the root of the project, specific folders under dist for each language will be created.

+

Testing Translations Locally

+

To preview your changes for an existing language:

+
  1. Modify or add a translated file in the appropriate language directory, such as packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/.
  2. From the /packages/docs/site directory, run the local development server for your target language. For example, to test Spanish (es):
+

+npm run dev -- --locale es
+
+

The Language Switcher

+

The language switcher is a dropdown menu that allows users to select their preferred language.

+

Documentation Language Switcher

+

Making a language publicly available on the Language Switcher

+

We recommend only adding a language to the switcher when a significant portion of the documentation has been translated. This avoids a poor user experience where switching to a new language results in seeing mostly untranslated English content.

+

As a guideline, a language should be made publicly available in the switcher only when the entire "Documentation" hub is translated, including these key sections:

+ +

All languages are available once the i18n setup for a language is complete and the correct file structure is in place under i18n.

+
  • https://wordpress.github.io/wordpress-playground/
  • https://wordpress.github.io/wordpress-playground/es/
  • https://wordpress.github.io/wordpress-playground/fr/
+

Assuming the fr language is the first language with the Documentation hub pages (Quick Start Guide, Playground web instance, About Playground, Guides,... ) completely translated to French, the docusaurus.config.js should look like this in that branch so npm run build:docs properly generate the fr subsite and only displays the french language in the localeDropdown language switcher.

+
  {
+    "i18n": {
+      "defaultLocale": "en",
+      "path": "i18n",
+      "locales": [
+        "en",
+        "fr"
+      ],
+      "localeConfigs": {
+        "en": {
+          "label": "English",
+          "path": "en"
+        },
+        "fr": {
+          "label": "French",
+          "path": "fr"
+        }
+      }
+    }
+  },
+  {
+    "type": "localeDropdown",
+    "position": "right"
+  }
+

Translation Workflow

+

Follow these steps to translate a page:

+
  1. Check for an Existing Translation Issue: First, search the repository issues to see if a tracking issue for your desired language already exists. If it does, comment on the issue to claim the page(s) you would like to translate.
  2. Create a New Translation Issue: If no issue exists, please create a new one to track the translation progress for the language. You can model it after issue #2202 and use the markdown checklist below to track progress.
  3. Translate the File:
+
  • Check if you have the latest version of the documentation
  • Copy the original .md file from packages/docs/site/docs/... to the corresponding path in the language directory (e.g., packages/docs/site/i18n/<LANGUAGE_CODE>/...). It is crucial to replicate the original file structure.
  • Translate the content of the new file, keeping the original content commented out <!-- English Content -->.
  • The assets are listed at packages/docs/site/static/img/ only place assets inside the translation folder when it requires localized content.
  • Once the translations are ready, check if the docs build script is running properly npm run build:docs.
+
  1. Create a pull request with your changes
+
  • Add a prefix to the title [i18n] to help to identify the translations
  • Describe the pages that you translated
  • Request a review at #playground or #polyglots at wordpress.slack.com
+

We highly recommend submitting pull requests with a small number of translated pages. This approach simplifies the review process and allows for a more gradual and manageable integration of your work.

+

Translation Tracking Template

+

You can use the following markdown in your tracking issue:

+
## Remaining translation pages
+
+<details open>
+<summary><h3>Main</h3></summary>
+
+- about
+  - [ ] build.md
+  - [ ] index.md
+  - [ ] launch.md
+  - [ ] test.md
+- contributing
+  - [ ] code.md
+  - [ ] coding-standards.md
+  - [ ] contributor-badge.md
+  - [ ] contributor-day.md
+  - [ ] contributor-day-table-lead.md
+  - [ ] documentation.md
+  - [ ] index.md
+  - [ ] releases.md
+  - [ ] translations.md
+- guides
+  - [ ] for-plugin-developers.md
+  - [ ] for-theme-developers.md
+  - [ ] github-action-pr-preview.md
+  - [ ] index.md
+  - [ ] providing-content-for-your-demo.md
+  - [ ] wordpress-native-ios-app.md
+- [ ] changelog.md
+- [ ] intro.md
+- [ ] quick-start-guide.md
+- [ ] resources.md
+- [ ] web-instance.md
+
+</details>
+
+<details open>
+<summary><h3>Blueprints</h3></summary>
+
+- [ ] 01-index.md
+- [ ] 02-using-blueprints.md
+- [ ] 03-data-format.md
+- [ ] 04-resources.md
+- [ ] 05-steps.md
+- [ ] 05-steps-shorthands.md
+- [ ] 06-bundles.md
+- [ ] 07-json-api-and-function-api.md
+- [ ] 08-examples.md
+- [ ] 09-troubleshoot-and-debug-blueprints.md
+- [ ] intro.md
+- tutorial
+  - [ ] 01-what-are-blueprints-what-you-can-do-with-them.md
+  - [ ] 02-how-to-load-run-blueprints.md
+  - [ ] 03-build-your-first-blueprint.md
+  - [ ] index.md
+
+</details>
+
+<details open>
+<summary><h3>Developers</h3></summary>
+
+- 03-build-an-app
+  - [ ] 01-index.md
+- 05-local-development
+  - [ ] 01-wp-now.md
+  - [ ] 02-vscode-extension.md
+  - [ ] 03-php-wasm-node.md
+  - [ ] 04-wp-playground-cli.md
+  - [ ] intro.md
+- 06-apis
+  - [ ] 01-index.md
+  - javascript-api
+    - [ ] 01-index.md
+    - [ ] 02-index-html-vs-remote-html.md
+    - [ ] 03-playground-api-client.md
+    - [ ] 04-blueprint-json-in-api-client.md
+    - [ ] 05-blueprint-functions-in-api-client.md
+    - [ ] 06-mount-data.md
+  - query-api
+    - [ ] 01-index.md
+- 07-xdebug
+  - [ ] 01-introduction.md
+  - [ ] 02-getting-started.md
+- 23-architecture
+  - [ ] 01-index.md
+  - [ ] 02-wasm-php-overview.md
+  - [ ] 03-wasm-php-compiling.md
+  - [ ] 04-wasm-php-javascript-module.md
+  - [ ] 05-wasm-php-filesystem.md
+  - [ ] 07-wasm-asyncify.md
+  - [ ] 08-browser-concepts.md
+  - [ ] 09-browser-tab-orchestrates-execution.md
+  - [ ] 10-browser-iframe-rendering.md
+  - [ ] 11-browser-php-worker-threads.md
+  - [ ] 12-browser-service-workers.md
+  - [ ] 13-browser-scopes.md
+  - [ ] 14-browser-cross-process-communication.md
+  - [ ] 15-wordpress.md
+  - [ ] 16-wordpress-database.md
+  - [ ] 17-browser-wordpress.md
+  - [ ] 18-host-your-own-playground.md
+- 24-limitations
+  - [ ] 01-index.md
+- [ ] intro-devs.md
+
+</details>
+

Translating with the GitHub Web Interface

+

If you prefer not to use developer tools, you can easily contribute translations directly on the GitHub website. All you need is a free GitHub account.

+

This guide will show you how to both update an existing translation and add a brand-new one.

+

---

+

Updating an Existing Translation

+
  1. Navigate to the file. Go to the repository and find the file you want to update. Translation files are located in a folder named after their language code. For example, all French translations are in packages/docs/site/i18n/fr/docusaurus-plugin-content-docs/current/.
+
  1. Open the editor. Select the file you wish to edit and click the pencil icon (Edit this file) in the upper right corner.
+

Editing existing translation

+
  1. Fork the repository. GitHub will automatically prompt you to Fork this repository. This creates a personal copy for you to edit safely. Click the button to proceed.
+
  1. Make your changes. The editor will open in your browser. Update the text with your improved translations.
+
  1. Propose your changes. Once you are finished, scroll to the bottom of the page. Add a brief title and description of your changes (e.g., "Fixing typos in French translation") and click the Propose changes button.
+
  1. Create a Pull Request. On the next screen, click the Create pull request button. This will submit your changes to the project maintainers for review.
+

---

+

Adding a New Translation

+
  1. Determine the correct file path. The new file's path and name must mirror the original English file.
+
  • English original: packages/docs/site/docs/main/contributing/documentation.md
  • French translation: packages/docs/site/i18n/fr/docusaurus-plugin-content-docs/current/main/contributing/documentation.md
+
  1. Create the new file. Navigate to the correct language folder (e.g., /packages/docs/site/i18n/fr/docusaurus-plugin-content-docs/current/). Click Add file > Create new file.
+

Creating a new translation

+
  • Pro Tip: In the filename box, you can create new folders by typing the folder name followed by a /. For example, typing main/contributing/documentation.md will create the main and contributing folders automatically.
+
  1. Fork the repository. Just like before, GitHub will prompt you to Fork this repository. Click the button to create your personal copy.
+
  1. Add the translated content. The editor will open with an empty file. For the convenience of reviewers, please copy the content from the original English file and paste it into your new file, wrapping it in comment tags. Add your translation below it.
+
    <!--
+    This is the original English content.
+    It helps reviewers understand the context of the translation.
+    -->
+
+    Ceci est le contenu traduit en français.
+

GitHub UI Editor

+
  1. Commit the new file. When you are done, scroll to the bottom. Add a title for your new file (e.g., "Add French translation for documentation.md") and click the Commit new file button.
+
  1. Create a Pull Request. On the next screen, click Create pull request to submit your new translation for review.
+

Review Process

+

To simplify the review process, please keep the original English text as a comment directly above the translated content.

+
<!--
+👋 Hi! Welcome to WordPress Playground documentation.
+
+Playground is an online tool to experiment and learn about WordPress. This site (Documentation) is where you will find all the information you need to start using Playground.
+-->
+
+👋 Olá! Bem vindo a documentação oficial do WordPress Playground.
+
+WordPress Playground é uma ferramenta online onde podes testar e aprender mais sobre o WordPress. Nesta página(Documentação) irá encontrar todas as informações necessárias para começar a trabalhar com o Playground.
+

This practice also helps the maintenance team identify outdated translations. When the original English content is updated, we can search the codebase for the old text (now in comments) and flag the corresponding translation for review.

+

To find a reviewer fluent in the language of your PR, you can post a request on the Make WordPress Polyglots blog. Be sure to include the locale tag (e.g., #ja for Japanese) to notify the appropriate General Translation Editors (GTEs).

+

When the PR is merged, the translated version of that page should appear under https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}, if you are contributing for the first time request your Contributor Badge.

+

Original Playground docs source: https://playground.wordpress.net/contributing/translations

]]> + + 64 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Using the WordPress Playground Agent Skill]]> + https://playground.wordpress.net/guides-agent-skill-wp-playground/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=65 + + Using the WordPress Playground Agent Skill +

Want an AI assistant that already knows how to spin up WordPress instances, run Blueprints, and debug plugins? The wp-playground agent skill teaches coding agents the WordPress Playground CLI and browser workflows. You describe what you need in plain language. The agent handles the commands.

+

Your coding agent reads the skill reference — a document with CLI flags, procedures, and troubleshooting steps — before responding. This ensures Playground commands run correctly.

+

Prerequisites

+

Before installing the skill, confirm you have:

+
| Requirement | Minimum version       | Check command   |
+| ----------- | --------------------- | --------------- |
+| Node.js     | 20.18                 | `node -v`       |
+| npm / npx   | Included with Node.js | `npx --version` |
+

You also need a coding agent that supports agent skills: Antigravity, Claude Code, Codex, Copilot, Cursor, or Gemini CLI. Make sure your CLI or IDE runs the latest version. Output quality depends on your chosen model.

+

Installation

+

1. Install via terminal

+

Install the skill using the npx skills CLI:

+
npx skills add wordpress/agent-skills --skill wp-playground
+

2. Install manually

+
# Clone agent-skills
+git clone https://github.com/WordPress/agent-skills.git
+cd agent-skills
+
+# Build the distribution
+node shared/scripts/skillpack-build.mjs --clean
+
+# Install into your WordPress project
+node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity,gemini
+

This copies skills into:

+
  • .github/skills/ for VS Code / GitHub Copilot
  • .claude/skills/ for Claude Code
  • .cursor/skills/ for Cursor
  • .agent/skills/ for Antigravity
  • .gemini/skills/ for Gemini CLI
  • .codex/skills/ for Codex
+

Verify installation by checking the skill directory exists for your agent:

+
| Agent          | Skill directory                 |
+| -------------- | ------------------------------- |
+| Claude Code    | `.claude/skills/wp-playground/` |
+| Gemini CLI     | `.gemini/skills/wp-playground/` |
+| GitHub Copilot | `.github/skills/wp-playground/` |
+| Cursor         | `.cursor/skills/wp-playground/` |
+| Antigravity    | `.agent/skills/wp-playground/`  |
+| Codex          | `.codex/skills/wp-playground/`  |
+

Some agents also support listing skills directly:

+
# Claude Code
+claude /skills
+
+# Gemini CLI
+gemini /skills list
+

Use the skill in the terminal

+

With the skill installed, describe your WordPress environment to your coding agent. The agent builds the Blueprint, runs the CLI commands, and starts the server.

+

Open your coding agent in the terminal and type your request:

+
> Run a WordPress instance with my plugin mounted
+

The agent reads the skill reference, detects your project layout, and runs server --auto-mount. The instance starts at http://localhost:9400.

+

Generating content on the fly

+

Need sample data for testing or a demo? Describe the content structure you want:

+
> Run a WordPress with 10 published posts
+

The agent creates a Blueprint with a runPHP step that generates the posts using wp_insert_post().

+

More examples:

+
> Run a WordPress with 3 users where each user has 3 posts
+
> Start a WordPress instance with 5 pages and a custom menu linking to all of them
+
> Create a WordPress site with 20 posts across 4 categories
+

Each prompt produces a complete Blueprint that runs locally, handling user creation, role assignment, post generation, and taxonomy setup through Blueprint steps.

+

Version compatibility testing

+

Does your plugin work on older PHP versions? Ask directly:

+
> Test my plugin on WordPress 6.3 with PHP 7.4
+
> Run my theme on the latest WordPress nightly with PHP 8.5
+

The agent adds --wp and --php flags to match your request. Common combinations:

+
| Scenario          | What to ask                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| Latest stable     | "Run a WordPress instance" (defaults to latest WP, PHP 8.3) |
+| Minimum supported | "Test my plugin on WordPress 6.3 with PHP 7.4"              |
+| Upcoming release  | "Run the WordPress nightly build"                           |
+| Legacy PHP        | "Start WordPress with PHP 7.4"                              |
+

Complex scenarios

+

Combine multiple requirements in a single prompt:

+
> Create a WordPress site with WooCommerce, 3 product categories,
+  10 sample products, and 2 customer accounts — running on PHP 8.2
+
> Run a WordPress instance with my plugin mounted, debug mode enabled,
+  and 5 test posts that include featured images
+

The agent breaks these into the right sequence of Blueprint steps and CLI flags. Each request produces a fully configured, running instance.

+

How the skill works

+

The wp-playground skill is a set of Markdown files that your coding agent loads into its context when your request matches Playground-related patterns. The skill includes:

+
  • SKILL.MD — The main procedure: guardrails, step-by-step workflows, verification checks, and failure modes.
  • references/cli-commands.md — A CLI cheatsheet with every flag and default value.
  • references/blueprint.md — Blueprint structure, common steps, and authoring tips.
  • references/debugging.md — Xdebug setup, path mapping, and troubleshooting steps.
+

Your coding agent reads these files before generating commands, ensuring correct flags and warning you about common pitfalls.

+

Next steps

+ +

Original Playground docs source: https://playground.wordpress.net/guides/agent-skill-wp-playground

]]> + + 65 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[E2E Testing with Playwright and WordPress Playground]]> + https://playground.wordpress.net/guides-e2e-testing-with-playwright/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=66 + + End-to-end testing verifies that your WordPress plugin or theme works correctly from a user's perspective — clicking buttons, filling forms, and navigating pages in a real browser. This guide shows how to combine Playwright with the WordPress Playground CLI to write reliable E2E tests without Docker, databases, or manual setup.

+

This guide assumes familiarity with WordPress plugin or theme development. For an introduction to using Playground in your development workflow, see WordPress Playground for Plugin Developers. For Blueprint configuration details, see Blueprints Getting Started.

+

Prerequisites

+
  • Node.js 20+ and up
  • A WordPress plugin/theme or an entire WordPress site to test
  • Recommended: enable the @typescript-eslint/no-floating-promises ESLint rule to catch missing await on async Playwright calls
+

Project setup

+

Install dependencies

+

From your plugin or theme root directory:

+
npm init -y
+npm install --save-dev @playwright/test @wp-playground/cli
+npx playwright install chromium
+

This installs Playwright as the test runner, the Playground CLI for creating WordPress instances, and the Chromium browser for test execution.

+

Configure Playwright

+

Create a playwright.config.ts file in your project root:

+
import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+	testDir: './tests/e2e',
+	fullyParallel: false,
+	forbidOnly: !!process.env.CI,
+	retries: process.env.CI ? 2 : 0,
+	workers: 1,
+	reporter: 'html',
+	timeout: 120_000,
+	expect: {
+		timeout: 30_000,
+	},
+	use: {
+		screenshot: 'only-on-failure',
+		trace: 'on-first-retry',
+	},
+});
+

WordPress Playground needs more time to start than a typical web app. The 120-second test timeout and 30-second assertion timeout account for WordPress boot time and page loads. Setting workers: 1 prevents port conflicts when multiple tests share a Playground server.

+

Tip: [Using baseURL with dynamic ports]

+

By default, Playground will sign the port 9400. If you want to select a different port, pass port: [NEW_PORT_NUMBER] in the runCLI options to select a different port:

+
const cli = await runCLI({ command: 'server', port: 9500, blueprint });
+

Then add baseURL: "http://localhost:9500" to the use section above. Note that testMatch defaults to **/*.spec.ts — customize it if your test files use a different naming pattern.

+

Tip

+

The WordPress Playground project uses even longer timeouts (300s test, 60s assertion) for its own tests. Start with the values above and increase if your CI environment is slower.

+

First test file

+

Create tests/e2e/plugin.spec.ts:

+
import { test, expect } from '@playwright/test';
+import { runCLI } from '@wp-playground/cli';
+
+let cli: Awaited<ReturnType<typeof runCLI>>;
+
+test.beforeAll(async () => {
+	cli = await runCLI({
+		command: 'server',
+		blueprint: {
+			preferredVersions: { php: '8.3', wp: 'latest' },
+			login: true,
+		},
+	});
+});
+
+test.afterAll(async () => {
+	await cli?.server?.close();
+});
+
+test('WordPress dashboard loads', async ({ page }) => {
+	await page.goto(`${cli.serverUrl}/wp-admin/`);
+	// WordPress core admin elements lack ARIA roles — CSS selectors are acceptable here
+	await expect(page.locator('#wpbody-content')).toBeVisible();
+	await expect(page).toHaveTitle(/Dashboard/);
+});
+

Run the test:

+
npx playwright test
+

Choosing locators

+

Playwright provides several ways to find elements on the page. Prefer locators that reflect how users see the page, falling back to CSS selectors only when necessary.

+

Locator priority (most to least preferred):

+
  1. page.getByRole() — buttons, headings, links, form controls
  2. page.getByLabel() — form inputs with associated labels
  3. page.getByText() — visible text content
  4. page.getByTestId() — elements with data-testid attributes you add to your plugin
  5. page.locator() — CSS or XPath selectors as a last resort
+

WordPress-specific guidance

+

In the WordPress admin, some core elements (admin bar, meta boxes) rely on IDs and CSS classes rather than ARIA roles. However, many elements work well with semantic locators. This means:

+
  • Use semantic locators for buttons, headings, links, form fields, and admin menu items — WordPress renders standard <button>, <input>, <a>, and <h1> elements that getByRole and getByLabel can find.
  • Use data-testid for your own plugin markup — you control the HTML, so add testable attributes.
  • Use CSS selectors for WordPress core layout elements like #wpadminbar or #wpbody-content — these lack ARIA alternatives.
+

Same element, three approaches

+
// ✅ Preferred: semantic locator (works because WP renders a real <button>)
+await page.getByRole('button', { name: 'Save Changes' }).click();
+
+// ⚠️ Acceptable: test ID you added to your plugin markup
+await page.getByTestId('save-settings').click();
+
+// ❌ Avoid: brittle CSS selector tied to WordPress markup
+await page.locator('#submit').click();
+

Tip: [Generate locators automatically]

+

Run npx playwright codegen localhost:9400/wp-admin/ to open a browser and record interactions. Playwright generates locator code as you click, helping you discover which semantic locators work for each element.

+

Auto-waiting and web-first assertions

+

Playwright locators wait automatically for elements to appear, become visible, and become actionable. You do not need manual waitForSelector calls in most cases.

+

Web-first assertions

+

Web-first assertions auto-retry until the condition passes or the timeout expires. Always prefer them over manual checks:

+
// ✅ Web-first assertion (auto-retries until visible or timeout)
+await expect(page.getByText('Settings saved')).toBeVisible();
+
+// ❌ Manual check (no retry — flaky if the element appears after a delay)
+expect(await page.getByText('Settings saved').isVisible()).toBe(true);
+

Soft assertions

+

Use expect.soft() to check multiple things on one page without stopping at the first failure. All failures appear in the test report:

+
await expect.soft(page.getByLabel('API Key')).toHaveValue('test-key-123');
+await expect.soft(page.getByText('Settings saved')).toBeVisible();
+await expect.soft(page.getByRole('heading', { level: 1 })).toContainText('Settings');
+

Writing tests

+

Starting a Playground server

+

The runCLI function starts a local Playground server and returns an object with serverUrl (the URL string) and server (the HTTP server instance). Pass a Blueprint to configure the WordPress instance:

+
const cli = await runCLI({
+	command: 'server',
+	blueprint: {
+		preferredVersions: { php: '8.3', wp: 'latest' },
+		login: true,
+		steps: [
+			{
+				step: 'installPlugin',
+				pluginData: {
+					resource: 'wordpress.org/plugins',
+					slug: 'woocommerce',
+				},
+			},
+		],
+	},
+});
+

Server lifecycle: shared vs. per-test

+

Shared server (beforeAll/afterAll) — one Playground instance serves all tests in a describe block. Faster, but tests can affect each other:

+
test.describe('Plugin settings', () => {
+	test.beforeAll(async () => {
+		cli = await runCLI({ command: 'server', blueprint });
+	});
+	test.afterAll(async () => {
+		await cli?.server?.close();
+	});
+	// Tests share the same WordPress instance
+});
+

Per-test server (beforeEach/afterEach) — each test gets a fresh instance. Slower, but fully isolated:

+
test.beforeEach(async () => {
+	cli = await runCLI({ command: 'server', blueprint });
+});
+test.afterEach(async () => {
+	await cli?.server?.close();
+});
+

Use shared servers when tests only read state (checking pages render). Use per-test servers when tests modify state (creating posts, changing settings).

+

Using Blueprints as test fixtures

+

Blueprints define the WordPress state each test scenario needs. Here are common patterns:

+

Installing a plugin from wordpress.org

+
const blueprint = {
+	preferredVersions: { php: '8.3', wp: 'latest' },
+	login: true,
+	steps: [
+		{
+			step: 'installPlugin',
+			pluginData: {
+				resource: 'wordpress.org/plugins',
+				slug: 'contact-form-7',
+			},
+		},
+	],
+};
+

Installing a local plugin

+

Mount your local plugin directory into the Playground instance:

+
const cli = await runCLI({
+	command: 'server',
+	mount: {
+		'./': '/wordpress/wp-content/plugins/my-plugin',
+	},
+	blueprint: {
+		preferredVersions: { php: '8.3', wp: 'latest' },
+		login: true,
+		steps: [
+			{
+				step: 'activatePlugin',
+				pluginPath: 'my-plugin/my-plugin.php',
+			},
+		],
+	},
+});
+

This maps your current directory to the plugin path inside WordPress, then activates the plugin. Changes to your local files are reflected immediately. The user can set the autoMount property to identify plugins and themes, but the mount property will provide more control to the user to set different folders in the project.

+

Setting options and creating content

+
const blueprint = {
+	login: true,
+	steps: [
+		{
+			step: 'setSiteOptions',
+			options: {
+				blogname: 'Test Site',
+				permalink_structure: '/%postname%/',
+			},
+		},
+		{
+			step: 'runPHP',
+			code: `<?php
+        require '/wordpress/wp-load.php';
+        wp_insert_post([
+          'post_title' => 'Test Post',
+          'post_content' => '<!-- wp:paragraph --><p>Hello World</p><!-- /wp:paragraph -->',
+          'post_status' => 'publish',
+        ]);
+      `,
+		},
+	],
+};
+

Tip

+

Use the Playground Step Library or Pootle Playground to prototype your Blueprint configuration visually before adding it to your test code.

+

Testing WordPress admin pages

+

Navigate to admin pages and interact with the WordPress UI:

+
test('plugin settings page saves options', async ({ page }) => {
+	await page.goto(`${cli.serverUrl}/wp-admin/options-general.php?page=my-plugin`);
+
+	await page.getByLabel('API Key').fill('test-key-123');
+	await page.getByRole('button', { name: 'Save Changes' }).click();
+
+	await expect(page.getByText('Settings saved')).toBeVisible();
+	await expect(page.getByLabel('API Key')).toHaveValue('test-key-123');
+});
+

Handling common admin UI elements

+
// Dismiss WordPress admin notices (WP adds aria-label to dismiss buttons)
+await page.getByRole('button', { name: 'Dismiss this notice' }).first().click();
+
+// Wait for admin bar to load — no ARIA role available, use locator
+await page.locator('#wpadminbar').waitFor();
+
+// Navigate via admin menu
+await page.getByRole('link', { name: 'My Plugin' }).first().click();
+

Testing the front end

+
test('plugin shortcode renders on front end', async ({ page }) => {
+	// Navigate to a page with the shortcode
+	await page.goto(`${cli.serverUrl}/?p=2`);
+
+	// Recommend: add data-testid="my-plugin-widget" to your plugin markup
+	await expect(page.getByTestId('my-plugin-widget')).toBeVisible();
+	await expect(page.getByTestId('my-plugin-widget')).toContainText('Expected content');
+	// Or use CSS if you don't control the markup:
+	// await expect(page.locator(".my-plugin-widget")).toBeVisible();
+});
+
+test('theme displays post correctly', async ({ page }) => {
+	await page.goto(`${cli.serverUrl}/test-post/`);
+
+	await expect(page.getByRole('heading', { level: 1 })).toContainText('Test Post');
+	await expect(page.getByText('Hello World', { exact: true })).toBeVisible();
+});
+

Page Object Model pattern

+

The Page Object Model (POM) wraps page interactions into reusable classes. This reduces duplication and makes tests easier to maintain when your plugin UI changes.

+
// tests/e2e/pages/plugin-settings.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+
+export class PluginSettingsPage {
+	readonly page: Page;
+	readonly apiKeyInput: Locator;
+	readonly saveButton: Locator;
+	readonly successNotice: Locator;
+
+	constructor(page: Page) {
+		this.page = page;
+		this.apiKeyInput = page.getByLabel('API Key');
+		this.saveButton = page.getByRole('button', { name: 'Save Changes' });
+		this.successNotice = page.getByText('Settings saved');
+	}
+
+	async goto(baseUrl: string) {
+		await this.page.goto(`${baseUrl}/wp-admin/options-general.php?page=my-plugin`);
+	}
+
+	async setApiKey(key: string) {
+		await this.apiKeyInput.fill(key);
+		await this.saveButton.click();
+	}
+
+	async expectSaved() {
+		await expect(this.successNotice).toBeVisible();
+	}
+}
+

Use the POM in tests:

+
import { PluginSettingsPage } from './pages/plugin-settings';
+
+test('save plugin settings', async ({ page }) => {
+	const settings = new PluginSettingsPage(page);
+	await settings.goto(cli.serverUrl);
+	await settings.setApiKey('test-key-123');
+	await settings.expectSaved();
+});
+

The Playground project uses this pattern with a WebsitePage class that provides methods like goto(), wordpress(), and getSiteTitle() — encapsulating navigation and WordPress-specific interactions.

+

Testing across PHP and WordPress versions

+

Parameterized tests cover multiple version combinations without duplicating test code:

+
const versionMatrix = [
+	{ php: '8.1', wp: '6.5' },
+	{ php: '8.2', wp: '6.7' },
+	{ php: '8.3', wp: 'latest' },
+];
+
+for (const { php, wp } of versionMatrix) {
+	test.describe(`PHP ${php} + WP ${wp}`, () => {
+		let versionCli: Awaited<ReturnType<typeof runCLI>>;
+
+		test.beforeAll(async () => {
+			versionCli = await runCLI({
+				command: 'server',
+				blueprint: {
+					preferredVersions: { php, wp },
+					login: true,
+					steps: [
+						{
+							step: 'activatePlugin',
+							pluginPath: 'my-plugin/my-plugin.php',
+						},
+					],
+				},
+			});
+		});
+
+		test('admin page loads without errors', async ({ page }) => {
+			await page.goto(`${versionCli.serverUrl}/wp-admin/options-general.php?page=my-plugin`);
+			// WordPress core elements use CSS selectors — no ARIA roles available
+			await expect(page.locator('.error')).not.toBeVisible();
+			await expect(page.locator('#wpbody-content')).toBeVisible();
+		});
+
+		test('front-end output renders', async ({ page }) => {
+			await page.goto(versionCli.serverUrl);
+			await expect(page.getByTestId('my-plugin-widget')).toBeVisible();
+		});
+
+		test.afterAll(async () => {
+			await versionCli?.server?.close();
+		});
+	});
+}
+

The preferredVersions property in the Blueprint controls which PHP and WordPress versions the Playground instance uses. Supported ranges: PHP 7.4–8.5, WordPress 6.3–6.8+, plus latest, nightly, and beta. For type-safe PHP version values, use the SupportedPHPVersion type from @php-wasm/universal.

+

Running tests in CI/CD

+

GitHub Actions

+

Create .github/workflows/e2e-tests.yml:

+
name: E2E Tests
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+        branches: [main]
+
+jobs:
+    e2e:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  cache: 'npm'
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Cache Playwright browsers
+              uses: actions/cache@v4
+              id: playwright-cache
+              with:
+                  path: ~/.cache/ms-playwright
+                  key: playwright-${{ hashFiles('package-lock.json') }}
+
+            - name: Install Playwright browsers
+              if: steps.playwright-cache.outputs.cache-hit != 'true'
+              run: npx playwright install chromium --with-deps
+
+            - name: Run E2E tests
+              run: npx playwright test
+
+            - name: Upload test report
+              uses: actions/upload-artifact@v4
+              if: ${{ !cancelled() }}
+              with:
+                  name: playwright-report
+                  path: playwright-report/
+                  retention-days: 30
+

This workflow installs dependencies, downloads Chromium, runs the tests, and uploads the HTML report as an artifact. The --with-deps flag installs system libraries Chromium needs on Ubuntu.

+

Tip: [Sharding for faster CI]

+

Split tests across multiple CI jobs with Playwright's built-in sharding:

+
npx playwright test --shard=1/3
+npx playwright test --shard=2/3
+npx playwright test --shard=3/3
+

Create three parallel jobs in your workflow matrix, each running a different shard. This reduces total CI time proportionally.

+

For manual PR testing alongside automated E2E tests, see Adding PR Preview Buttons with GitHub Actions.

+

Troubleshooting

+

Timeout errors — Increase timeout in playwright.config.ts. WordPress boot time varies by environment. CI runners often need 120–180 seconds.

+

Port conflicts — Let Playground auto-assign ports. Do not hardcode port numbers in your configuration. The serverUrl property returns the correct URL.

+

Browser not found — Run npx playwright install chromium to download the browser binary. On CI, add --with-deps for system libraries.

+

WordPress not loading — Check your Blueprint syntax against the Blueprint schema. Invalid steps fail silently in some cases.

+

Tests pass locally but fail in CI — CI runners have less memory and CPU. Increase timeouts, reduce parallel workers, and ensure workers: 1 in the config.

+

Debugging tests

+

When a test fails, Playwright provides several tools to investigate:

+

Playwright Inspector — step through tests interactively with a built-in debugger:

+
npx playwright test --debug
+

Trace viewer — inspect a timeline of actions, DOM snapshots, and network requests from a failed test. The trace: "on-first-retry" setting in the config above captures traces automatically:

+
npx playwright show-trace test-results/plugin-spec-ts/trace.zip
+

UI mode — run tests in a visual interface where you can watch, filter, and re-run them:

+
npx playwright test --ui
+

Screenshot on failure — the screenshot: "only-on-failure" setting in the config saves a screenshot whenever a test fails. Find screenshots in the test-results/ directory.

+

Tip

+

Combine --debug with a specific test file to focus your investigation: npx playwright test tests/e2e/settings.spec.ts --debug

+

Next steps

+ +

Original Playground docs source: https://playground.wordpress.net/guides/e2e-testing-with-playwright

]]> + + 66 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground for Plugin Developers]]> + https://playground.wordpress.net/guides-for-plugin-developers/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=67 + + The WordPress Playground is an innovative tool that allows plugin developers to build, test and showcase their plugins directly in a browser environment.

+

This guide will show you how to use WordPress Playground to improve your plugin development workflow, create live demos to showcase your plugin, and simplify your plugin testing and review.

+

Discover how to Build, Test, and Launch your products with WordPress Playground in the About Playground section.

+

Launching a Playground instance with a plugin

+

Plugin in the WordPress plugins directory

+

With WordPress Playground, you can quickly launch a WordPress installation with almost any plugin available in the WordPress Plugins Directory installed and activated. All you need to do is to add the plugin query parameter to the Playground URL and use the slug of the plugin from the WordPress directory as a value. For example: https://playground.wordpress.net/?plugin=create-block-theme

+

Tip

+

You can install and activate several plugins via query parameters by repeating the plugin parameter for every plugin you want to be installed and activated in the Playground instance. For example: https://playground.wordpress.net/?plugin=gutenberg&plugin=akismet&plugin=wordpress-seo.

+

You can also load any plugin from the WordPress plugins directory by setting the installPlugin step of a Blueprint passed to the Playground instance.

+
{
+	"landingPage": "/wp-admin/plugins.php",
+	"login": true,
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "wordpress.org/plugins",
+				"slug": "gutenberg"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Blueprints can be passed to a Playground instance in several ways.

+

Plugin in a GitHub repository

+

A plugin stored in a GitHub repository can also be loaded in a Playground instance via Blueprints.

+

With the pluginData property of the installPlugin blueprint step, you can define a git:directory resource that will build a plugin from the files from a repository in the Playground instance.

+

Use the git:directory resource to load plugin source code from a Git repository. It supports branches, tags, commits, and subdirectories without requiring you to create a ZIP archive first. If your plugin needs a Composer, npm, or other build step, publish a built ZIP artifact and install that artifact with a url resource instead.

+

For example, the following blueprint.json installs a plugin from a GitHub repository:

+
{
+	"landingPage": "/wp-admin/admin.php?page=add-media-from-third-party-service",
+	"login": true,
+	"steps": [
+		{
+			"step": "installPlugin",
+			"pluginData": {
+				"resource": "git:directory",
+				"url": "https://github.com/wptrainingteam/devblog-dataviews-plugin",
+				"ref": "HEAD",
+				"refType": "refname"
+			}
+		}
+	]
+}
+

Tip

+

If your plugin is hosted on GitHub, you can automatically add preview buttons to your pull requests using the Playground PR Preview GitHub Action. This lets reviewers test your changes instantly without any setup. See Adding PR Preview Buttons with GitHub Actions for details.

+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Plugin from code in a file or gist in GitHub

+

By combining the writeFile and activatePlugin steps you can also launch a WP Playground instance with a plugin built on the fly from code stored on a gist or a file in GitHub:

+
{
+	"landingPage": "/wp-admin/plugins.php",
+	"login": true,
+	"steps": [
+		{
+			"step": "login"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/plugins/cpt-books.php",
+			"data": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/custom-post/books.php"
+			}
+		},
+		{
+			"step": "activatePlugin",
+			"pluginPath": "cpt-books.php"
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

The Install plugin from a gist example in the Blueprints Gallery shows how to load a plugin from code in a gist

+

Setting up a demo for your plugin with Blueprints

+

When providing a link to a WordPress Playground instance with some plugins activated, you may also want to customize the initial setup for that Playground instance using those plugins. With Playground's Blueprints you can load/activate plugins and configure the Playground instance.

+

Tip

+

Some useful tools and resources provided by the Playground project to work with blueprints are:

+
  • Check the Blueprints Gallery to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.
  • The WordPress Playground Step Library tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!
  • The Blueprints builder tool allows you edit your blueprint online and run it directly in a Playground instance.
+

Through properties and steps in the Blueprint, you can configure the Playground instance's initial setup, providing your plugins with the content and configuration needed for showcasing your plugin's compelling features and functionality.

+

A great demo with WordPress Playground might require that you load default content for your plugin and theme, including images and other assets. Check out the Providing content for your demo guide to learn more about this.

+

plugins

+

If your plugin has dependencies on other plugins you can use the plugins shorthand to install yours along with any other needed plugins.

+
{
+	"landingPage": "/wp-admin/plugins.php",
+	"plugins": ["gutenberg", "sql-buddy", "create-block-theme"],
+	"login": true
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

landingPage

+

If your plugin has a settings view or onboarding wizard, you can use the landingPage shorthand to automatically redirect to any page in the Playground instance upon loading.

+
{
+	"landingPage": "/wp-admin/admin.php?page=my-custom-gutenberg-app",
+	"login": true,
+	"plugins": ["https://raw.githubusercontent.com/WordPress/block-development-examples/deploy/zips/data-basics-59c8f8.zip"]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

writeFile

+

With the writeFile step you can create any plugin file on the fly, referencing code from a \*.php file stored on a GitHub or Gist.

+

Here’s an example of a plugin that generates Custom Post Types, placed in the mu-plugins folder to ensure the code runs automatically on load:

+
{
+	"landingPage": "/wp-admin/",
+	"login": true,
+	"steps": [
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/mu-plugins/books.php",
+			"data": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/custom-post/books.php"
+			}
+		}
+	]
+}
+

Plugin Development

+

Local plugin development and testing with Playground

+

From a plugins' folder in your local development environment, you can quickly load locally a Playground instance with that plugin loaded and activated.

+

Use the @wp-playground/cli command from your plugin's root directory using your preferred command line program.

+

With Visual Studio Code IDE, you can also use the Visual Studio Code extension while working in the root directory of your plugin.

+

For example:

+
git clone git@github.com:wptrainingteam/devblog-dataviews-plugin.git
+cd devblog-dataviews-plugin
+npx @wp-playground/cli server --auto-mount
+

See your local changes in a Playground instance and directly create PRs in a GitHub repo with your changes

+

With Google Chrome you can synchronize a Playground instance with your local plugin's code and your plugin's GitHub repo. With this connection you can:

+
  • See live (in the Playground instance) your local changes
  • Create PRs in the GitHub repo with your changes
+

Here's a little demo of this workflow in action:

+

Embedded media: https://www.youtube.com/embed/UYK88eZqrjo

+

Check About Playground > Build > Synchronize your playground instance with a local folder and create GitHub Pull Requests for more info.

+

Original Playground docs source: https://playground.wordpress.net/guides/for-plugin-developers

]]> + + 67 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground for Theme Developers]]> + https://playground.wordpress.net/guides-for-theme-developers/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=68 + + The WordPress Playground is an innovative tool that allows theme developers to build, test, and showcase their themes directly in a browser environment.

+

This guide will show you how to use WordPress Playground to improve your theme development workflow, create live demos to showcase your theme, and simplify the theme review process.

+

Discover how to Build, Test, and Launch your products with WordPress Playground in the About Playground section

+

Launching a Playground instance with a theme

+

Themes in the WordPress themes directory

+

With WordPress Playground, you can quickly launch a WordPress installation using any theme available in the WordPress Themes Directory. Simply pass the theme query parameter to the Playground URL like this: https://playground.wordpress.net/?theme=disco.

+

You can also load any theme from the WordPress themes directory by setting the installTheme step of a Blueprint passed to the Playground instance.

+
{
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "twentytwenty"
+			},
+			"options": {
+				"activate": true,
+				"importStarterContent": true
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Themes in a GitHub repository

+

A theme stored in a GitHub repository can also be loaded in a Playground instance with Blueprints.

+

With the themeData property of the installTheme blueprint step, you can define a git:directory resource that will build a theme from the files from a repository in the Playground instance.

+

Use the git:directory resource to load theme source code from a Git repository. It supports branches, tags, commits, and subdirectories without requiring you to create a ZIP archive first. If your theme needs a build step, publish a built ZIP artifact and install that artifact with a url resource instead.

+

For example the following blueprint.json installs a theme from a GitHub repository:

+
{
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "git:directory",
+				"url": "https://github.com/Automattic/themes",
+				"ref": "trunk",
+				"path": "assembler"
+			},
+			"options": {
+				"activate": true
+			}
+		}
+	]
+}
+

Tip

+

If your theme is hosted on GitHub, you can automatically add preview buttons to your pull requests using the Playground PR Preview GitHub Action. This lets reviewers test your changes instantly without any setup. See Adding PR Preview Buttons with GitHub Actions for details.

+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

A blueprint can be passed to a Playground instance in several ways.

+

Setting up a demo theme with Blueprints

+

When providing a link to a WordPress Playground instance with a specific theme activated, you may also want to customize the initial setup for that theme. With Playground's Blueprints you can load, activate, and configure a theme.

+

Tip

+

Some useful tools and resources provided by the Playground project to work with blueprints are:

+
  • Check the Blueprints Gallery to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.
  • The WordPress Playground Step Library tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!
  • The Blueprints builder tool allows you edit your blueprint online and run it directly in a Playground instance.
+

Through properties and steps in the blueprint, you can configure the initial setup of your theme in the Playground instance.

+

To provide a good demo of your theme via Playground, you may want to load it with default content that highlights the features of your theme. Check out the Providing content for your demo guide to learn more about this.

+

resetData

+

With the resetData step, you can remove the default content of a WordPress installation in order to import your own content.

+
"steps": [
+	...,
+	{
+		"step": "resetData"
+	},
+	...
+]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

writeFile

+

With the writeFile step, you can write data to a file at a specified path. You may want to use this step to write custom PHP code in a PHP file inside the mu-plugins folder of the Playground WordPress instance, so the code is executed automatically when the WordPress instance is loaded. One of the things you can do through this step is to enable pretty permalinks for your Playground instance:

+
"steps": [
+	...,
+	{
+		"step": "writeFile",
+		"path": "/wordpress/wp-content/mu-plugins/rewrite.php",
+		"data": "<?php /* Use pretty permalinks */ add_action( 'after_setup_theme', function() { global $wp_rewrite; $wp_rewrite->set_permalink_structure('/%postname%/'); $wp_rewrite->flush_rules(); } );"
+	},
+	...
+]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

updateUserMeta

+

With the updateUserMeta step, you can update any user metadata. For example, you could update the metadata of the default admin user of any WordPress installation:

+
"steps": [
+	...,
+	{
+		"step": "updateUserMeta",
+		"meta": {
+			"first_name": "John",
+			"last_name": "Doe",
+			"admin_color": "modern"
+		},
+		"userId": 1
+	},
+	...
+]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

setSiteOptions

+

With the setSiteOptions step, you can set site options such as the site name, description, or page to use for posts.

+
"steps": [
+	...,
+	{
+		"step": "setSiteOptions",
+		"options": {
+			"blogname": "Rich Tabor",
+			"blogdescription": "Multidisciplinary maker specializing in the intersection of product, design and engineering. Making WordPress.",
+			"show_on_front": "page",
+			"page_on_front": 6,
+			"page_for_posts": 2
+		}
+	},
+	...
+]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

There's also a siteOptions shorthand that can be used instead of the setSiteOptions step.

+

plugins

+

With the plugins shorthand you can set a list of plugins you want to be installed and activated with your theme in the Playground instance.

+
"plugins": ["todo-list-block", "markdown-comment-block"]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

You can also use the installPlugin step to install and activate plugins for your Playground instance but the shorthand way is recommended.

+

login

+

With the login shorthand you can launch your Playground instance with the admin user logged in.

+
 "login": true,
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

You can also use the login step to launch your Playground instance logged in with any specific user.

+

Tip

+

The "Stylish Press" and "Loading, activating, and configuring a theme from a GitHub repository" examples from the Blueprints Gallery are great references for loading, activating, importing content, and configuring a block theme on a Playground instance.

+

Theme development

+

Local theme development and testing with Playground

+

From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the @wp-playground/cli command from your preferred command line program or the Visual Code Studio extension from the Visual Studio Code IDE.

+

For example:

+
git clone git@github.com:WordPress/community-themes.git
+cd community-themes/blue-note
+npx @wp-playground/cli server --auto-mount
+

Design your theme using the WordPress UI and save your changes as Pull Requests

+

You can connect your Playground instance to a GitHub repository and create a Pull Request with the changes you’ve done through the WordPress UI in the Playground instance, leveraging the Create Block Theme plugin. You can also make changes to that theme and export a zip.

+

Note that you'll need the Create Block Theme plugin installed and activated in the Playground instance in order to use this workflow.

+

Embedded media: https://www.youtube.com/embed/94KnoFhQg1g

+

Tip

+

Check About Playground > Build > Save changes done on a Block Theme and create GitHub Pull Requests for more info.

+

Original Playground docs source: https://playground.wordpress.net/guides/for-theme-developers

]]> + + 68 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Adding PR Preview Buttons with GitHub Actions]]> + https://playground.wordpress.net/guides-github-action-pr-preview/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=69 + + The Playground PR Preview action adds a preview button to your pull requests. Clicking the button launches Playground with your plugin or theme installed from the PR branch:

+

PR Preview Button

+

For complete configuration options and advanced features, see the action-wp-playground-pr-preview workflow README.

+

How it works

+

The basic workflow runs on the pull_request event (types opened, synchronize, reopened, edited). It reads pull request metadata, builds a Playground URL that points at the PR branch, and updates the PR description or comment.

+

Forked pull requests need extra care because GitHub makes GITHUB_TOKEN read-only for pull_request workflows from forks. If you need to write a preview button for fork PRs, use pull_request_target only for a small workflow that reads PR metadata and writes the button. If your preview needs a build step, run the build in a separate pull_request workflow and publish the preview from a workflow_run workflow.

+

Warning: This is a regular GitHub Action, not a reusable workflow

+

Reference it as a step inside jobs.<job_id>.steps: (i.e. jobs.<job_id>.steps[*].uses:) — never as jobs.<job_id>.uses: at the job level. The job-level form is valid YAML for reusable workflows, so it is a common mistake (including by AI coding assistants), but it will not work with this action.

+

Basic setup for plugins

+

For plugins without a build step, create .github/workflows/pr-preview.yml:

+
name: PR Preview
+on:
+    pull_request:
+        types: [opened, synchronize, reopened, edited]
+
+jobs:
+    preview:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            pull-requests: write
+        steps:
+            - name: Post Playground Preview Button
+              uses: WordPress/action-wp-playground-pr-preview@v2
+              with:
+                  github-token: ${{ secrets.GITHUB_TOKEN }}
+                  mode: 'append-to-description'
+                  plugin-path: .
+

The plugin-path: . setting points to your plugin directory. For subdirectories like plugins/my-plugin, use plugin-path: plugins/my-plugin.

+

See adamziel/preview-in-playground-button-plugin-example for a live example of this workflow in action.

+

Basic setup for themes

+

For themes, use theme-path instead of plugin-path:

+
name: PR Preview
+on:
+    pull_request:
+        types: [opened, synchronize, reopened, edited]
+
+jobs:
+    preview:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            pull-requests: write
+        steps:
+            - name: Post Playground Preview Button
+              uses: WordPress/action-wp-playground-pr-preview@v2
+              with:
+                  github-token: ${{ secrets.GITHUB_TOKEN }}
+                  theme-path: .
+

Testing PRs from forks

+

Pull requests opened from forked repositories run with a read-only GITHUB_TOKEN, so the default pull_request trigger cannot post or update the preview button. The action may fail with Resource not accessible by integration.

+

Use pull_request_target only for the workflow that posts the preview button:

+
on:
+    pull_request_target:
+        types: [opened, synchronize, reopened, edited]
+

Danger: Security note

+

pull_request_target runs in the context of the base repository and can access repository secrets and a write-capable GITHUB_TOKEN. Do not use it to check out PR code, run files from the PR, install PR dependencies, load a blueprint from the PR branch, or pass PR values into shell commands. Keep permissions as narrow as possible, typically contents: read and pull-requests: write for this action.

+

If you need Composer, npm, tests, or any other step that runs PR code, put that work in a separate pull_request workflow and use workflow_run to publish the preview after the build completes.

+

Button placement

+

By default, the action updates the PR description (mode: append-to-description). To post as a comment instead:

+
with:
+    plugin-path: .
+    mode: comment
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+

The action wraps the button in HTML markers and updates it on subsequent runs. By default, it restores the button if you remove it. To prevent restoration:

+
with:
+    plugin-path: .
+    restore-button-if-removed: false
+

Working with built artifacts

+

For plugins or themes requiring compilation, the workflow involves building the code, exposing it via GitHub releases, and creating a blueprint that references the public URL.

+

Warning: First-time setup: publish the draft release

+

The expose-artifact-on-public-url action uploads built files to a GitHub release tagged ci-artifacts by default. On the first run, GitHub creates this release as a draft, which is not publicly fetchable — the preview button will appear but silently 404 when clicked. Go to your repository's Releases page once and either publish the release or mark it as a pre-release. Subsequent runs reuse the same release, so this is only needed once.

+

Use the two-workflow pattern from the complete artifact documentation:

+
  • A pull_request workflow checks out the PR code, runs the build with read-only permissions, and uploads the ZIP as a GitHub Actions artifact.
  • A workflow_run workflow runs only after that build succeeds. It has contents: write and pull-requests: write, exposes the uploaded ZIP on a public release URL, builds a Blueprint that installs that ZIP, and posts the preview button.
+

Keep secrets and write permissions out of the build workflow. The publish workflow should not check out or run PR code. The artifacts-to-keep setting controls how many builds to retain per PR. For themes, change installPlugin to installTheme.

+

See adamziel/preview-in-playground-button-built-artifact-example for a complete working example.

+

Custom blueprints

+

Use blueprints to configure the Playground environment. You can install additional plugins, set WordPress options, import content, or run custom PHP.

+

For the canonical pattern of installing a plugin straight from a GitHub repository — and when to publish a built ZIP instead because your plugin needs a Composer or npm build step — see Plugin in a GitHub repository.

+

Example installing your plugin with WooCommerce:

+
jobs:
+    create-blueprint:
+        name: Create Blueprint
+        runs-on: ubuntu-latest
+        outputs:
+            blueprint: ${{ steps.blueprint.outputs.result }}
+        steps:
+            - name: Create Blueprint
+              id: blueprint
+              uses: actions/github-script@v7
+              with:
+                  script: |
+                      const blueprint = {
+                        steps: [
+                          {
+                            step: "installPlugin",
+                            pluginData: {
+                              resource: "git:directory",
+                              // Use head.repo.full_name, not context.repo. PRs from forks
+                              // live on the contributor's fork, not the base repository —
+                              // pointing at context.repo.* will 404 for every fork PR.
+                              url: `https://github.com/${context.payload.pull_request.head.repo.full_name}.git`,
+                              ref: context.payload.pull_request.head.sha,
+                              refType: "commit",
+                              path: "/"
+                            }
+                          },
+                          {
+                            step: "installPlugin",
+                            pluginData: {
+                              resource: "wordpress.org/plugins",
+                              slug: "woocommerce"
+                            }
+                          }
+                        ]
+                      };
+                      return JSON.stringify(blueprint);
+                  result-encoding: string
+
+    preview:
+        needs: create-blueprint
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            pull-requests: write
+        steps:
+            - uses: WordPress/action-wp-playground-pr-preview@v2
+              with:
+                  github-token: ${{ secrets.GITHUB_TOKEN }}
+                  blueprint: ${{ needs.create-blueprint.outputs.blueprint }}
+

Or reference an external blueprint:

+
with:
+    blueprint-url: https://example.com/path/to/blueprint.json
+

See Blueprints documentation for all available steps and configuration options.

+

Template customization

+

Customize the preview content using template variables:

+
with:
+    plugin-path: .
+    description-template: |
+        ### Test this PR in WordPress Playground
+
+        {{PLAYGROUND_BUTTON}}
+
+        **Branch:** {{PR_HEAD_REF}}
+

Available variables: {{PLAYGROUND_BUTTON}}, {{PLUGIN_SLUG}}, {{THEME_SLUG}}, {{PR_NUMBER}}, {{PR_TITLE}}, {{PR_HEAD_REF}}, and more.

+

See the workflow README for the complete list.

+

Artifact exposure

+

The expose-artifact-on-public-url action uploads built files to a single release (tagged ci-artifacts by default). Each artifact gets a unique filename like pr-123-abc1234.zip. Old artifacts are automatically cleaned up based on artifacts-to-keep.

+

Configuration options: Expose Artifact Inputs

+

Troubleshooting

+

Invalid workflow file or jobs.<id>.uses error: You referenced the action as a reusable workflow. Move uses: WordPress/action-wp-playground-pr-preview@v2 into the job's steps: list (as an item under jobs.<job_id>.steps:), not directly under the job. See How it works.

+

Button not appearing: The workflow file must exist on the default branch before it runs on PRs. Check the Actions tab for errors.

+

Resource not accessible by integration: The PR was opened from a fork and the default pull_request trigger cannot write. Use pull_request_target only for the preview-button workflow described in Testing PRs from forks. If you need to build or run PR code, use the two-workflow artifact pattern in Working with built artifacts.

+

Button appears but preview fails to load (404): For built-artifact workflows, the ci-artifacts release is still a draft. Publish it once from the Releases page. See Working with built artifacts.

+

plugin-path or theme-path resolves to an empty directory: The path is relative to the repository root, not to the workflow file. Use . for repo-root plugins, plugins/my-plugin for subdirectories.

+

Git ref refs/heads/<branch> not found on a fork PR: Your blueprint uses context.repo.owner/context.repo.repo to build the git:directory resource URL, which points at the base repository. Fork PRs live on the contributor's fork — use context.payload.pull_request.head.repo.full_name and head.sha with refType: "commit" instead. Repository URLs with or without a trailing .git suffix are supported.

+

Blueprint references a legacy ZIP-from-repo proxy service and times out: Look in your blueprint for resource URLs pointing at ZIP-from-repo proxy endpoints, then switch source-based previews to the git:directory resource (shown in Custom blueprints), which fetches directly from GitHub. For plugins or themes that need a build step, publish a built ZIP artifact and install that artifact with a url resource instead.

+

Plugin/theme not activated: Check the browser console for PHP errors. Dependencies may be missing, or the plugin's main file may not match the directory name.

+

Permissions errors: Ensure the job declares permissions: pull-requests: write (and contents: write for built-artifact workflows).

+

More: workflow README

+

Other ways of previewing a git repository

+

Embedded media: https://www.youtube.com/embed/2VQkCPYyabQ?si=g5zkAZelHZ9bkN1X

+

Examples

+ +

Next steps

+
  • Add demo content (guide)
  • Create custom blueprints (docs)
+

Original Playground docs source: https://playground.wordpress.net/guides/github-action-pr-preview

]]> + + 69 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[📖 Guides]]> + https://playground.wordpress.net/guides/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=70 + + Guides +

In this section we present a selection of guides that will help you to both work with, and to better understand, a variety of topics related to WordPress Playground.

+

PHP code snippets and embeds

+

Embed runnable PHP snippets in any web page with the <php-snippet> web component, or share full PHP examples via the standalone PHP Playground at playground.wordpress.net/php-playground.html. One script tag, lazy-loaded runtime, shared across every snippet on the page.

+

WordPress Playground for Everyone

+

Think Playground is only for developers? Think again. This guide shows how WordPress Playground helps beginners, site owners, and everyday users experiment safely — no technical expertise required.

+

How to ship a real WordPress site in a native iOS app via Playground?

+

Check "Blocknotes", the first app to run WordPress natively on iOS via WordPress Playground. It showcases the potential for seamless mobile web integration using WebAssembly and the WordPress block editor.

+

Providing content for your demo with WordPress Playground

+

To provide a good demo of your theme or plugin via Playground, you may want to load it with default content that highlights the features of your product. Check this guide to learn how to do so.

+

WordPress Playground for Theme Developers

+

This guide will show you the essential settings to fully create a theme demo using WordPress Playground and how you can leverage it during the building stage.

+

WordPress Playground for Plugin Developers

+

This guide will show you the basic settings to showcase your plugin using WordPress Playground and how to use it while developing your plugin.

+

Adding PR Preview Buttons with GitHub Actions

+

Learn how to automatically add one-click preview buttons to your pull requests. When someone opens a PR on your plugin or theme repository, they get an instant link to test the changes in a fully configured WordPress instance running in the browser.

+

Using the WordPress Playground Agent Skill

+

Automate WordPress Playground workflows with Claude Code. Learn how to install the wp-playground agent skill and use it for local testing, Blueprint execution, snapshot building, version switching, and debugging.

+

Programmatic Usage of Playground CLI

+

Learn how to use the runCLI function to control WordPress Playground programmatically from JavaScript/TypeScript for automation, end-to-end testing, and CI/CD pipelines.

+

E2E Testing with Playwright and WordPress Playground

+

Set up automated end-to-end tests for your WordPress plugins and themes using Playwright and the WordPress Playground CLI.

+

Original Playground docs source: https://playground.wordpress.net/guides

]]> + + 70 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[PHP code snippets and embeds]]> + https://playground.wordpress.net/guides-php-code-snippets/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=71 + + PHP code snippets and embeds +

WordPress Playground ships two ready-made ways to put runnable PHP — and the full WordPress runtime — directly into a web page or a shareable URL. No PHP server, no setup, just a browser.

+
  • <php-snippet> web component — drop one <script> tag into your blog post, docs site, or readme to embed multiple runnable PHP snippets that share a single Playground runtime.
  • Standalone PHP Playground — a full-page PHP editor at playground.wordpress.net/php-playground.html with a shareable URL.
+

Embedding with <php-snippet>

+

The <php-snippet> custom element renders a syntax-highlighted code block with a Run button. Multiple snippets on the same page share a single hidden Playground runtime that is downloaded only when the visitor clicks Run for the first time.

+

Quick start

+
<script
+	type="module"
+	src="https://playground.wordpress.net/php-code-snippet.js"
+></script>
+
+<php-snippet name="hello.php">
+	<script type="application/x-php">
+<?php
+echo "Hello from PHP " . phpversion();
+	</script>
+</php-snippet>
+

That's the whole integration. The script is around 5 KB gzipped and contains no PHP or WordPress — those are fetched lazily on the first Run click.

+

Why a <script type="application/x-php"> wrapper?

+

Browsers ignore the contents of script tags whose type they don't understand. That means you can put PHP code that contains literal < characters (HTML strings, generics, comparisons) inside the wrapper without escaping anything.

+

If your snippet has no characters that need escaping, you can put the code directly inside <php-snippet>:

+
<php-snippet name="add.php">
+	&lt;?php echo 1 + 2;
+</php-snippet>
+

You can also load the code from a separate file:

+
<php-snippet name="lazy-load.php" src="./snippets/lazy-load.php"></php-snippet>
+

WordPress is available

+

Each snippet runs inside a real WordPress installation. require '/wordpress/wp-load.php' brings in the core APIs:

+
<php-snippet name="lazy-load-images.php">
+	<script type="application/x-php">
+<?php
+require '/wordpress/wp-load.php';
+
+$html = '<article>
+    <img src="hero.jpg" alt="Hero">
+    <img src="inline.jpg" alt="Inline">
+</article>';
+
+$tags = new WP_HTML_Tag_Processor( $html );
+while ( $tags->next_tag( 'img' ) ) {
+    $tags->set_attribute( 'loading', 'lazy' );
+    $tags->add_class( 'responsive' );
+}
+
+echo $tags->get_updated_html();
+	</script>
+</php-snippet>
+

How runtime sharing works

+

The first time a visitor clicks Run on any snippet on the page, the component:

+
  1. Lazy-loads the Playground client (https://playground.wordpress.net/client/index.js),
  2. Creates one hidden iframe pointing at https://playground.wordpress.net/remote.html,
  3. Boots PHP and WordPress inside it.
+

Every later Run — on the same snippet or any other — calls client.run({ code }) against that same runtime. No additional downloads, no extra processes. A page with five snippets pays the runtime cost once.

+

While the boot is in progress, every snippet that has its Run clicked shows the same staged progress bar (download → install → ready) drawn from the live progress events Playground emits internally.

+

Sharing a blueprint across snippets

+

If several snippets need the same baseline — a mu-plugin, a couple of files, a configured option — drop a single <script type="application/json"> on the page that contains a JSON Blueprint, and point each snippet at it with a blueprint attribute:

+
<script id="toolkit" type="application/json">
+{
+  "steps": [
+    {
+      "step": "writeFile",
+      "path": "/wordpress/wp-content/mu-plugins/toolkit.php",
+      "data": "<?php\nfunction toolkit_say($s) { return strtoupper($s); }"
+    }
+  ]
+}
+</script>
+
+<php-snippet name="a.php" blueprint="toolkit">
+  <script type="application/x-php">
+<?php require '/wordpress/wp-load.php'; echo toolkit_say('hello');
+  </script>
+</php-snippet>
+
+<php-snippet name="b.php" blueprint="toolkit">
+  <script type="application/x-php">
+<?php require '/wordpress/wp-load.php'; echo toolkit_say('world');
+  </script>
+</php-snippet>
+

Browsers don't execute scripts whose type they don't recognize, so the JSON sits inert until the component reads it. The blueprint is JSON-stringified and folded into the runtime cache key, so two snippets with the same blueprint share one runtime boot. Two snippets with different blueprint values get separate runtimes — usually what you want.

+

The blueprint attribute accepts either an id or any CSS selector. Any element will do — <script type="application/json"> is recommended because the HTML parser treats its contents as raw text, so a literal <?php inside the JSON is harmless. A <template> works too, but its content is parsed as HTML, and the <? in <?php is treated as the start of a bogus comment that runs to the next >. That can swallow the closing </template> and quietly break the page. If you do use a <template>, escape < as \u003c in the JSON.

+

Editable snippets

+

Add the editable attribute and visitors can tweak the code before clicking Run. The keystrokes go into a transparent textarea overlaid on the highlighted code, so the syntax colors update as they type.

+
<php-snippet name="scratch.php" editable>
+	<script type="application/x-php">
+<?php
+$nums = range(1, 10);
+echo "Sum: " . array_sum($nums);
+	</script>
+</php-snippet>
+

Useful for "now you try" sections in tutorials, or for letting readers experiment with their own values. Edits live only in the page — there's no persistence — so a refresh resets the snippet to its initial code.

+

Attributes

+
| Attribute            | Default                              | Purpose                                       |
+| -------------------- | ------------------------------------ | --------------------------------------------- |
+| `name`               | `snippet.php`                        | Filename label shown in the snippet header    |
+| `php`                | `8.4`                                | PHP version (see [supported versions][php])   |
+| `wp`                 | `latest`                             | WordPress version                             |
+| `src`                | —                                    | Load PHP from a URL instead of inline         |
+| `editable`           | (off)                                | Let visitors edit the code before running     |
+| `blueprint`          | —                                    | Id or CSS selector of a `<script type="application/json">` (or `<template>`) containing a JSON Blueprint to run before the snippet |
+| `playground-origin`  | `https://playground.wordpress.net`   | Override the runtime origin (local dev, etc.) |
+

Snippets that share the same php, wp, and playground-origin values share one runtime; mixing different versions on the same page boots a separate runtime per combination.

+

[php]: /developers/apis/query-api/#available-options

+

Standalone PHP Playground

+

For full-page editing or sharing a one-off snippet via URL, use the standalone PHP Playground at:

+

playground.wordpress.net/php-playground.html

+

It's a side-by-side editor and preview with PHP and WordPress version selectors. The current code, PHP version, and WordPress version are encoded into the URL fragment, so you can share a working example by copying the URL.

+

You can embed it in any page with an iframe:

+
<iframe
+	src="https://playground.wordpress.net/php-playground.html#eyJjb2RlIjoiPD9waHBcblxuZWNobyBcIkkgYW0gYSBjb2RlIHNuaXBwZXQhXCI7XG4iLCJwaHAiOiI4LjQifQ=="
+	width="100%"
+	height="600"
+></iframe>
+

The fragment is a base64-encoded JSON payload of { code, php, wp }.

+

Standalone PHP Playground <iframe> vs. <php-snippet> — which should I use?

+
| Use case                                                          | Pick                |
+| ----------------------------------------------------------------- | ------------------- |
+| Multiple read-only runnable examples in a docs page or blog post  | `<php-snippet>`     |
+| Customizations, e.g. read-only code vs editable code  | `<php-snippet>`     |
+| A single code example you don't want to load foreign scripts on your site | Standalone PHP Playground |
+

Original Playground docs source: https://playground.wordpress.net/guides/php-code-snippets

]]> + web component, or share full PHP demos via the standalone PHP Playground.]]> + 71 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground for Everyone]]> + https://playground.wordpress.net/guides-playground-for-everyone/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=72 + + WordPress Playground for Everyone +

WordPress Playground lets you run WordPress instantly—no server, no setup, no risk. It works in your browser at playground.wordpress.net, and developers can also use it via CLI, Node.js, or embedded in their own apps. But you don't need to be technical to benefit from it.

+

Watch this quick overview:

+

Embedded media: https://www.youtube.com/embed/8_rH2k-OQ8E

+

Think of It Like a Car Simulator

+

A car simulator gives you a steering wheel, pedals, and virtual streets. Practice driving, hit cones, make mistakes — nothing bad happens. No real car gets damaged. Want to try again? Just restart.

+

WordPress Playground works the same way. It gives you a complete WordPress site to experiment with, but nothing you do affects any real website. Make changes, break things, learn from mistakes — then start fresh whenever you want.

+

WordPress Playground Landing Page

+

What Can You Do with Playground?

+

When you visit playground.wordpress.net, you get a WordPress site running entirely in your browser. You can:

+
  • Install plugins and themes
  • Edit pages and create content
  • Change WordPress and PHP versions
  • Explore features you've never tried before
+

By default, WordPress Playground loads a landing page to introduce some of the features of Playground and where you can learn more about it. But you can also load a vanilla WordPress version without the landing page. At the Launching Playground panel, one option is to load a vanilla WordPress version.

+
  1. Open Launch WordPress Panel
+

Launch WordPress Panel

+
  1. Select to load a Vanilla WordPress version
+

Launching Vanilla WordPress

+

If You're Learning WordPress

+

Are you new to WordPress or trying to understand features like the Site Editor or the new features of the latest WordPress Release? Playground is your perfect practice space.

+

Explore How Pages Are Built

+

Playground logs you in as an administrator, so you can edit any page. Click Edit for editing posts and Edit Site to update the website layout in the top toolbar to open the editor.

+

Editing WordPress websites

+

Want to understand how a page layout was created? Open the List View (the three horizontal lines icon) to see every block that makes up the page.

+

Site Editor List view

+

You can inspect columns, headings, images, and buttons — and see exactly how they're arranged. This is a powerful way to learn by example.

+

Explore the Blueprint Library

+

At the Launch WordPress Playground panel, you will have access to the Blueprint Library, a set of more than 40 blueprints to inspire you and try different types of websites with WordPress Playground, Art Gallery, E-commerce, and Web Portfolio are some of the examples.

+
  1. Open the Blueprint gallery at the Playground Launch Panel
+

Open blueprint Gallery

+
  1. Navigate and select the Blueprint to launch at WordPress Playground
+

Open blueprint Gallery

+

Try New Features Safely

+

When the WordPress team releases new features, you can test them in Playground before they affect your real site. Select any WordPress version from the settings panel to explore what's new — or what's coming next.

+

If You Own a WordPress Site

+

Running a live website means every change risks breaking something. Playground lets you test before you commit.

+

Test Plugins Before Installing

+

Curious about a new SEO plugin? Want to compare two contact form options? Install them in Playground first:

+
  1. Open playground.wordpress.net
  2. Go to Plugins → Add New
  3. Search for and install any plugin
  4. Test it thoroughly
+

Your real site stays untouched while you evaluate whether the plugin fits your needs.

+

Installing Plugins

+

Preview Theme Changes

+

Thinking about switching themes? Test your new theme in Playground to see how it handles your content — without disrupting your visitors.

+

Compare Options Side by Side

+

Open multiple browser tabs with different Playground setups. Compare plugin A versus plugin B, or see how your content looks in different themes. Make informed decisions before touching your production site.

+

Your Real Site Stays Safe

+

Every Playground runs independently in your browser. Nothing syncs to any external server, and nothing affects your live WordPress installation.

+

If You Use WordPress Daily

+

Even experienced WordPress users benefit from a safe testing environment.

+

Make Design Experiments

+

Want to try a different font size? Adjust spacing? Change colors? Load a Playground with the same theme that you are using in production and edit it freely:

+
  1. Open any page in the editor
  2. Select a block and modify its settings
  3. See the results immediately
+

If you like what you see, recreate those changes on your real site. If not, just close the tab — no cleanup required.

+

Yes, You Can Save Your Work

+

Playground doesn't have to be temporary. You can save your progress and return to it later.

+

Save to Your Browser

+
  1. Now WordPress Playground teels you if your Playground instance is unsaved on the top right
  2. Click on Save (yellow button)
  3. Set the name of your instance
+

Saving Playgrounds

+

Playground generates a unique link for your saved site. Bookmark it, and you can return to exactly where you left off.

+

Download as a ZIP File

+

Need to move your work elsewhere? Choose Download as .zip to export your entire Playground — including plugins, themes, and content. You can restore it later or even host it on a real server.

+

Tip: Keep Your Playground Link

+

When you save to the browser, copy the unique URL it generates. That link is your way back to your saved work.

+

Next Steps

+

Now that you know Playground is for everyone, explore further:

+ +

Original Playground docs source: https://playground.wordpress.net/guides/playground-for-everyone

]]> + + 72 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Programmatic Usage of Playground CLI]]> + https://playground.wordpress.net/guides-programmatic-playground-cli/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=73 + + Programmatic Usage of Playground CLI +

The Playground CLI can also be controlled programmatically from your JavaScript/TypeScript code using the runCLI function. This gives you direct access to all CLI functionalities within your code, which is useful for automating end-to-end tests. The options you pass to runCLI map directly to the CLI flags.

+

Embedded media: https://www.youtube.com/embed/rmNf3CfXbtA?si=cduqQYbBWc6zAPVj

+

Running a WordPress instance with a specific version

+

Using the runCLI function, you can specify options like the PHP and WordPress versions. In the example below, we request PHP 8.3, the latest version of WordPress, and to be automatically logged in. All supported arguments are defined in the RunCLIArgs type.

+
import { runCLI } from "@wp-playground/cli";
+
+const cliServer = await runCLI({
+  command: 'server',
+  php: '8.3',
+  wp: 'latest',
+  login: true,
+});
+

Run the code above using your preferred TypeScript runtime, e.g. tsx:

+
npx tsx my-script.ts
+

Setting a blueprint

+

You can provide a blueprint in two ways: either as an object literal directly passed to the blueprint property, or as a string containing the path to an external .json file.

+
import { runCLI, RunCLIServer } from "@wp-playground/cli";
+
+const cliServer: RunCLIServer = await runCLI({
+  command: 'server',
+  wp: 'latest',
+  blueprint: {
+    steps: [
+        {
+          "step": "setSiteOptions",
+          "options": {
+              "blogname": "Blueprint Title",
+              "blogdescription": "A great blog description"
+          }
+        }
+    ],
+  },
+});
+

For full type-safety when defining your blueprint object, you can import and use the BlueprintDeclaration type from the @wp-playground/blueprints package:

+
import type { BlueprintDeclaration } from '@wp-playground/blueprints';
+
+const myBlueprint: BlueprintDeclaration = {
+  landingPage: "/wp-admin/",
+  steps: [
+    {
+      "step": "installTheme",
+      "themeData": {
+        "resource": "wordpress.org/themes",
+        "slug": "twentytwentyone"
+      },
+      "options": {
+        "activate": true
+      }
+    }
+  ]
+};
+

Mounting a plugin programmatically

+

You can mount local directories programmatically using runCLI. The options mount and mount-before-install are available. The hostPath property expects a path to a directory on your local machine. This path should be relative to where your script is being executed.

+
import { runCLI } from "@wp-playground/cli";
+
+const cliServer = await runCLI({
+  command: 'server',
+  login: true,
+  'mount-before-install': [
+    {
+      hostPath: './[my-plugin-local-path]',
+      vfsPath: '/wordpress/wp-content/plugins/my-plugin',
+    },
+  ],
+});
+

Combining mounts with blueprints

+

You can combine mounting parts of the project with blueprints, for example:

+
import { runCLI, RunCLIServer } from "@wp-playground/cli";
+
+const cliServer: RunCLIServer = await runCLI({
+    command: 'server',
+    php: '8.3',
+    wp: 'latest',
+    login: true,
+    mount: [
+        {
+            "hostPath": "./plugin/",
+            "vfsPath": "/wordpress/wp-content/plugins/playwright-test"
+        }
+    ],
+    blueprint: {
+        steps: [
+            {
+                "step": "activatePlugin",
+                "pluginPath": "/wordpress/wp-content/plugins/playwright-test/plugin-playwright.php"
+            }
+        ]
+    }
+});
+

Automated testing

+

Integration testing with Vitest

+

The programmatic API is excellent for automated testing. Here's a complete example using Vitest:

+
import { describe, test, expect, afterEach } from 'vitest';
+import { runCLI, RunCLIServer } from "@wp-playground/cli";
+
+describe('My Plugin Tests', () => {
+  const cliServer: RunCLIServer;
+
+  afterEach(async () => {
+    if (cliServer) {
+      // RunCLIServer exposes Symbol.asyncDispose as its public async cleanup API.
+      await cliServer[Symbol.asyncDispose]();
+    }
+  });
+
+  test('plugin activates successfully', async () => {
+    cliServer = await runCLI({
+      command: 'server',
+      mount: [
+        {
+          hostPath: './my-plugin',
+          vfsPath: '/wordpress/wp-content/plugins/my-plugin'
+        }
+      ],
+      blueprint: {
+        steps: [
+          {
+            step: 'activatePlugin',
+            pluginPath: '/wordpress/wp-content/plugins/my-plugin/plugin.php'
+          }
+        ]
+      }
+    });
+
+    const homeUrl = new URL('/', cliServer.serverUrl);
+    const response = await fetch(homeUrl);
+
+    expect(response.status).toBe(200);
+    const html = await response.text();
+    expect(html).toContain('My Plugin');
+  });
+
+  test('plugin settings page loads', async () => {
+    cliServer = await runCLI({
+      command: 'server',
+      login: true, // Auto-login as admin
+      mount: [
+        {
+          hostPath: './my-plugin',
+          vfsPath: '/wordpress/wp-content/plugins/my-plugin'
+        }
+      ],
+      blueprint: {
+        steps: [
+          {
+            step: 'activatePlugin',
+            pluginPath: '/wordpress/wp-content/plugins/my-plugin/plugin.php'
+          }
+        ]
+      }
+    });
+
+    const settingsUrl = new URL(
+      '/wp-admin/options-general.php?page=my-plugin',
+      cliServer.serverUrl
+    );
+    const response = await fetch(settingsUrl);
+
+    // Note: A plain `fetch` call does not send the admin session cookie set by `login: true`,
+    // so this request is typically redirected to the login page instead of returning 200.
+    expect(response.status).toBe(302);
+  });
+});
+

Testing with different WordPress/PHP versions

+
test('plugin works with WordPress 6.4 and PHP 8.3', async () => {
+  cliServer = await runCLI({
+    command: 'server',
+    php: '8.3',
+    wp: '6.4',
+    mount: [
+      {
+        hostPath: './my-plugin',
+        vfsPath: '/wordpress/wp-content/plugins/my-plugin'
+      }
+    ],
+    blueprint: {
+      steps: [
+        {
+          step: 'activatePlugin',
+          pluginPath: '/wordpress/wp-content/plugins/my-plugin/plugin.php'
+        }
+      ]
+    }
+  });
+
+  const homeUrl = new URL('/', cliServer.serverUrl);
+  const response = await fetch(homeUrl);
+
+  expect(response.status).toBe(200);
+});
+

Advanced configuration

+

Skip WordPress and SQLite setup

+

When you only need to test PHP code without WordPress, you can skip the setup for faster testing:

+
import { runCLI } from "@wp-playground/cli";
+
+const cliServer = await runCLI({
+    command: 'server',
+    php: '8.3',
+    wordpressInstallMode: 'do-not-attempt-installing',
+    skipSqliteSetup: true,
+});
+
+// Test PHP version
+await cliServer.playground.writeFile(
+  '/wordpress/version.php',
+  '<?php echo phpversion(); ?>'
+);
+
+const versionUrl = new URL('/version.php', cliServer.serverUrl);
+const response = await fetch(versionUrl);
+const version = await response.text();
+console.log('PHP Version:', version); // Outputs: 8.3.x
+

Error handling

+
import { runCLI } from "@wp-playground/cli";
+
+try {
+  const cliServer = await runCLI({
+    command: 'server',
+    debug: true, // Enable PHP error logging.
+  });
+
+  // Your test code here
+
+} catch (error) {
+  console.error('Server failed to start:', error);
+}
+

Original Playground docs source: https://playground.wordpress.net/guides/programmatic-playground-cli

]]> + + 73 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Providing content for your demo with Playground]]> + https://playground.wordpress.net/guides-providing-content-for-your-demo/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=74 + + One of the things you may want to do to provide a good demo with WordPress Playground is to load default content to better highlight the features of your plugin or theme. This default content may include images or other assets.

+

There are several blueprint steps and strategies you can use to import content (or generate it) in the Playground instance:

+

importWxr

+

With the importWxr step, you can import your own content via a .xml file previously exported from an existing WordPress installation:

+
"steps": [
+	...,
+	{
+		"step": "importWxr",
+		"file": {
+			"resource": "url",
+			"url": "https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/blueprint-content.xml"
+		}
+	},
+	...
+]
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd> &nbsp; <kbd> &nbsp; See <code>blueprint.json</code> &nbsp; </kbd>

+

To include images in your imported content, a good approach is to upload the images to your GitHub repo and search/replace the path for them in the exported .xml file using the URL format: https://raw.githubusercontent.com/{repo}/{branch}/{image_path}.

+
<!-- wp:image {"lightbox":{"enabled":false},"id":4751,"width":"78px","sizeSlug":"full","linkDestination":"none","align":"center","className":"no-border"} -->
+<figure class="wp-block-image aligncenter size-full is-resized no-border">
+	<img src="https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/install-activate-setup-theme-from-gh-repo/images/avatars.png" alt="" class="wp-image-4751" style="width:78px" />
+</figure>
+<!-- /wp:image -->
+

It is recommended to upload your exported .xml file and any referenced assets (such as images) to the same directory as your blueprint.json in your GitHub repository.

+

importWordPressFiles

+

With the importWordPressFiles step, you can import your own top-level WordPress files from a given .zip file into the instance's root folder. For example, if a .zip file contains the wp-content and wp-includes directories, they will replace the corresponding directories in Playground's root folder.

+

This zip file can be created from any Playground instance with the "Download as zip" option in the Playground Options Menu.

+

You can prepare a demo for your WordPress theme or plugin (including images and other assets) in a Playground instance and then export a snapshot of that demo into a .zip file. This file can be imported later using the importWordPressFiles step.

+
{
+	"landingPage": "/",
+	"login": true,
+	"steps": [
+		{
+			"step": "importWordPressFiles",
+			"wordPressFilesZip": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/adamziel/playground-sites/main/playground-for-site-builders/playground.zip"
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

importThemeStarterContent

+

Some themes have starter content that can be published to highlight the features of a theme.

+

With the importThemeStarterContent step you can publish the starter content of any theme even if that theme is not the one activated in the Playground instance.

+

+"steps": [
+    {
+      "step": "installTheme",
+      "themeData": {
+        "resource": "wordpress.org/themes",
+        "slug": "twentytwenty"
+      }
+    },
+    {
+      "step": "installTheme",
+      "themeData": {
+        "resource": "wordpress.org/themes",
+        "slug": "twentytwentyone"
+      },
+      "options": {
+        "activate": true
+      }
+    },
+    {
+      "step": "importThemeStarterContent",
+      "themeSlug": "twentytwenty"
+    }
+  ]
+
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

You can also publish the starter content of a theme when installing it with the installTheme step by setting to true its importStarterContent option:

+
{
+	"steps": [
+		{
+			"step": "installTheme",
+			"themeData": {
+				"resource": "wordpress.org/themes",
+				"slug": "twentytwenty"
+			},
+			"options": {
+				"activate": true,
+				"importStarterContent": true
+			}
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

wp-cli

+

Another way of generating content for your theme or plugin is via the wp-cli step that allows you to run WP-CLI commands such as wp post generate:

+
{
+	"landingPage": "/wp-admin/edit.php",
+	"login": true,
+	"steps": [
+		{
+			"step": "wp-cli",
+			"command": "wp post generate --count=20 --post_type=post --post_date=1999-01-04"
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

You can also use the wp-cli step in combination with the writeFile step to create posts based on existing content and to import images to the Playground instance:

+
{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"landingPage": "/?p=4",
+	"login": true,
+	"steps": [
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/postcontent.md",
+			"data": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/postcontent.md"
+			}
+		},
+		{
+			"step": "wp-cli",
+			"command": "wp post create --post_title='Welcome to Playground' --post_status='published' /wordpress/wp-content/postcontent.md"
+		},
+		{
+			"step": "writeFile",
+			"path": "/wordpress/wp-content/Select-storage-method.png",
+			"data": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/wpcli-post-with-image/Select-storage-method.png"
+			}
+		},
+		{
+			"step": "wp-cli",
+			"command": "wp media import wordpress/wp-content/Select-storage-method.png --post_id=4 --title='Select your storage method' --featured_image"
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>

+

Tip

+

Check the "Use wp-cli to add a post with image" example from the Blueprints Gallery to see the full example showing the connection between the content and the featured image.

+

runPHP

+

With the runPHP step you can run any PHP code you require to insert info into your WordPress installation, for example by using the wp_insert_post function.

+
{
+	"landingPage": "/wp-admin/edit.php",
+	"login": true,
+	"steps": [
+		{
+			"step": "runPHP",
+			"code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Simple post from PHP', 'post_content'  => '<!-- wp:paragraph --><p>This is a simple post inserted with wp_insert_post</p><!-- /wp:paragraph -->', 'post_author'   => 1, 'post_status' => 'publish')); ?>"
+		}
+	]
+}
+

<kbd> &nbsp; Run Blueprint &nbsp; </kbd>);%20?%3E%22}]}>)

+

Original Playground docs source: https://playground.wordpress.net/guides/providing-content-for-your-demo

]]> + + 74 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[WordPress Playground in native iOS apps]]> + https://playground.wordpress.net/guides-wordpress-native-ios-app/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=75 + + How to ship a real WordPress site in a native iOS app via Playground? +

Blocknotes is the first iOS application that ran WordPress natively on iOS devices by leveraging WordPress Playground. Developed by Ella van Durpe, a core committer for WordPress, Blocknotes represents a significant leap in the capabilities of mobile applications by utilizing WebAssembly to run WordPress without the need for a traditional PHP server.

+

This case study explores the features, technical implementation, and potential implications of Blocknotes for the future of mobile and web development.

+

Important! The current version of Blocknotes isn’t running WordPress Playground anymore. Since the initial release, the app was rewritten to only use the WordPress block editor without the rest of WordPress. This case study covers the early versions of Blocknotes that opened an entire world of new possibilities for WordPress.

+

Blocknotes features

+

Blocknotes allows users to create and edit notes using the WordPress block editor. The notes are automatically saved as HTML files to the user’s iCloud Drive and seamlessly synchronized across devices.

+

Technical Implementation

+

Blocknotes operated as a WebView running an HTML page where a WebAssembly version of PHP was running WordPress. That HTML page was packaged as a native iOS via Capacitor. This setup allowed WordPress to function in environments traditionally not supported.

+

In Blocknotes GitHub repository you can review the last Playground-based release. Here are the most important parts:

+ +

Building your own iOS app with WordPress Playground

+

Although Blocknotes proved releasing a WordPress-based iOS app is possible, this is still a highly exploratory area. There are no established workflows, libraries, or knowledge bases.

+

The best documentation we have is the Blocknotes repository. Use it as a reference and a starting point for exploring your new app. Review the key components like the WebAssembly build of PHP, the integration of the WordPress block editor, and how web workers are utilized to run WordPress efficiently. By dissecting these elements, you can gain insights into building your own iOS app with WordPress Playground, pushing the boundaries of what’s possible with mobile web applications.

+

As you navigate this innovative space, share your findings and challenges with the Playground team and the broader WordPress community. Publishing your learnings will not only aid in your development but also contribute to a collective knowledge base, driving forward the future of WordPress on mobile.

+

Potential and the future

+

Blocknotes paves the way for a new generation of applications that are more accessible, flexible, and powerful.

+

Once the app-building workflows mature, we may see an automated pipelines for packaging Playground sites as iOS apps. It would make it extremely easy to run the same codebase on the server, in the browser, and as a mobile app.

+

By working together and sharing our findings, we can push the boundaries of what’s possible with WordPress and mobile app development

+

Original Playground docs source: https://playground.wordpress.net/guides/wordpress-native-ios-app

]]> + + 75 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + + <![CDATA[Introduction]]> + https://playground.wordpress.net/wordpress-playground-docs/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=76 + + WordPress Playground Docs +

Looking for the official Playground website?

+

WordPress Playground website moved to wordpress.org/playground/. The site you're at now hosts the documentation.

+

👋 Hi! Welcome to WordPress Playground documentation.

+

Playground is an online tool to experiment and learn about WordPress. This site (Documentation) is where you will find all the information you need to start using Playground.

+

<p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>

+
  • 👉 Documentation (you're here) – Introduction to WP Playground, starter guides and your entry point to WP Playground Docs.
  • Blueprints – Blueprints are JSON files for setting up your WordPress Playground instance. Learn about their possibilities from the Blueprints docs hub.
  • Developers – WordPress Playground was created as a programmable tool. Discover all the things you can do with it from your code in the Developers docs hub.
  • API Reference – All the APIs exposed by WordPress Playground
+

Navigating this documentation hub

+

This docs hub is focused on starting with WordPress Playground and is divided into the following major sections.

+ + +
  • About Playground: To learn about WordPress Playground, how safe it is, what you can do with and some of its current limitations, visit this section.
+

Discover how you can leverage WordPress Playground to Build, Test, and Launch your products.

+
  • Guides: Explore our comprehensive guides to master new skills, find step-by-step instructions, and unlock valuable insights. Dive in to learn and grow!
+
  • Contributing: WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage. Learn here how to contribute.
+
  • Links and resources: A nice compilation of useful links and resources related to WordPress Playground.
+

First steps

+

Whether you're a developer, a non-technical user, or a contributor, these docs will guide you as you start your learning journey:

+ +

Tip

+

Read Introduction to Playground: running WordPress in the browser blog post in the WordPress Developer Blog for a great introduction to WordPress Playground

+

Take a deep dive

+

If you're a developer or tech user, you may want to check directly the APIs available:

+ +

Get Involved

+

WordPress Playground is an open-source project and welcomes all contributors from code to design, and from documentation to triage. Don't worry, _you don't need to know WebAssembly_ to contribute!

+ +

As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our Code of Conduct.

+

Using Playground with AI assistants

+

WordPress Playground is designed to work with AI coding agents and AI-powered tools. It runs entirely client-side in WebAssembly — no authentication, no backend required, and isolated to the browser with no persistent side effects outside the sandbox — making it a safe, reliable environment for AI-generated demos and prototypes.

+
  • Using Playground with AI agents — Install the wp-playground skill for Claude Code, Cursor, Gemini CLI, GitHub Copilot, and other coding agents. Describe what you need; the agent runs the commands.
  • AI-readable site index — Machine-readable summary of Playground's capabilities, APIs, and docs in llms.txt format.
  • AGENTS.md — Guidance for AI coding agents contributing to this codebase.
+

License

+

WordPress Playground is free software released under the terms of the GNU General Public License version 2 or (at your option) any later version. For a complete license, see LICENSE.md.

+

Original Playground docs source: https://playground.wordpress.net/

]]> + + 76 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Quick Start Guide]]> + https://playground.wordpress.net/quick-start-guide/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=77 + + Start using WordPress Playground in 5 minutes +

WordPress Playground can help you with any of the following:

+

This page will guide you through each of these. Oh, and if you're a visual learner – here's a video:

+

Embedded media: https://video.wordpress.com/v/3UBIXJ9S?autoPlay=false&amp;height=1080&amp;width=1920&amp;fill=true

+

Start a new WordPress site

+

Every time you visit the official demo on playground.wordpress.net, you get a fresh WordPress site.

+

You can then create pages, upload plugins, themes, import your own site, and do most things you would do on a regular WordPress.

+

It's that easy to start!

+

The entire site lives in your browser and is scraped when you close the tab. Want to start over? Just refresh the page!

+

WordPress Playground is private

+

Everything you build stays in your browser and is not sent anywhere. Once you're finished, you can export your site as a zip file. Or just refresh the page and start over!

+

Try a block, a theme, or a plugin

+

You can upload any plugin or theme you want in /wp-admin/.

+

To save a few clicks, you can preinstall plugins or themes from the WordPress plugin directory by adding a plugin or theme parameter to the URL. For example, to install the coblocks plugin, you can use this URL:

+

https://playground.wordpress.net/?plugin=coblocks

+

Or this URL to preinstall the pendant theme:

+

https://playground.wordpress.net/?theme=pendant

+

In case you would like to install multiple themes and plugins, it is possible to repeat the theme or plugin parameters:

+

https://playground.wordpress.net/?theme=pendant&theme=acai

+

You can also mix and match these parameters and even add multiple plugins:

+

https://playground.wordpress.net/?plugin=coblocks&plugin=friends&theme=pendant

+

This is called Query API and you can learn more about it here.

+

Save your site

+

To keep your WordPress Playground site for longer than a single browser session, you can export it as a .zip file.

+
  1. Open the Playground site manager panel:
+

Site Manager

+
  1. Use the "Download as .zip" button in the additional actions menu
+

Export button

+

The exported file contains the complete site you've built. You could host it on any server that supports PHP and SQLite. All WordPress core files, plugins, themes, and everything else you've added to your site are in there.

+

The SQLite database file is also included in the export, you'll find it wp-content/database/.ht.sqlite. Keep in mind that files starting with a dot are hidden by default on most operating systems so you might need to enable the "Show hidden files" option in your file manager.

+

Restore a saved site

+

You can restore the saved site using the "Import from .zip" button in the Playground dashboard panel:

+
  1. Open the Playground dashboard panel:
+

Open Playground Dashboard

+
  1. Use the "Import .zip" button at the end of the "Start a new Playground" section
+

Open Playground Dashboard

+

Use a specific WordPress or PHP version

+

The quickest way to change the version of WordPress or PHP is by using the settings panel on the official demo site:

+

WordPress Playground Settings menu

+

Test your plugin or theme

+

Compatibility testing with so many WordPress and PHP versions was always a pain. WordPress Playground makes this process effortless – use it to your advantage!

+

You can also use the wp and php query parameters to open Playground with the right versions already loaded:

+
  • https://playground.wordpress.net/?wp=6.5
  • https://playground.wordpress.net/?php=8.3
  • https://playground.wordpress.net/?php=8.2&wp=6.2
+

This is called Query API and you can learn more about it here.

+

To learn more about preparing content for demos, see the providing content for your demo guide.

+

Major versions only

+

You can specify major versions like wp=6.2 or php=8.1 and expect the most recent release in that line. You cannot, however, request older minor versions so neither wp=6.1.2 nor php=7.4.9 will work.

+

Import a WXR file

+

You can import a WordPress export file by uploading a WXR file in /wp-admin/.

+

You can also use JSON Blueprints. See getting started with Blueprints to learn more.

+

This is different from the import feature described above. The import feature exports the entire site, including the database. This import feature imports a WXR file into an existing site.

+

Build apps with WordPress Playground

+

WordPress Playground is programmable, which means you can build WordPress apps, setup plugin demos, and even use it as a zero-setup local development environment.

+

To learn more about developing with WordPress Playground, check out the development quick start section.

+

Original Playground docs source: https://playground.wordpress.net/quick-start-guide

]]> + + 77 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Links and Resources]]> + https://playground.wordpress.net/resources/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=78 + + Links and Resources +

Tip

+

There's a set of redirections in place to make it easier the access to some of the tools related to Playground:

+

<ul id="list-resources-redirections"> <li><a href="https://playground.wordpress.net/"><strong>https://playground.wordpress.net/</strong></a> → Playground instance</li> <li><a href="https://playground.wordpress.net/docs">https://playground.wordpress.net<strong>/docs</strong></a> → Playground Docs</li> <li><a href="https://playground.wordpress.net/builder">https://playground.wordpress.net<strong>/builder</strong></a> → Playground Blueprints Builder</li> <li><a href="https://playground.wordpress.net/wordpress">https://playground.wordpress.net<strong>/wordpress</strong></a> → Playground PR viewer for WordPress</li> <li><a href="https://playground.wordpress.net/gutenberg">https://playground.wordpress.net<strong>/gutenberg</strong></a> → Playground PR viewer for Gutenberg</li> <li><a href="https://playground.wordpress.net/proxy">https://playground.wordpress.net<strong>/proxy</strong></a> → Legacy Playground Proxy Service <em>(for Git repositories, prefer <a href="/blueprints/steps/resources#gitdirectoryreference">git:directory</a>)</em></li> </ul>

+

Frequently sought links

+ +

Apps built with WordPress Playground

+ +

Reading materials

+ +

Videos

+ +

Original Playground docs source: https://playground.wordpress.net/resources

]]> + + 78 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + + <![CDATA[Web Instance]]> + https://playground.wordpress.net/web-instance/ + Mon, 11 May 2026 00:00:00 +0000 + + https://playground.wordpress.net/?p=79 + + WordPress Playground web instance +

https://playground.wordpress.net/ lets developers run WordPress in a browser without a server. This environment makes testing plugins, themes, and features quick and easy.

+

Some key features:

+
  • Browser-based: No local server setup required.
  • Instant Setup: Run WordPress with a single click.
  • Testing Environment: Ideal for testing plugins and themes.
+

The Query Params API allows you to directly load specific configurations into a Playground instance. This includes setting a particular WordPress version, theme, or plugin. You can also define more complex setups using blueprints (see examples here).

+

The Playground website includes toolbars that customize your instance and provide quick access to resources and utilities.

+

Playground Toolbar Snapshot

+

Customize Playground

+

On the toolbar, you'll find:

+
  • Playground Settings: A panel for configuring your current instance, like PHP and WordPress versions.
  • Playground Dashboard: This panel lets you manage WordPress Playground instances, save and export them, edit files from your WordPress instance, and create new Blueprints.
  • Playground Launch Panel: The Launch Panel shows all the ways to launch a WordPress Playground instance.
+

Playground Settings

+

snapshot of customize Playground window at Playground instance

+

The Playground Settings Panel includes these Query API options:

+
  • wp: Defines the WordPress version.
  • php: Specifies the PHP version for the instance.
  • language: Sets the WordPress instance language.
  • multisite: Enables WordPress multisite support.
  • networking: Enables network access to the WordPress Plugin Directory and WordPress APIs.
+

Playground Manager

+

Playground settings panel allow users to save export and edit the WordPress directly

+

This panel lets you manage Playground instances and provides access to the following panels:

+
  • Settings: To manage the current Playground's settings
  • File Browser: Built-in IDE for editing files, uploading plugins and themes, and live editing. Playground auto-reloads changes in real time.
  • Blueprint: A Blueprint editor for creating, saving, and running Blueprints in your Playground web instance.
  • Database: Tools for managing the database with Adminer and phpMyAdmin, and downloading as a .sqlite file.
  • Logs: Displays log messages when something goes wrong.
+

Save Playground Button

+

Click "Save" to create an instance and list it in the Playground Launch Panel. The Playground Dashboard also offers export and download options through the Additional actions menu:

+

Additional actions menu

+

Additional actions Menu

+
  • Export Pull Request to GitHub: Export WordPress plugins, themes, and entire wp-content directories as pull requests to any public GitHub repository. Watch a demo of this feature.
  • Download as .zip: Creates a .zip file with the setup of the Playground instance, including any themes or plugins installed. This .zip excludes content and database changes.
+

Blueprint Editor

+

Blueprint editor WordPress Playground

+

The Blueprint editor provides the ability to manage multiple Blueprints and to validate code.

+

Launch Playground Panel

+

Playground Launch Panel

+

This panel shows all the ways to launch WordPress Playground: import .zip files, load from GitHub repositories, and preview PRs from WordPress core and Gutenberg.

+

The Launch Panel also lists more than 40 blueprints from the Blueprint Gallery and your Saved Playgrounds.

+

Caution

+

The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.

+

If you need certain availability, you should host your own WordPress Playground.

+

Original Playground docs source: https://playground.wordpress.net/web-instance

]]> + + 79 + + + + + + + + + 0 + 0 + + + 0 + + + + + + + + + + + + diff --git a/blueprints/personal-rag/plugin/assets/personal-rag.css b/blueprints/personal-rag/plugin/assets/personal-rag.css new file mode 100644 index 00000000..ebd2b707 --- /dev/null +++ b/blueprints/personal-rag/plugin/assets/personal-rag.css @@ -0,0 +1,289 @@ +.personal-rag-wrap { + max-width: 1180px; +} + +.personal-rag-shell { + display: flex; + flex-direction: column; + gap: 18px; +} + +.personal-rag-header { + align-items: flex-start; + display: flex; + gap: 16px; + justify-content: space-between; + padding: 10px 0 4px; +} + +.personal-rag-header h1, +.personal-rag-band h2 { + margin: 0; +} + +.personal-rag-header p { + color: #50575e; + font-size: 14px; + margin: 6px 0 0; + max-width: 620px; +} + +.personal-rag-band { + background: #fff; + border: 1px solid #c3c4c7; + padding: 18px; +} + +.personal-rag-grid { + display: grid; + gap: 14px; + grid-template-columns: repeat(4, minmax(150px, 1fr)); + margin-top: 16px; +} + +.personal-rag-field { + display: flex; + flex-direction: column; + gap: 6px; + min-width: 0; +} + +.personal-rag-field span { + color: #1d2327; + font-weight: 600; +} + +.personal-rag-field input, +#personal-rag-question { + box-sizing: border-box; + width: 100%; +} + +.personal-rag-actions { + align-items: center; + display: flex; + flex-wrap: wrap; + gap: 10px; + margin-top: 16px; +} + +.personal-rag-help { + color: #646970; +} + +.personal-rag-index-head, +.personal-rag-chat-header { + align-items: center; + display: flex; + gap: 16px; + justify-content: space-between; +} + +.personal-rag-status { + display: flex; + flex-wrap: wrap; + gap: 8px; +} + +.personal-rag-status span { + align-items: baseline; + background: #f6f7f7; + border: 1px solid #dcdcde; + display: inline-flex; + gap: 5px; + min-height: 30px; + padding: 4px 9px; +} + +.personal-rag-status strong { + color: #135e96; + font-size: 18px; +} + +.personal-rag-notice { + border-left: 4px solid #72aee6; + padding: 11px 14px; +} + +.personal-rag-notice-info { + background: #f0f6fc; + border-left-color: #72aee6; +} + +.personal-rag-notice-success { + background: #edfaef; + border-left-color: #00a32a; +} + +.personal-rag-notice-warning { + background: #fcf9e8; + border-left-color: #dba617; +} + +.personal-rag-notice-error, +.personal-rag-error { + background: #fcf0f1; + border-left-color: #d63638; +} + +#personal-rag-progress { + height: 12px; + margin-top: 16px; + width: 100%; +} + +#personal-rag-question { + margin-top: 14px; + min-height: 110px; + resize: vertical; +} + +.personal-rag-answer { + border-top: 1px solid #dcdcde; + margin-top: 18px; + padding-top: 16px; +} + +.personal-rag-answer-text { + font-size: 15px; + line-height: 1.6; + max-width: 820px; +} + +.personal-rag-markdown > *:first-child { + margin-top: 0; +} + +.personal-rag-markdown > *:last-child { + margin-bottom: 0; +} + +.personal-rag-markdown h2, +.personal-rag-markdown h3, +.personal-rag-markdown h4 { + color: #1d2327; + font-weight: 600; + line-height: 1.25; + margin: 22px 0 8px; +} + +.personal-rag-markdown h2 { + font-size: 20px; +} + +.personal-rag-markdown h3 { + font-size: 18px; +} + +.personal-rag-markdown h4 { + font-size: 16px; +} + +.personal-rag-markdown p { + margin: 0 0 14px; +} + +.personal-rag-markdown ul, +.personal-rag-markdown ol { + margin: 0 0 16px 22px; + padding: 0; +} + +.personal-rag-markdown li { + margin: 5px 0; + padding-left: 2px; +} + +.personal-rag-markdown strong { + color: #1d2327; + font-weight: 700; +} + +.personal-rag-markdown code { + background: #f6f7f7; + border: 1px solid #dcdcde; + border-radius: 3px; + color: #1d2327; + font-size: 13px; + padding: 1px 4px; +} + +.personal-rag-markdown pre { + background: #101517; + border-radius: 4px; + color: #f6f7f7; + overflow-x: auto; + padding: 14px; + white-space: pre; +} + +.personal-rag-markdown pre code { + background: transparent; + border: 0; + color: inherit; + padding: 0; +} + +.personal-rag-markdown blockquote { + border-left: 4px solid #72aee6; + color: #3c434a; + margin: 0 0 16px; + padding: 1px 0 1px 14px; +} + +.personal-rag-markdown a { + color: #135e96; +} + +.personal-rag-loading { + color: #50575e; +} + +.personal-rag-error { + border-left: 4px solid #d63638; + padding: 10px 12px; +} + +.personal-rag-sources { + margin-top: 18px; +} + +.personal-rag-sources h3 { + font-size: 14px; + margin: 0 0 8px; +} + +.personal-rag-sources ol { + margin: 0; + padding-left: 22px; +} + +.personal-rag-sources li { + margin-bottom: 7px; +} + +.personal-rag-sources span { + color: #646970; + display: inline-block; + font-size: 12px; + margin-left: 8px; +} + +@media (max-width: 960px) { + .personal-rag-grid { + grid-template-columns: repeat(2, minmax(160px, 1fr)); + } +} + +@media (max-width: 640px) { + .personal-rag-header, + .personal-rag-index-head, + .personal-rag-chat-header { + align-items: stretch; + flex-direction: column; + } + + .personal-rag-grid { + grid-template-columns: 1fr; + } +} diff --git a/blueprints/personal-rag/plugin/assets/personal-rag.js b/blueprints/personal-rag/plugin/assets/personal-rag.js new file mode 100644 index 00000000..696e041d --- /dev/null +++ b/blueprints/personal-rag/plugin/assets/personal-rag.js @@ -0,0 +1,701 @@ +(function () { + 'use strict'; + + var config = window.personalRagSettings || {}; + var defaults = config.defaults || {}; + var state = { + status: null, + isBusy: false, + settings: loadSettings(), + }; + + function loadSettings() { + return { + endpoint: localStorage.getItem('personalRag_endpoint') || defaults.endpoint || 'http://localhost:11434', + embeddingModel: localStorage.getItem('personalRag_embeddingModel') || defaults.embeddingModel || 'embeddinggemma', + chatModel: localStorage.getItem('personalRag_chatModel') || defaults.chatModel || 'gemma4:e4b', + topK: parseInt(localStorage.getItem('personalRag_topK') || defaults.topK || '5', 10), + }; + } + + function saveSettings() { + localStorage.setItem('personalRag_endpoint', state.settings.endpoint); + localStorage.setItem('personalRag_embeddingModel', state.settings.embeddingModel); + localStorage.setItem('personalRag_chatModel', state.settings.chatModel); + localStorage.setItem('personalRag_topK', String(state.settings.topK)); + } + + function endpoint() { + return String(state.settings.endpoint || '').replace(/\/+$/, ''); + } + + function rest(path, options) { + options = options || {}; + var headers = options.headers || {}; + headers['X-WP-Nonce'] = config.nonce; + if (options.body && !headers['Content-Type']) { + headers['Content-Type'] = 'application/json'; + } + + return fetch(config.restUrl + path, Object.assign({}, options, { headers: headers })) + .then(function (response) { + return response.json().catch(function () { + return {}; + }).then(function (body) { + if (!response.ok) { + throw new Error(body.message || 'Request failed with status ' + response.status); + } + return body; + }); + }); + } + + function ollamaFetch(path, body, stream) { + return fetch(endpoint() + path, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(body), + }).then(function (response) { + if (!response.ok) { + return response.text().then(function (text) { + throw new Error(text || 'Ollama request failed with status ' + response.status); + }); + } + return stream ? response : response.json(); + }).catch(function (error) { + if (error instanceof TypeError) { + throw new Error('Could not reach Ollama from this browser origin. ' + corsHint()); + } + throw error; + }); + } + + function corsHint() { + return 'Start Ollama with OLLAMA_ORIGINS="' + window.location.origin + '" or add this origin to your existing OLLAMA_ORIGINS value.'; + } + + function escapeHtml(value) { + return String(value || '').replace(/[&<>"']/g, function (char) { + return { + '&': '&', + '<': '<', + '>': '>', + '"': '"', + "'": ''', + }[char]; + }); + } + + function setBusy(isBusy) { + state.isBusy = isBusy; + document.querySelectorAll('#personal-rag-app button, #personal-rag-app input, #personal-rag-app textarea').forEach(function (el) { + if (el.dataset.alwaysEnabled === '1') { + return; + } + el.disabled = isBusy; + }); + } + + function setNotice(message, type) { + var notice = document.getElementById('personal-rag-notice'); + if (!notice) { + return; + } + notice.className = 'personal-rag-notice personal-rag-notice-' + (type || 'info'); + notice.textContent = message || ''; + notice.hidden = !message; + } + + function render() { + var root = document.getElementById('personal-rag-app'); + if (!root) { + return; + } + + root.innerHTML = [ + '
', + '
', + '
', + '

Personal RAG

', + '

Ask questions against your local WordPress posts and pages using Ollama.

', + '
', + '', + '
', + '', + '
', + '

Local Models

', + '
', + fieldHtml('Ollama endpoint', 'endpoint', state.settings.endpoint, 'http://localhost:11434'), + fieldHtml('Embedding model', 'embeddingModel', state.settings.embeddingModel, 'embeddinggemma'), + fieldHtml('Chat model', 'chatModel', state.settings.chatModel, 'gemma4:e4b'), + fieldHtml('Sources', 'topK', state.settings.topK, '5', 'number'), + '
', + '
', + '', + 'Required local models: ollama pull embeddinggemma and ollama pull gemma4:e4b.', + '
', + '
', + config.canManageOptions ? indexHtml() : '', + '
', + '
', + '

Ask Your Site

', + '', + '
', + '', + '
', + '', + '
', + '', + '
', + '
', + ].join(''); + + bindEvents(); + renderStatus(); + } + + function fieldHtml(label, key, value, placeholder, type) { + return ''; + } + + function indexHtml() { + return [ + '
', + '
', + '

Local Index

', + '
', + '
', + '
', + '', + '', + '', + '
', + '', + '
', + ].join(''); + } + + function bindEvents() { + document.getElementById('personal-rag-refresh').addEventListener('click', refreshStatus); + document.getElementById('personal-rag-test').addEventListener('click', testOllama); + document.getElementById('personal-rag-ask').addEventListener('click', askQuestion); + + document.querySelectorAll('[data-setting]').forEach(function (input) { + input.addEventListener('change', function () { + var key = input.dataset.setting; + var value = input.type === 'number' ? parseInt(input.value || '5', 10) : input.value.trim(); + if (key === 'topK') { + value = Math.max(1, Math.min(12, value || 5)); + } + state.settings[key] = value; + saveSettings(); + }); + }); + + if (config.canManageOptions) { + document.getElementById('personal-rag-queue').addEventListener('click', function () { + queueIndex(false); + }); + document.getElementById('personal-rag-index').addEventListener('click', rebuildEmbeddings); + document.getElementById('personal-rag-reset').addEventListener('click', resetIndex); + } + } + + function refreshStatus() { + return rest('/status').then(function (status) { + state.status = status; + renderStatus(); + return status; + }).catch(function (error) { + setNotice(error.message, 'error'); + }); + } + + function renderStatus() { + var statusEl = document.getElementById('personal-rag-status'); + if (!statusEl) { + return; + } + + var status = state.status; + if (!status) { + statusEl.textContent = 'Loading status...'; + return; + } + + statusEl.innerHTML = [ + statHtml('Sources', status.sources), + statHtml('Chunks', status.chunks), + statHtml('Queued', status.queued), + statHtml('Embedded', status.embedded), + ].join(''); + } + + function statHtml(label, value) { + return '' + escapeHtml(value) + '' + escapeHtml(label) + ''; + } + + function testOllama() { + setBusy(true); + setNotice('Testing Ollama...', 'info'); + return fetch(endpoint() + '/api/tags') + .then(function (response) { + if (!response.ok) { + throw new Error('Ollama responded with status ' + response.status); + } + return response.json(); + }) + .then(function (data) { + var models = (data.models || []).map(function (model) { + return model.name; + }); + var missing = [state.settings.embeddingModel, state.settings.chatModel].filter(function (model) { + return models.indexOf(model) === -1 && models.indexOf(model + ':latest') === -1; + }); + if (missing.length) { + setNotice('Ollama is reachable, but these models were not listed: ' + missing.join(', ') + '.', 'warning'); + } else { + setNotice('Ollama is reachable and the configured models are available.', 'success'); + } + }) + .catch(function (error) { + if (error instanceof TypeError) { + setNotice('Could not reach Ollama. ' + corsHint(), 'error'); + } else { + setNotice(error.message, 'error'); + } + }) + .finally(function () { + setBusy(false); + }); + } + + function queueIndex(force) { + setBusy(true); + setNotice(force ? 'Rebuilding local content chunks...' : 'Queueing changed content...', 'info'); + return rest('/index/queue', { + method: 'POST', + body: JSON.stringify({ force: !!force }), + }).then(function (result) { + state.status = result.status; + renderStatus(); + setNotice('Queued ' + result.queued + ' sources. ' + result.unchanged + ' unchanged.', 'success'); + return result; + }).catch(function (error) { + setNotice(error.message, 'error'); + }).finally(function () { + setBusy(false); + }); + } + + function rebuildEmbeddings() { + setBusy(true); + setProgress(0); + setNotice('Preparing local index...', 'info'); + + return rest('/index/queue', { + method: 'POST', + body: JSON.stringify({ force: true }), + }).then(function (result) { + state.status = result.status; + renderStatus(); + return embedQueuedChunks(); + }).catch(function (error) { + setNotice(error.message, 'error'); + }).finally(function () { + setProgress(null); + setBusy(false); + }); + } + + function embedQueuedChunks() { + var initialQueued = state.status ? state.status.queued : 0; + var completed = 0; + + function nextBatch() { + return rest('/index/batch?limit=8').then(function (batch) { + var items = batch.items || []; + state.status = batch.status || state.status; + renderStatus(); + + if (!items.length) { + setNotice('Index is ready. Embedded ' + completed + ' chunks locally.', 'success'); + setProgress(100); + return null; + } + + var inputs = items.map(function (item) { + return 'title: ' + (item.title || 'Untitled') + ' | text: ' + item.text; + }); + + setNotice('Embedding ' + items.length + ' chunks with ' + state.settings.embeddingModel + '...', 'info'); + return embed(inputs).then(function (embeddings) { + var payload = items.map(function (item, index) { + return { + chunkId: item.id, + vector: floatsToBase64(embeddings[index]), + dimensions: embeddings[index].length, + }; + }); + + return rest('/index/embeddings', { + method: 'POST', + body: JSON.stringify({ + model: state.settings.embeddingModel, + items: payload, + }), + }); + }).then(function (result) { + completed += result.saved || items.length; + state.status = result.status; + renderStatus(); + if (initialQueued > 0) { + setProgress(Math.min(99, Math.round((completed / initialQueued) * 100))); + } + return nextBatch(); + }); + }); + } + + return nextBatch(); + } + + function setProgress(value) { + var progress = document.getElementById('personal-rag-progress'); + if (!progress) { + return; + } + if (value === null) { + progress.hidden = true; + progress.value = 0; + return; + } + progress.hidden = false; + progress.value = value; + } + + function embed(input) { + return ollamaFetch('/api/embed', { + model: state.settings.embeddingModel, + input: input, + }).then(function (data) { + var embeddings = normalizeEmbeddings(data); + if (!embeddings.length) { + throw new Error('Ollama returned no embeddings.'); + } + return embeddings; + }); + } + + function normalizeEmbeddings(data) { + if (Array.isArray(data.embeddings)) { + return data.embeddings; + } + if (Array.isArray(data.embedding)) { + return [data.embedding]; + } + if (Array.isArray(data.data)) { + return data.data.map(function (item) { + return item.embedding; + }).filter(Boolean); + } + return []; + } + + function resetIndex() { + if (!window.confirm('Reset the local RAG index? Your posts and pages will not be deleted.')) { + return; + } + + setBusy(true); + setNotice('Resetting index...', 'info'); + return rest('/reset', { + method: 'POST', + body: JSON.stringify({}), + }).then(function (status) { + state.status = status; + renderStatus(); + setNotice('Index reset.', 'success'); + }).catch(function (error) { + setNotice(error.message, 'error'); + }).finally(function () { + setBusy(false); + }); + } + + function askQuestion() { + var questionEl = document.getElementById('personal-rag-question'); + var question = questionEl.value.trim(); + if (!question) { + questionEl.focus(); + return; + } + + var answer = document.getElementById('personal-rag-answer'); + answer.hidden = false; + answer.innerHTML = '
Searching local content...
'; + setBusy(true); + setNotice('', 'info'); + + return embed('task: search result | query: ' + question) + .then(function (embeddings) { + return rest('/search', { + method: 'POST', + body: JSON.stringify({ + vector: floatsToBase64(embeddings[0]), + model: state.settings.embeddingModel, + topK: state.settings.topK, + }), + }); + }) + .then(function (search) { + return streamAnswer(question, search.matches || []); + }) + .catch(function (error) { + answer.innerHTML = '
' + escapeHtml(error.message) + '
'; + }) + .finally(function () { + setBusy(false); + }); + } + + function streamAnswer(question, matches) { + var answer = document.getElementById('personal-rag-answer'); + var messages = buildMessages(question, matches); + var sourceHtml = renderSources(matches); + + answer.innerHTML = '
' + sourceHtml; + var textEl = answer.querySelector('.personal-rag-answer-text'); + var content = ''; + + return ollamaFetch('/api/chat', { + model: state.settings.chatModel, + stream: true, + messages: messages, + options: { + temperature: 0.2, + }, + }, true).then(function (response) { + var reader = response.body.getReader(); + var decoder = new TextDecoder(); + var buffer = ''; + + function pump() { + return reader.read().then(function (result) { + if (result.done) { + textEl.innerHTML = formatAnswer(stripThinking(content)); + return; + } + buffer += decoder.decode(result.value, { stream: true }); + var lines = buffer.split('\n'); + buffer = lines.pop(); + lines.forEach(function (line) { + if (!line.trim()) { + return; + } + try { + var chunk = JSON.parse(line); + if (chunk.message && chunk.message.content) { + content += chunk.message.content; + textEl.innerHTML = formatAnswer(stripThinking(content)); + } + } catch (error) {} + }); + return pump(); + }); + } + + return pump(); + }); + } + + function buildMessages(question, matches) { + var system = [ + 'You are a private RAG assistant running inside WordPress.', + 'Answer only from the provided local WordPress sources.', + 'Use citations like [1], [2] for claims.', + 'If the sources do not contain enough evidence, say that clearly and do not guess.', + ].join(' '); + + var sources = matches.length ? matches.map(function (match, index) { + return '[' + (index + 1) + '] ' + match.title + '\nURL: ' + match.url + '\nText: ' + match.text; + }).join('\n\n') : 'No matching local sources were found.'; + + return [ + { role: 'system', content: system }, + { role: 'user', content: 'Question: ' + question + '\n\nLocal sources:\n' + sources }, + ]; + } + + function renderSources(matches) { + if (!matches.length) { + return '

Sources

No local sources matched this question.

'; + } + + return '

Sources

    ' + matches.map(function (match) { + return '
  1. ' + escapeHtml(match.title) + 'Score ' + escapeHtml(match.score) + '
    2. '; + }).join('') + '
'; + } + + function formatAnswer(value) { + return renderMarkdown(value || 'No answer returned.'); + } + + function renderMarkdown(value) { + var lines = String(value || '').replace(/\r\n?/g, '\n').split('\n'); + var html = []; + var index = 0; + + function isBlank(line) { + return !line || !line.trim(); + } + + function isBlockStart(line) { + return /^#{1,4}\s+/.test(line) || + /^```/.test(line) || + /^\s*[-*+]\s+/.test(line) || + /^\s*\d+[.)]\s+/.test(line) || + /^>\s?/.test(line); + } + + while (index < lines.length) { + var line = lines[index]; + + if (isBlank(line)) { + index++; + continue; + } + + var fence = line.match(/^```\s*([A-Za-z0-9_-]+)?\s*$/); + if (fence) { + var codeLines = []; + index++; + while (index < lines.length && !/^```\s*$/.test(lines[index])) { + codeLines.push(lines[index]); + index++; + } + if (index < lines.length) { + index++; + } + html.push('
' + escapeHtml(codeLines.join('\n')) + '
'); + continue; + } + + var heading = line.match(/^(#{1,4})\s+(.+)$/); + if (heading) { + var level = Math.min(4, heading[1].length + 1); + html.push('' + renderInlineMarkdown(heading[2]) + ''); + index++; + continue; + } + + if (/^>\s?/.test(line)) { + var quoteLines = []; + while (index < lines.length && /^>\s?/.test(lines[index])) { + quoteLines.push(lines[index].replace(/^>\s?/, '')); + index++; + } + html.push('
' + renderMarkdown(quoteLines.join('\n')) + '
'); + continue; + } + + if (/^\s*[-*+]\s+/.test(line)) { + html.push(renderList(lines, index, false)); + while (index < lines.length && /^\s*[-*+]\s+/.test(lines[index])) { + index++; + } + continue; + } + + if (/^\s*\d+[.)]\s+/.test(line)) { + html.push(renderList(lines, index, true)); + while (index < lines.length && /^\s*\d+[.)]\s+/.test(lines[index])) { + index++; + } + continue; + } + + var paragraph = [line.trim()]; + index++; + while (index < lines.length && !isBlank(lines[index]) && !isBlockStart(lines[index])) { + paragraph.push(lines[index].trim()); + index++; + } + html.push('

' + renderInlineMarkdown(paragraph.join(' ')) + '

'); + } + + return html.join(''); + } + + function renderList(lines, start, ordered) { + var items = []; + var pattern = ordered ? /^\s*\d+[.)]\s+(.+)$/ : /^\s*[-*+]\s+(.+)$/; + var index = start; + + while (index < lines.length) { + var match = lines[index].match(pattern); + if (!match) { + break; + } + items.push('
  • ' + renderInlineMarkdown(match[1]) + '
    • '); + index++; + } + + return '<' + (ordered ? 'ol' : 'ul') + '>' + items.join('') + ''; + } + + function renderInlineMarkdown(value) { + var html = escapeHtml(value); + var codeSpans = []; + + html = html.replace(/`([^`]+)`/g, function (match, code) { + var token = '\u0000CODE' + codeSpans.length + '\u0000'; + codeSpans.push('' + code + ''); + return token; + }); + + html = html.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, function (match, label, url) { + return '' + label + ''; + }); + html = html.replace(/\*\*([^*]+)\*\*/g, '$1'); + html = html.replace(/__([^_]+)__/g, '$1'); + html = html.replace(/(^|[\s(])\*([^*\n]+)\*/g, '$1$2'); + html = html.replace(/(^|[\s(])_([^_\n]+)_/g, '$1$2'); + + codeSpans.forEach(function (code, codeIndex) { + html = html.replace('\u0000CODE' + codeIndex + '\u0000', code); + }); + + return html; + } + + function stripThinking(value) { + return String(value || '') + .replace(/<\|channel\>thought[\s\S]*?/g, '') + .replace(/[\s\S]*?<\/think>/g, '') + .trim(); + } + + function floatsToBase64(values) { + if (!Array.isArray(values) && !(values instanceof Float32Array)) { + throw new Error('Invalid embedding vector.'); + } + var floats = values instanceof Float32Array ? values : new Float32Array(values); + var bytes = new Uint8Array(floats.buffer); + var binary = ''; + var chunkSize = 0x8000; + for (var i = 0; i < bytes.length; i += chunkSize) { + var chunk = bytes.subarray(i, i + chunkSize); + binary += String.fromCharCode.apply(null, chunk); + } + return btoa(binary); + } + + document.addEventListener('DOMContentLoaded', function () { + render(); + refreshStatus(); + }); +})(); diff --git a/blueprints/personal-rag/plugin/personal-rag.php b/blueprints/personal-rag/plugin/personal-rag.php new file mode 100644 index 00000000..c8de6621 --- /dev/null +++ b/blueprints/personal-rag/plugin/personal-rag.php @@ -0,0 +1,889 @@ +get_charset_collate(); + + require_once ABSPATH . 'wp-admin/includes/upgrade.php'; + + dbDelta( + "CREATE TABLE {$tables['sources']} ( + id bigint(20) unsigned NOT NULL AUTO_INCREMENT, + source_type varchar(20) NOT NULL DEFAULT 'post', + source_id bigint(20) unsigned NOT NULL, + post_type varchar(20) NOT NULL DEFAULT '', + post_status varchar(20) NOT NULL DEFAULT '', + title text NOT NULL, + url text NOT NULL, + content_hash char(64) NOT NULL DEFAULT '', + updated_at datetime NOT NULL, + indexed_at datetime DEFAULT NULL, + PRIMARY KEY (id), + UNIQUE KEY source_unique (source_type, source_id), + KEY content_hash (content_hash) + ) {$charset};" + ); + + dbDelta( + "CREATE TABLE {$tables['chunks']} ( + id bigint(20) unsigned NOT NULL AUTO_INCREMENT, + source_id bigint(20) unsigned NOT NULL, + chunk_index int(11) NOT NULL DEFAULT 0, + chunk_text longtext NOT NULL, + chunk_hash char(64) NOT NULL DEFAULT '', + token_estimate int(11) NOT NULL DEFAULT 0, + embedding_status varchar(20) NOT NULL DEFAULT 'queued', + created_at datetime NOT NULL, + updated_at datetime NOT NULL, + PRIMARY KEY (id), + UNIQUE KEY source_chunk (source_id, chunk_index), + KEY source_id (source_id), + KEY embedding_status (embedding_status) + ) {$charset};" + ); + + dbDelta( + "CREATE TABLE {$tables['vectors']} ( + id bigint(20) unsigned NOT NULL AUTO_INCREMENT, + chunk_id bigint(20) unsigned NOT NULL, + model varchar(100) NOT NULL DEFAULT '', + dimensions int(11) NOT NULL DEFAULT 0, + vector longtext NOT NULL, + norm double NOT NULL DEFAULT 0, + created_at datetime NOT NULL, + PRIMARY KEY (id), + UNIQUE KEY chunk_id (chunk_id), + KEY model_dimensions (model, dimensions) + ) {$charset};" + ); + + update_option( self::OPTION_VERSION, self::DB_VERSION ); + } + + private static function table_names() { + global $wpdb; + + return array( + 'sources' => $wpdb->prefix . 'personal_rag_sources', + 'chunks' => $wpdb->prefix . 'personal_rag_chunks', + 'vectors' => $wpdb->prefix . 'personal_rag_vectors', + ); + } + + public function add_admin_page() { + add_management_page( + __( 'Personal RAG', 'personal-rag' ), + __( 'Personal RAG', 'personal-rag' ), + 'read', + 'personal-rag', + array( $this, 'render_admin_page' ) + ); + } + + public function enqueue_admin_assets( $hook ) { + if ( 'tools_page_personal-rag' !== $hook ) { + return; + } + + wp_enqueue_style( + 'personal-rag-admin', + plugin_dir_url( __FILE__ ) . 'assets/personal-rag.css', + array(), + self::VERSION + ); + + wp_enqueue_script( + 'personal-rag-admin', + plugin_dir_url( __FILE__ ) . 'assets/personal-rag.js', + array(), + self::VERSION, + true + ); + + wp_localize_script( + 'personal-rag-admin', + 'personalRagSettings', + array( + 'restUrl' => esc_url_raw( rest_url( self::REST_NAMESPACE ) ), + 'nonce' => wp_create_nonce( 'wp_rest' ), + 'canManageOptions' => current_user_can( 'manage_options' ), + 'origin' => esc_url_raw( home_url( '/' ) ), + 'defaults' => array( + 'endpoint' => 'http://localhost:11434', + 'embeddingModel' => 'embeddinggemma', + 'chatModel' => 'gemma4:e4b', + 'topK' => 5, + ), + ) + ); + } + + public function render_admin_page() { + ?> +
    +
    +

    +

    +
    +
    + WP_REST_Server::READABLE, + 'callback' => array( $this, 'rest_status' ), + 'permission_callback' => array( $this, 'permission_read' ), + ) + ); + + register_rest_route( + self::REST_NAMESPACE, + '/index/queue', + array( + 'methods' => WP_REST_Server::CREATABLE, + 'callback' => array( $this, 'rest_queue_index' ), + 'permission_callback' => array( $this, 'permission_manage' ), + ) + ); + + register_rest_route( + self::REST_NAMESPACE, + '/index/batch', + array( + 'methods' => WP_REST_Server::READABLE, + 'callback' => array( $this, 'rest_index_batch' ), + 'permission_callback' => array( $this, 'permission_manage' ), + ) + ); + + register_rest_route( + self::REST_NAMESPACE, + '/index/embeddings', + array( + 'methods' => WP_REST_Server::CREATABLE, + 'callback' => array( $this, 'rest_save_embeddings' ), + 'permission_callback' => array( $this, 'permission_manage' ), + ) + ); + + register_rest_route( + self::REST_NAMESPACE, + '/search', + array( + 'methods' => WP_REST_Server::CREATABLE, + 'callback' => array( $this, 'rest_search' ), + 'permission_callback' => array( $this, 'permission_read' ), + ) + ); + + register_rest_route( + self::REST_NAMESPACE, + '/reset', + array( + 'methods' => WP_REST_Server::CREATABLE, + 'callback' => array( $this, 'rest_reset' ), + 'permission_callback' => array( $this, 'permission_manage' ), + ) + ); + } + + public function permission_read() { + return current_user_can( 'read' ); + } + + public function permission_manage() { + return current_user_can( 'manage_options' ); + } + + public function rest_status() { + return rest_ensure_response( $this->get_status() ); + } + + private function get_status() { + global $wpdb; + + $tables = self::table_names(); + + return array( + 'sources' => (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$tables['sources']}" ), + 'chunks' => (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$tables['chunks']}" ), + 'queued' => (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$tables['chunks']} WHERE embedding_status = 'queued'" ), + 'embedded' => (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$tables['vectors']}" ), + 'dbVersion' => get_option( self::OPTION_VERSION ), + 'indexables' => count( $this->get_indexable_post_ids() ), + ); + } + + public function rest_queue_index( WP_REST_Request $request ) { + $params = $request->get_json_params(); + $force = ! empty( $params['force'] ); + + return rest_ensure_response( $this->queue_all_sources( $force ) ); + } + + public function rest_index_batch( WP_REST_Request $request ) { + global $wpdb; + + $tables = self::table_names(); + $limit = max( 1, min( 50, absint( $request->get_param( 'limit' ) ? $request->get_param( 'limit' ) : 8 ) ) ); + + $rows = $wpdb->get_results( + $wpdb->prepare( + "SELECT c.id, c.chunk_index, c.chunk_text, c.token_estimate, s.title, s.url, s.source_id, s.post_type + FROM {$tables['chunks']} c + INNER JOIN {$tables['sources']} s ON s.id = c.source_id + WHERE c.embedding_status = 'queued' + ORDER BY s.updated_at DESC, c.id ASC + LIMIT %d", + $limit + ), + ARRAY_A + ); + + $items = array(); + foreach ( $rows as $row ) { + $items[] = array( + 'id' => (int) $row['id'], + 'chunkIndex' => (int) $row['chunk_index'], + 'text' => $row['chunk_text'], + 'tokenEstimate' => (int) $row['token_estimate'], + 'title' => $row['title'], + 'url' => $row['url'], + 'sourceId' => (int) $row['source_id'], + 'postType' => $row['post_type'], + ); + } + + return rest_ensure_response( + array( + 'items' => $items, + 'status' => $this->get_status(), + ) + ); + } + + public function rest_save_embeddings( WP_REST_Request $request ) { + global $wpdb; + + $params = $request->get_json_params(); + $items = isset( $params['items'] ) && is_array( $params['items'] ) ? $params['items'] : array(); + $model = sanitize_text_field( isset( $params['model'] ) ? $params['model'] : '' ); + + if ( '' === $model ) { + return new WP_Error( 'personal_rag_missing_model', __( 'Embedding model is required.', 'personal-rag' ), array( 'status' => 400 ) ); + } + + $tables = self::table_names(); + $saved = 0; + $source_ids = array(); + + foreach ( $items as $item ) { + $chunk_id = absint( isset( $item['chunkId'] ) ? $item['chunkId'] : 0 ); + $encoded = isset( $item['vector'] ) ? (string) $item['vector'] : ''; + + if ( ! $chunk_id || '' === $encoded ) { + continue; + } + + $decoded = $this->decode_vector( $encoded ); + if ( is_wp_error( $decoded ) ) { + return $decoded; + } + + $dimension = count( $decoded['values'] ); + if ( isset( $item['dimensions'] ) && absint( $item['dimensions'] ) !== $dimension ) { + return new WP_Error( 'personal_rag_dimension_mismatch', __( 'Embedding dimension mismatch.', 'personal-rag' ), array( 'status' => 400 ) ); + } + + $source_id = (int) $wpdb->get_var( + $wpdb->prepare( + "SELECT source_id FROM {$tables['chunks']} WHERE id = %d", + $chunk_id + ) + ); + + if ( ! $source_id ) { + continue; + } + + $stored = $wpdb->replace( + $tables['vectors'], + array( + 'chunk_id' => $chunk_id, + 'model' => $model, + 'dimensions' => $dimension, + 'vector' => $decoded['encoded'], + 'norm' => $decoded['norm'], + 'created_at' => current_time( 'mysql' ), + ), + array( '%d', '%s', '%d', '%s', '%f', '%s' ) + ); + + if ( false === $stored ) { + return new WP_Error( + 'personal_rag_vector_save_failed', + $wpdb->last_error ? $wpdb->last_error : __( 'Could not save embedding vector.', 'personal-rag' ), + array( 'status' => 500 ) + ); + } + + $wpdb->update( + $tables['chunks'], + array( + 'embedding_status' => 'embedded', + 'updated_at' => current_time( 'mysql' ), + ), + array( 'id' => $chunk_id ), + array( '%s', '%s' ), + array( '%d' ) + ); + + $source_ids[ $source_id ] = true; + $saved++; + } + + $this->mark_completed_sources( array_keys( $source_ids ) ); + + return rest_ensure_response( + array( + 'saved' => $saved, + 'status' => $this->get_status(), + ) + ); + } + + public function rest_search( WP_REST_Request $request ) { + global $wpdb; + + $params = $request->get_json_params(); + $encoded = isset( $params['vector'] ) ? (string) $params['vector'] : ''; + $model = sanitize_text_field( isset( $params['model'] ) ? $params['model'] : '' ); + $top_k = max( 1, min( 12, absint( isset( $params['topK'] ) ? $params['topK'] : 5 ) ) ); + + $query_vector = $this->decode_vector( $encoded ); + if ( is_wp_error( $query_vector ) ) { + return $query_vector; + } + + $tables = self::table_names(); + $dimension = count( $query_vector['values'] ); + + if ( '' !== $model ) { + $rows = $wpdb->get_results( + $wpdb->prepare( + "SELECT v.vector, v.norm, c.id AS chunk_id, c.chunk_index, c.chunk_text, s.title, s.url, s.source_id, s.post_type + FROM {$tables['vectors']} v + INNER JOIN {$tables['chunks']} c ON c.id = v.chunk_id + INNER JOIN {$tables['sources']} s ON s.id = c.source_id + WHERE v.dimensions = %d AND v.model = %s", + $dimension, + $model + ), + ARRAY_A + ); + } else { + $rows = $wpdb->get_results( + $wpdb->prepare( + "SELECT v.vector, v.norm, c.id AS chunk_id, c.chunk_index, c.chunk_text, s.title, s.url, s.source_id, s.post_type + FROM {$tables['vectors']} v + INNER JOIN {$tables['chunks']} c ON c.id = v.chunk_id + INNER JOIN {$tables['sources']} s ON s.id = c.source_id + WHERE v.dimensions = %d", + $dimension + ), + ARRAY_A + ); + } + + $matches = array(); + foreach ( $rows as $row ) { + $vector = $this->stored_vector_to_floats( $row['vector'] ); + if ( count( $vector ) !== $dimension ) { + continue; + } + + $score = $this->cosine_similarity( $query_vector['values'], $query_vector['norm'], $vector, (float) $row['norm'] ); + if ( null === $score ) { + continue; + } + + $matches[] = array( + 'chunkId' => (int) $row['chunk_id'], + 'sourceId' => (int) $row['source_id'], + 'postType' => $row['post_type'], + 'chunkIndex' => (int) $row['chunk_index'], + 'title' => $row['title'], + 'url' => $row['url'], + 'text' => $row['chunk_text'], + 'score' => round( $score, 6 ), + ); + } + + usort( + $matches, + function ( $a, $b ) { + if ( $a['score'] === $b['score'] ) { + return 0; + } + return ( $a['score'] > $b['score'] ) ? -1 : 1; + } + ); + + return rest_ensure_response( + array( + 'matches' => array_slice( $matches, 0, $top_k ), + 'total' => count( $matches ), + ) + ); + } + + public function rest_reset() { + $this->reset_index(); + return rest_ensure_response( $this->get_status() ); + } + + public function handle_save_post( $post_id, $post, $update ) { + if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) ) { + return; + } + + $this->queue_post( $post_id, false ); + } + + public function handle_delete_post( $post_id ) { + $this->delete_source_by_wp_post( $post_id ); + } + + public function handle_untrashed_post( $post_id ) { + $this->queue_post( $post_id, false ); + } + + private function queue_all_sources( $force = false ) { + global $wpdb; + + $results = array( + 'queued' => 0, + 'unchanged' => 0, + 'skipped' => 0, + 'deleted' => 0, + 'status' => array(), + ); + + $post_ids = $this->get_indexable_post_ids(); + $seen = array(); + + foreach ( $post_ids as $post_id ) { + $seen[ $post_id ] = true; + $result = $this->queue_post( $post_id, $force ); + if ( isset( $results[ $result ] ) ) { + $results[ $result ]++; + } + } + + $tables = self::table_names(); + $sources = $wpdb->get_results( "SELECT id, source_id FROM {$tables['sources']} WHERE source_type = 'post'", ARRAY_A ); + foreach ( $sources as $source ) { + if ( ! isset( $seen[ (int) $source['source_id'] ] ) ) { + $this->delete_source_by_id( (int) $source['id'] ); + $results['deleted']++; + } + } + + $results['status'] = $this->get_status(); + return $results; + } + + private function queue_post( $post_id, $force = false ) { + global $wpdb; + + $post = get_post( $post_id ); + if ( ! $post || ! $this->is_indexable_post( $post ) ) { + $this->delete_source_by_wp_post( $post_id ); + return 'skipped'; + } + + $tables = self::table_names(); + $title = get_the_title( $post ); + $content = $this->extract_post_text( $post ); + $source_text = trim( $title . "\n\n" . $content ); + $content_hash = hash( 'sha256', $source_text ); + $permalink = get_permalink( $post ); + $url = $permalink ? $permalink : home_url( '?p=' . $post_id ); + $now = current_time( 'mysql' ); + + $source = $wpdb->get_row( + $wpdb->prepare( + "SELECT * FROM {$tables['sources']} WHERE source_type = %s AND source_id = %d", + 'post', + $post_id + ), + ARRAY_A + ); + + if ( $source && ! $force && hash_equals( $source['content_hash'], $content_hash ) ) { + return 'unchanged'; + } + + $source_data = array( + 'source_type' => 'post', + 'source_id' => $post_id, + 'post_type' => $post->post_type, + 'post_status' => $post->post_status, + 'title' => $title, + 'url' => (string) $url, + 'content_hash' => $content_hash, + 'updated_at' => $now, + 'indexed_at' => null, + ); + + if ( $source ) { + $source_id = (int) $source['id']; + $wpdb->update( + $tables['sources'], + $source_data, + array( 'id' => $source_id ), + array( '%s', '%d', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ), + array( '%d' ) + ); + } else { + $wpdb->insert( + $tables['sources'], + $source_data, + array( '%s', '%d', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ) + ); + $source_id = (int) $wpdb->insert_id; + } + + if ( ! $source_id ) { + return 'skipped'; + } + + $this->delete_chunks_for_source( $source_id ); + + $chunks = $this->chunk_text( $source_text, $title ); + if ( empty( $chunks ) ) { + $this->delete_source_by_id( $source_id ); + return 'skipped'; + } + + foreach ( $chunks as $index => $chunk_text ) { + $wpdb->insert( + $tables['chunks'], + array( + 'source_id' => $source_id, + 'chunk_index' => $index, + 'chunk_text' => $chunk_text, + 'chunk_hash' => hash( 'sha256', $chunk_text ), + 'token_estimate' => $this->estimate_tokens( $chunk_text ), + 'embedding_status' => 'queued', + 'created_at' => $now, + 'updated_at' => $now, + ), + array( '%d', '%d', '%s', '%s', '%d', '%s', '%s', '%s' ) + ); + } + + return 'queued'; + } + + private function get_indexable_post_ids() { + return get_posts( + array( + 'post_type' => array( 'post', 'page' ), + 'post_status' => array( 'publish', 'private' ), + 'posts_per_page' => -1, + 'fields' => 'ids', + 'orderby' => 'modified', + 'order' => 'DESC', + ) + ); + } + + private function is_indexable_post( $post ) { + return in_array( $post->post_type, array( 'post', 'page' ), true ) + && in_array( $post->post_status, array( 'publish', 'private' ), true ); + } + + private function extract_post_text( WP_Post $post ) { + $content = do_blocks( $post->post_content ); + $content = strip_shortcodes( $content ); + $content = wp_strip_all_tags( $content, true ); + $content = html_entity_decode( $content, ENT_QUOTES, get_bloginfo( 'charset' ) ); + $content = preg_replace( '/\s+/', ' ', $content ); + + return trim( $content ); + } + + private function chunk_text( $text, $title ) { + $text = trim( preg_replace( '/\s+/', ' ', $text ) ); + if ( '' === $text ) { + return array(); + } + + $words = preg_split( '/\s+/', $text ); + $target_size = 650; + $overlap = 80; + $chunks = array(); + $count = count( $words ); + + for ( $start = 0; $start < $count; $start += max( 1, $target_size - $overlap ) ) { + $slice = array_slice( $words, $start, $target_size ); + if ( empty( $slice ) ) { + break; + } + + $chunk = implode( ' ', $slice ); + if ( $title && 0 !== strpos( $chunk, $title ) ) { + $chunk = $title . "\n\n" . $chunk; + } + $chunks[] = $chunk; + + if ( $start + $target_size >= $count ) { + break; + } + } + + return $chunks; + } + + private function estimate_tokens( $text ) { + return max( 1, (int) ceil( strlen( $text ) / 4 ) ); + } + + private function delete_source_by_wp_post( $post_id ) { + global $wpdb; + + $tables = self::table_names(); + $id = (int) $wpdb->get_var( + $wpdb->prepare( + "SELECT id FROM {$tables['sources']} WHERE source_type = %s AND source_id = %d", + 'post', + $post_id + ) + ); + + if ( $id ) { + $this->delete_source_by_id( $id ); + } + } + + private function delete_source_by_id( $source_id ) { + global $wpdb; + + $tables = self::table_names(); + $this->delete_chunks_for_source( $source_id ); + $wpdb->delete( $tables['sources'], array( 'id' => $source_id ), array( '%d' ) ); + } + + private function delete_chunks_for_source( $source_id ) { + global $wpdb; + + $tables = self::table_names(); + $wpdb->query( + $wpdb->prepare( + "DELETE FROM {$tables['vectors']} WHERE chunk_id IN (SELECT id FROM {$tables['chunks']} WHERE source_id = %d)", + $source_id + ) + ); + $wpdb->delete( $tables['chunks'], array( 'source_id' => $source_id ), array( '%d' ) ); + } + + private function reset_index() { + global $wpdb; + + $tables = self::table_names(); + $wpdb->query( "DELETE FROM {$tables['vectors']}" ); + $wpdb->query( "DELETE FROM {$tables['chunks']}" ); + $wpdb->query( "DELETE FROM {$tables['sources']}" ); + } + + private function mark_completed_sources( $source_ids ) { + global $wpdb; + + if ( empty( $source_ids ) ) { + return; + } + + $tables = self::table_names(); + foreach ( $source_ids as $source_id ) { + $queued = (int) $wpdb->get_var( + $wpdb->prepare( + "SELECT COUNT(*) FROM {$tables['chunks']} WHERE source_id = %d AND embedding_status = 'queued'", + $source_id + ) + ); + if ( 0 === $queued ) { + $wpdb->update( + $tables['sources'], + array( 'indexed_at' => current_time( 'mysql' ) ), + array( 'id' => $source_id ), + array( '%s' ), + array( '%d' ) + ); + } + } + } + + private function decode_vector( $encoded ) { + $binary = base64_decode( $encoded, true ); + if ( false === $binary || '' === $binary || 0 !== strlen( $binary ) % 4 ) { + return new WP_Error( 'personal_rag_invalid_vector', __( 'Vector payload is invalid.', 'personal-rag' ), array( 'status' => 400 ) ); + } + + $values = $this->binary_to_floats( $binary ); + if ( empty( $values ) ) { + return new WP_Error( 'personal_rag_empty_vector', __( 'Vector payload is empty.', 'personal-rag' ), array( 'status' => 400 ) ); + } + + return array( + 'binary' => $binary, + 'encoded' => base64_encode( $binary ), + 'values' => $values, + 'norm' => $this->vector_norm( $values ), + ); + } + + private function stored_vector_to_floats( $stored ) { + $binary = base64_decode( (string) $stored, true ); + if ( false !== $binary && '' !== $binary && 0 === strlen( $binary ) % 4 ) { + return $this->binary_to_floats( $binary ); + } + + return $this->binary_to_floats( $stored ); + } + + private function binary_to_floats( $binary ) { + $values = unpack( 'f*', $binary ); + return $values ? array_values( $values ) : array(); + } + + private function vector_norm( $values ) { + $sum = 0.0; + foreach ( $values as $value ) { + $sum += (float) $value * (float) $value; + } + return sqrt( $sum ); + } + + private function cosine_similarity( $a, $a_norm, $b, $b_norm ) { + if ( $a_norm <= 0 || $b_norm <= 0 || count( $a ) !== count( $b ) ) { + return null; + } + + $dot = 0.0; + $n = count( $a ); + for ( $i = 0; $i < $n; $i++ ) { + $dot += (float) $a[ $i ] * (float) $b[ $i ]; + } + + return $dot / ( $a_norm * $b_norm ); + } + + public function maybe_register_abilities() { + if ( ! function_exists( 'wp_register_ability_category' ) || ! function_exists( 'wp_register_ability' ) ) { + return; + } + + add_action( 'wp_abilities_api_categories_init', array( $this, 'register_ability_category' ) ); + add_action( 'wp_abilities_api_init', array( $this, 'register_abilities' ) ); + add_filter( 'ai_assistant_ability_domains', array( $this, 'ability_domains' ) ); + } + + public function register_ability_category() { + wp_register_ability_category( + 'personal-rag', + array( + 'label' => __( 'Personal RAG', 'personal-rag' ), + 'description' => __( 'Private local retrieval over WordPress content.', 'personal-rag' ), + ) + ); + } + + public function register_abilities() { + wp_register_ability( + 'personal-rag/get-status', + array( + 'label' => __( 'Get Personal RAG Status', 'personal-rag' ), + 'description' => 'Returns local RAG index counts: source count, chunk count, queued embeddings, and embedded vectors.', + 'category' => 'personal-rag', + 'execute_callback' => array( $this, 'ability_get_status' ), + 'permission_callback' => array( $this, 'permission_read' ), + 'meta' => array( + 'show_in_rest' => true, + 'annotations' => array( + 'readonly' => true, + 'destructive' => false, + 'idempotent' => true, + ), + ), + ) + ); + } + + public function ability_get_status() { + return $this->get_status(); + } + + public function ability_domains( $domains ) { + $domains['personal-rag'] = 'private rag, local search, site knowledge, blog search, embedded WordPress content'; + return $domains; + } +} + +register_activation_hook( __FILE__, array( 'Personal_RAG_Plugin', 'activate' ) ); +Personal_RAG_Plugin::instance(); diff --git a/blueprints/personal-rag/plugin/uninstall.php b/blueprints/personal-rag/plugin/uninstall.php new file mode 100644 index 00000000..cfa355b3 --- /dev/null +++ b/blueprints/personal-rag/plugin/uninstall.php @@ -0,0 +1,24 @@ +prefix . 'personal_rag_vectors', + $wpdb->prefix . 'personal_rag_chunks', + $wpdb->prefix . 'personal_rag_sources', +); + +foreach ( $tables as $table ) { + $wpdb->query( "DROP TABLE IF EXISTS {$table}" ); +} + +delete_option( 'personal_rag_db_version' ); diff --git a/blueprints/personal-rag/screenshot.jpg b/blueprints/personal-rag/screenshot.jpg new file mode 100644 index 00000000..73da3b91 Binary files /dev/null and b/blueprints/personal-rag/screenshot.jpg differ diff --git a/package.json b/package.json index 2e8f971c..b27bde08 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "private": true, "type": "module", "scripts": { + "generate:personal-rag-docs": "node scripts/generate-personal-rag-docs-wxr.js", "shots": "tsx scripts/screenshot-blueprints.ts" }, "devDependencies": { diff --git a/scripts/generate-personal-rag-docs-wxr.js b/scripts/generate-personal-rag-docs-wxr.js new file mode 100644 index 00000000..329a8494 --- /dev/null +++ b/scripts/generate-personal-rag-docs-wxr.js @@ -0,0 +1,778 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const scriptDir = path.dirname(fileURLToPath(import.meta.url)); +const repoRoot = path.resolve(scriptDir, '..'); +const defaultDocsDir = path.resolve( + repoRoot, + '../wordpress-playground/packages/docs/site/docs' +); +const defaultOutFile = path.resolve(repoRoot, 'blueprints/personal-rag/content.xml'); +const sourceRepoRoot = path.resolve(repoRoot, '../wordpress-playground'); +const typedocModelFile = path.join(sourceRepoRoot, 'packages/docs/site/src/model.json'); + +const topLevelCategories = { + main: { label: 'Documentation', slug: 'documentation' }, + developers: { label: 'Developers', slug: 'developers' }, + blueprints: { label: 'Blueprints', slug: 'blueprints' }, +}; + +const fixedDate = '2026-05-11 00:00:00'; +const fixedPubDate = 'Mon, 11 May 2026 00:00:00 +0000'; +const siteUrl = 'https://playground.wordpress.net'; +const rawStaticBase = + 'https://raw.githubusercontent.com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/static'; + +const args = parseArgs(process.argv.slice(2)); +const docsDir = path.resolve(args.get('docs-dir') || defaultDocsDir); +const outFile = path.resolve(args.get('out') || defaultOutFile); + +if (!fs.existsSync(docsDir)) { + throw new Error(`Docs directory does not exist: ${docsDir}`); +} + +const files = findMarkdownFiles(docsDir) + .filter((file) => topLevelCategories[path.relative(docsDir, file).split(path.sep)[0]]) + .sort((a, b) => a.localeCompare(b)); + +const categories = new Map(); +const posts = files.map((file, index) => buildPost(file, index + 1, categories)); +const xml = buildWxr(posts, [...categories.values()]); + +fs.mkdirSync(path.dirname(outFile), { recursive: true }); +fs.writeFileSync(outFile, xml); + +console.log( + `Generated ${posts.length} posts and ${categories.size} categories in ${path.relative( + repoRoot, + outFile + )}` +); + +function parseArgs(values) { + const parsed = new Map(); + for (let index = 0; index < values.length; index++) { + const value = values[index]; + if (!value.startsWith('--')) { + continue; + } + const [rawKey, rawValue] = value.slice(2).split('='); + if (rawValue !== undefined) { + parsed.set(rawKey, rawValue); + } else { + parsed.set(rawKey, values[index + 1]); + index++; + } + } + return parsed; +} + +function findMarkdownFiles(dir) { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + let files = []; + + for (const entry of entries) { + if (entry.name === '_fragments' || entry.name === 'node_modules') { + continue; + } + + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + files = files.concat(findMarkdownFiles(fullPath)); + } else if (entry.isFile() && entry.name.endsWith('.md')) { + files.push(fullPath); + } + } + + return files; +} + +function buildPost(file, postId, categories) { + const relativeFile = path.relative(docsDir, file).replaceAll(path.sep, '/'); + const source = fs.readFileSync(file, 'utf8'); + const { frontmatter, body } = splitFrontmatter(source); + const title = frontmatter.title || firstHeading(body) || titleFromFile(file); + const postName = postSlug(frontmatter.slug, relativeFile); + const sourceUrl = sourceUrlFor(frontmatter.slug, relativeFile); + const categoryChain = ensureCategories(relativeFile, categories); + const content = markdownToHtml(normalizeMdx(body, relativeFile)); + const description = frontmatter.description || ''; + + return { + id: postId, + title, + postName, + link: `${siteUrl}/${postName}/`, + guid: `${siteUrl}/?p=${postId}`, + content: [ + content, + `

    Original Playground docs source: ${escapeHtml(sourceUrl)}

    `, + ].join('\n'), + excerpt: description, + categories: categoryChain, + sourceFile: relativeFile, + sourceSlug: frontmatter.slug || '', + }; +} + +function splitFrontmatter(source) { + if (!source.startsWith('---\n')) { + return { frontmatter: {}, body: source }; + } + + const end = source.indexOf('\n---', 4); + if (end === -1) { + return { frontmatter: {}, body: source }; + } + + const raw = source.slice(4, end); + const body = source.slice(source.indexOf('\n', end + 4) + 1); + const frontmatter = {}; + + for (const line of raw.split('\n')) { + const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/); + if (!match) { + continue; + } + frontmatter[match[1]] = unquote(match[2].trim()); + } + + return { frontmatter, body }; +} + +function unquote(value) { + if ( + (value.startsWith('"') && value.endsWith('"')) || + (value.startsWith("'") && value.endsWith("'")) + ) { + return value.slice(1, -1); + } + return value; +} + +function firstHeading(body) { + const heading = body.match(/^#\s+(.+)$/m); + return heading ? stripMarkdown(heading[1]).trim() : ''; +} + +function titleFromFile(file) { + const base = path.basename(file, '.md'); + return labelFromSegment(base); +} + +function postSlug(frontmatterSlug, relativeFile) { + if (frontmatterSlug && frontmatterSlug !== '/') { + return slugify(frontmatterSlug.replace(/^\/+|\/+$/g, '').replaceAll('/', '-')); + } + if (frontmatterSlug === '/') { + return 'wordpress-playground-docs'; + } + return slugify(relativeFile.replace(/\.md$/, '').replaceAll('/', '-')); +} + +function sourceUrlFor(frontmatterSlug, relativeFile) { + if (frontmatterSlug) { + return `${siteUrl}${frontmatterSlug.startsWith('/') ? frontmatterSlug : `/${frontmatterSlug}`}`; + } + return `${siteUrl}/${relativeFile.replace(/\.md$/, '')}`; +} + +function ensureCategories(relativeFile, categories) { + const segments = relativeFile.split('/'); + const top = segments[0]; + const folderSegments = segments.slice(1, -1); + const chain = []; + const topCategory = topLevelCategories[top]; + + let parentKey = ''; + let currentKey = top; + let currentSlug = topCategory.slug; + ensureCategory(categories, currentKey, { + label: topCategory.label, + slug: currentSlug, + parentSlug: '', + }); + chain.push(categories.get(currentKey)); + + for (const segment of folderSegments) { + parentKey = currentKey; + currentKey = `${currentKey}/${segment}`; + currentSlug = `${categories.get(parentKey).slug}-${slugify(stripNumberPrefix(segment))}`; + ensureCategory(categories, currentKey, { + label: categoryLabelFor(path.join(docsDir, currentKey)), + slug: currentSlug, + parentSlug: categories.get(parentKey).slug, + }); + chain.push(categories.get(currentKey)); + } + + return chain; +} + +function ensureCategory(categories, key, category) { + if (!categories.has(key)) { + categories.set(key, { + id: categories.size + 1, + ...category, + }); + } +} + +function categoryLabelFor(dir) { + const categoryFile = path.join(dir, '_category_.json'); + if (fs.existsSync(categoryFile)) { + try { + const data = JSON.parse(fs.readFileSync(categoryFile, 'utf8')); + if (data.label) { + return data.label; + } + } catch (error) { + throw new Error(`Could not parse ${categoryFile}: ${error.message}`); + } + } + return labelFromSegment(path.basename(dir)); +} + +function normalizeMdx(markdown, relativeFile) { + const lines = markdown.replace(/\r\n?/g, '\n').split('\n'); + const normalized = []; + let inFence = false; + let skipImport = false; + let componentBlock = null; + + for (const line of lines) { + const trimmed = line.trim(); + + if (trimmed.startsWith('```')) { + inFence = !inFence; + normalized.push(line); + continue; + } + + if (inFence) { + normalized.push(line); + continue; + } + + if (skipImport) { + if (trimmed.endsWith(';')) { + skipImport = false; + } + continue; + } + + if (componentBlock) { + componentBlock.lines.push(line); + if (trimmed.endsWith('/>') || trimmed === '') { + flushComponentBlock(componentBlock, normalized, relativeFile); + componentBlock = null; + } + continue; + } + + if (/^import\b/.test(trimmed)) { + if (!trimmed.endsWith(';')) { + skipImport = true; + } + continue; + } + + if (/^<(BlueprintExample|UpdateTopLevelToc|BlueprintStep|TSDocstring|TOCInline)\b/.test(trimmed)) { + if (trimmed.startsWith('')) { + flushComponentBlock(componentBlock, normalized, relativeFile); + componentBlock = null; + } + continue; + } + + if (trimmed === '') { + componentBlock = { name: 'InteractiveDocs', lines: [line] }; + continue; + } + + if (trimmed === '') { + continue; + } + + if (/^$/i.test(trimmed) || /^]*>\s*<\/p>$/i.test(trimmed)) { + continue; + } + + if (/^/i.test(trimmed)) { + continue; + } + + if (/^$/i.test(trimmed) || /^$/i.test(trimmed)) { + normalized.push(`\`${trimmed}\``); + continue; + } + + const admonition = trimmed.match(/^:{3,4}([A-Za-z]+)?(?:\s*(.*))?$/); + if (admonition) { + if (admonition[1]) { + const label = labelFromSegment(admonition[1]); + const title = admonition[2] ? `: ${admonition[2]}` : ''; + normalized.push(`> ${label}${title}`); + } + continue; + } + + normalized.push(line); + } + + return normalized.join('\n').trim(); +} + +function flushComponentBlock(block, output, relativeFile) { + if (block.name === 'BlueprintExample') { + output.push(''); + output.push('```jsx'); + output.push(...block.lines); + output.push('```'); + output.push(''); + return; + } + + if (block.name === 'UpdateTopLevelToc') { + return; + } + + if (block.name === 'InteractiveDocs' && relativeFile === 'blueprints/05-steps.md') { + output.push(''); + output.push(buildBlueprintStepsReference()); + output.push(''); + return; + } + + if (block.name === 'BlueprintStep' || block.name === 'InteractiveDocs') { + output.push(''); + output.push('This section renders interactive reference content in the official documentation.'); + output.push(''); + } +} + +function buildBlueprintStepsReference() { + if (!fs.existsSync(typedocModelFile)) { + return 'The interactive Blueprint step reference is generated from TypeDoc in the official documentation.'; + } + + const model = JSON.parse(fs.readFileSync(typedocModelFile, 'utf8')); + const blueprintsApi = findModule(model, '@wp-playground/blueprints'); + if (!blueprintsApi?.children) { + return 'The interactive Blueprint step reference is generated from TypeDoc in the official documentation.'; + } + + const steps = blueprintsApi.children + .filter((entry) => entry.name?.match(/Step$/)) + .filter( + (entry) => + !['CompiledStep', 'CompiledV1Step', 'GenericStep', 'Step'].includes( + entry.name + ) + ) + .filter((entry) => !entry.flags?.isPrivate) + .sort((a, b) => a.name.localeCompare(b.name)); + + const blocks = ['## Blueprint Step Reference']; + for (const step of steps) { + const props = step.children || step.type?.declaration?.children || []; + const stepId = props.find((prop) => prop.name === 'step')?.type?.value || step.name; + const summary = commentText(step.comment?.summary); + const params = props.filter((prop) => prop.name !== 'step'); + const example = firstExample(step); + + blocks.push(`### ${stepId}`); + if (summary) { + blocks.push(summary); + } + if (params.length) { + blocks.push('Parameters:'); + for (const param of params) { + const optional = param.flags?.isOptional ? ' optional' : ''; + const type = typeLabel(param.type); + const description = commentText(param.comment?.summary); + blocks.push( + `- \`${param.name}\`${type ? ` (${type}${optional})` : optional ? ` (${optional.trim()})` : ''}${description ? `: ${description}` : ''}` + ); + } + } + if (example) { + blocks.push('Example:'); + blocks.push('```json'); + blocks.push(example); + blocks.push('```'); + } + } + + return blocks.join('\n\n'); +} + +function findModule(node, name) { + if (node?.name === name) { + return node; + } + for (const child of node?.children || []) { + const found = findModule(child, name); + if (found) { + return found; + } + } + return null; +} + +function commentText(parts = []) { + return parts + .map((part) => { + if (part.kind === 'code') { + return `\`${part.text.replace(/^`|`$/g, '')}\``; + } + return part.text || ''; + }) + .join('') + .replace(/\s+/g, ' ') + .trim(); +} + +function firstExample(step) { + const tag = step.comment?.blockTags?.find((entry) => entry.tag === '@example'); + const raw = tag?.content?.[0]?.text; + if (!raw) { + return ''; + } + return raw + .trim() + .replace(/^```[a-z]*\s*/i, '') + .replace(/```$/i, '') + .trim() + .replace(/^\s*/i, '') + .replace(/\s*<\/code>$/i, '') + .trim(); +} + +function typeLabel(type) { + if (!type) { + return ''; + } + if (type.name) { + return type.name; + } + if (type.value !== undefined) { + return JSON.stringify(type.value); + } + if (type.type === 'array') { + return `${typeLabel(type.elementType)}[]`; + } + if (type.type === 'union') { + return type.types.map(typeLabel).filter(Boolean).join(' | '); + } + if (type.type === 'reflection') { + return 'object'; + } + if (type.type === 'intrinsic') { + return type.name || ''; + } + return type.type || ''; +} + +function markdownToHtml(markdown) { + const lines = markdown.split('\n'); + const html = []; + let index = 0; + + while (index < lines.length) { + const line = lines[index]; + const trimmed = line.trim(); + + if (!trimmed) { + index++; + continue; + } + + const fence = trimmed.match(/^```\s*([A-Za-z0-9_-]+)?/); + if (fence) { + const code = []; + index++; + while (index < lines.length && !lines[index].trim().startsWith('```')) { + code.push(lines[index]); + index++; + } + if (index < lines.length) { + index++; + } + html.push(`
    ${escapeHtml(code.join('\n'))}
    `); + continue; + } + + const heading = trimmed.match(/^(#{1,6})\s+(.+)$/); + if (heading) { + const level = Math.min(6, heading[1].length); + html.push(`${inlineMarkdown(heading[2])}`); + index++; + continue; + } + + if (/^>\s?/.test(trimmed)) { + const quote = []; + while (index < lines.length && /^>\s?/.test(lines[index].trim())) { + quote.push(lines[index].trim().replace(/^>\s?/, '')); + index++; + } + html.push(`
    ${markdownToHtml(quote.join('\n'))}
    `); + continue; + } + + if (/^\s*[-*+]\s+/.test(line)) { + const items = []; + while (index < lines.length && /^\s*[-*+]\s+/.test(lines[index])) { + items.push(lines[index].replace(/^\s*[-*+]\s+/, '')); + index++; + } + html.push(`
      ${items.map((item) => `
    • ${inlineMarkdown(item)}
      • `).join('')}
    `); + continue; + } + + if (/^\s*\d+[.)]\s+/.test(line)) { + const items = []; + while (index < lines.length && /^\s*\d+[.)]\s+/.test(lines[index])) { + items.push(lines[index].replace(/^\s*\d+[.)]\s+/, '')); + index++; + } + html.push(`
      ${items.map((item) => `
    1. ${inlineMarkdown(item)}
      2. `).join('')}
    `); + continue; + } + + if (/^\|.*\|$/.test(trimmed)) { + const rows = []; + while (index < lines.length && /^\|.*\|$/.test(lines[index].trim())) { + rows.push(lines[index]); + index++; + } + html.push(`
    ${escapeHtml(rows.join('\n'))}
    `); + continue; + } + + const paragraph = [trimmed]; + index++; + while ( + index < lines.length && + lines[index].trim() && + !isBlockStart(lines[index].trim()) + ) { + paragraph.push(lines[index].trim()); + index++; + } + html.push(`

    ${inlineMarkdown(paragraph.join(' '))}

    `); + } + + return html.join('\n'); +} + +function isBlockStart(line) { + return /^#{1,6}\s+/.test(line) || + line.startsWith('```') || + /^>\s?/.test(line) || + /^\s*[-*+]\s+/.test(line) || + /^\s*\d+[.)]\s+/.test(line) || + /^\|.*\|$/.test(line); +} + +function inlineMarkdown(value) { + let html = escapeHtml(value); + html = html.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_match, alt, url) => { + return `
    ${escapeHtml( + alt + )}
    `; + }); + html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => { + return `${text}`; + }); + html = html.replace(/`([^`]+)`/g, '$1'); + html = html.replace(/\*\*([^*]+)\*\*/g, '$1'); + return html; +} + +function buildWxr(posts, categories) { + const categoryXml = categories + .sort((a, b) => a.id - b.id) + .map( + (category) => ` + ${category.id} + + + + ` + ) + .join('\n'); + + const itemXml = posts.map(postToWxrItem).join('\n\n'); + + return ` + + + WordPress Playground Docs for Personal RAG + ${siteUrl} + Starter documentation corpus for the Personal RAG blueprint. + ${fixedPubDate} + en-US + 1.2 + ${siteUrl} + ${siteUrl} + + 1 + + + + + + +${categoryXml} + +${itemXml} + + +`; +} + +function postToWxrItem(post) { + const categories = post.categories + .map( + (category) => + ` ` + ) + .join('\n'); + + return ` + <![CDATA[${safeCdata(post.title)}]]> + ${escapeHtml(post.link)} + ${fixedPubDate} + + ${escapeHtml(post.guid)} + + + + ${post.id} + + + + + + + + + 0 + 0 + + + 0 +${categories} + + + + + + + + + `; +} + +function resolveAssetUrl(url) { + if (/^[a-z]+:\/\//i.test(url)) { + return url; + } + if (url.startsWith('/img/')) { + return `${rawStaticBase}${url}`; + } + return url; +} + +function resolveLinkUrl(url) { + if (/^[a-z]+:\/\//i.test(url) || url.startsWith('#') || url.startsWith('mailto:')) { + return url; + } + if (url.startsWith('/')) { + return `${siteUrl}${url}`; + } + return url; +} + +function labelFromSegment(segment) { + const words = stripNumberPrefix(segment).replace(/[_-]+/g, ' ').trim().split(/\s+/); + return words.map(titleWord).join(' '); +} + +function titleWord(word) { + const lower = word.toLowerCase(); + const acronyms = new Map([ + ['api', 'API'], + ['apis', 'APIs'], + ['cli', 'CLI'], + ['css', 'CSS'], + ['html', 'HTML'], + ['ios', 'iOS'], + ['json', 'JSON'], + ['php', 'PHP'], + ['pr', 'PR'], + ['wasm', 'WASM'], + ['wp', 'WP'], + ['wpcli', 'WP-CLI'], + ['xdebug', 'Xdebug'], + ]); + return acronyms.get(lower) || lower.charAt(0).toUpperCase() + lower.slice(1); +} + +function stripNumberPrefix(value) { + return value.replace(/^\d+-/, ''); +} + +function slugify(value) { + return stripNumberPrefix(String(value)) + .toLowerCase() + .replace(/&/g, ' and ') + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, '') || 'doc'; +} + +function stripMarkdown(value) { + return value + .replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1') + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/[`*_#]/g, ''); +} + +function safeCdata(value) { + return String(value || '').replaceAll(']]>', ']]]]>'); +} + +function escapeHtml(value) { + return String(value || '') + .replaceAll('&', '&') + .replaceAll('<', '<') + .replaceAll('>', '>') + .replaceAll('"', '"') + .replaceAll("'", '''); +} + +function escapeAttr(value) { + return escapeHtml(value); +}