Ir al contenido principal

Hospeda tu propio Playground

Puedes hospedar el Playground en tu propio dominio en lugar de playground.wordpress.net.

Esto es útil para tener control total sobre su contenido y comportamiento, así como eliminar la dependencia de un servidor de terceros. Puede proporcionar una experiencia de usuario más personalizada, por ejemplo: un playground con plugins y temas preinstalados, configuraciones predeterminadas del sitio o contenido de demostración.

Antes de comenzar​

Hospedar Playground por tu cuenta te da control total, pero requiere entender algunos conceptos clave:

Qué esperar​

  • Complejidad de configuración inicial: Construir y desplegar Playground involucra múltiples pasos. Reserva tiempo para solución de problemas durante tu primer despliegue.
  • Alojamiento de archivos estáticos: Playground es principalmente archivos estáticos (HTML, JS, WASM) con requisitos mínimos del lado del servidor.
  • Ejecución basada en navegador: Todo el procesamiento de WordPress ocurre en el navegador del usuario vía WebAssembly—tu servidor solo entrega archivos.

Consideraciones de rendimiento​

Los tiempos de carga dependen de varios factores:

FactorImpactoOptimización
Tamaño del pluginLos plugins grandes (ej. WooCommerce) pueden tardar 30-60 seg en instalarPre-instala plugins en tu build de WordPress
Velocidad de redLos archivos WASM son ~15-30MBUsa CDN con encabezados de caché adecuados
NavegadorChrome/Edge tienen mejor rendimiento; Safari usa mecanismos de respaldoPrueba en diferentes navegadores
DispositivoLos dispositivos móviles cargan más lento que escritorioAdvierte a usuarios móviles sobre tiempos de carga más largos

Compatibilidad con navegadores​

Playground funciona en navegadores modernos, pero con algunas diferencias:

NavegadorEstadoNotas
Chrome/Edge✅ Mejor rendimientoSoporte completo para todas las características
Firefox✅ BuenoRendimiento confiable
Safari✅ BuenoMejoras recientes han mejorado significativamente la confiabilidad
Navegadores móviles⚠️ LimitadoFunciona, pero con mayor uso de memoria, y una conexión 4G puede impactar la experiencia

Nota técnica: Safari usa MessagePorts en lugar de SharedArrayBuffer para respuestas en streaming. Este mecanismo de respaldo funciona de manera confiable pero añade una ligera sobrecarga comparado con Chrome/Edge.

Uso​

Un Playground auto-hospedado puede ser incrustado como un iframe.

<iframe src="https://my-playground.com"></iframe>

O cargado dinámicamente pasando la URL remota al Cliente de Playground.

import { startPlaygroundWeb } from '@wp-playground/client';

const client = await startPlaygroundWeb({
iframe: document.getElementById('wp'),
remoteUrl: `https://my-playground.com/remote.html`,
});

Recursos estáticos​

Compila el sitio web de Playground a partir del código fuente para alojarlo en tu propio dominio. Esto no requiere un artefacto de GitHub Actions. El paquete npm @wp-playground/client conecta tu aplicación a un entorno de ejecución en el navegador ya alojado. El paquete npm @wp-playground/cli ejecuta WordPress localmente con Node.js. Ninguno de los dos instala el sitio web de Playground y su Dock.

El flujo de trabajo Deploy Playground website genera un artefacto temporal para el despliegue público. Este caduca, y la compilación está configurada para mostrar WordPress en wpsandbox.wordpress.net. Para otro dominio, compila a partir del código fuente siguiendo las instrucciones de abajo, aunque el artefacto siga disponible. Ejecutar el flujo de despliegue en un fork sin los secretos de despliegue también hace que se omita la compilación.

Compilar localmente​

Crea un clon superficial del repositorio de Playground o de tu propio fork. El siguiente comando usa el código de desarrollo más reciente de trunk. Para fijar el código fuente de Playground a una versión específica, sustituye trunk por una etiqueta de la página de versiones. La etiqueta no hace que la compilación sea reproducible: la compilación descarga wp-cli.phar de la rama gh-pages del repositorio wp-cli/builds, que puede cambiar entre compilaciones.

git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git

Entra en el directorio wordpress-playground.

cd wordpress-playground

Usa la versión de Node.js indicada en .nvmrc. Los siguientes comandos requieren tener instalado nvm. nvm install instala y activa la versión necesaria de Node.js. Si usas otro gestor de versiones, úsalo para instalar y activar la versión indicada en .nvmrc. Después, instala las dependencias con las versiones fijadas en el archivo de bloqueo:

nvm install
npm ci

Antes de compilar, deja PLAYGROUND_APP_ORIGIN y VITE_WORDPRESS_SITE_URL sin definir para servir la aplicación Playground y sus páginas de WordPress desde el mismo origen. Para una instancia pública que ejecute plugins o Blueprints que no sean de confianza, usa un origen separado para WordPress para reducir la exposición. Esto no protege completamente los archivos guardados ni los identificadores de acceso a directorios nativos. Consulta la guía de despliegue con orígenes separados.

Para compilar con el mismo origen, ejecuta lo siguiente en un shell compatible con POSIX, como Bash o Zsh:

unset PLAYGROUND_APP_ORIGIN VITE_WORDPRESS_SITE_URL
npm run build:website

Este comando ejecuta internamente la tarea nx build:wasm-wordpress-net. Copia los recursos compilados de los paquetes remote y website a una nueva carpeta en la siguiente ruta:

dist/packages/playground/wasm-wordpress-net

Sirve el contenido de esta carpeta como la raíz de tu sitio.

Este proceso compila los archivos que vas a servir. No hace que todas las funciones de Playground sean independientes de los servicios externos. Por ejemplo, las compilaciones de producción usan el proxy CORS del proyecto para las solicitudes que el navegador no puede realizar directamente, a menos que definas CORS_PROXY_URL en el momento de la compilación.

Verificar la compilación local​

Con PHP instalado, ejecuta este comando desde el directorio wordpress-playground para servir los archivos compilados localmente:

php -S localhost:9999 -t dist/packages/playground/wasm-wordpress-net

Abre http://localhost:9999/ en tu navegador. Comprueba que:

  1. Aparecen la página de bienvenida de WordPress y el Dock de Playground.
  2. Al introducir /wp-admin/ en el campo de dirección del Dock, se abre el escritorio de WordPress.
  3. La URL del iframe de WordPress, inspeccionada con las herramientas de desarrollo del navegador, empieza por http://localhost:9999/scope:. La aplicación y WordPress deben usar el mismo protocolo, nombre de host y puerto, en lugar de wpsandbox.wordpress.net.

Detén el servidor con Ctrl+C. Este servidor es solo para la verificación local. Usa HTTPS al desplegar en un dominio público; los service workers pueden funcionar mediante HTTP en direcciones de loopback como 127.0.0.1.

Al informar del resultado de una prueba, incluye la salida de git rev-parse HEAD, node --version y npm --version, junto con la versión del navegador y el comando usado para servir los archivos.

Resumen de archivos incluidos​

Los recursos estáticos incluyen:

  • Archivos de datos y WASM para todas las versiones disponibles de PHP y WordPress
  • remote.html - el núcleo del Playground
  • index.html - el shell, o chrome del navegador
  • Script del Web Worker

Puedes desplegar el contenido de la carpeta a tu servidor usando SSH, como scp o rsync.

Es un sitio estático, excepto por estos aspectos dinámicos.

  • Archivo de directiva del servidor Apache .htaccess del paquete remote

Para que estos funcionen, necesitas un entorno de servidor con Apache y PHP instalados.

Configuración de NGINX​

Como alternativa a Apache, aquí hay un ejemplo de usar NGINX para servir el Playground.

Consulta el archivo fuente

El ejemplo puede estar desactualizado. Por favor revisa el archivo fuente para la última versión.

El archivo combinado de Apache .htaccess se ve así.

AddType application/wasm .wasm

Un equivalente en NGINX.

location ~* .wasm$ {
types {
application/wasm wasm;
}
}

Puede que necesites ajustar lo anterior según las especificaciones del servidor, particularmente cómo invocar PHP para la ruta /plugin-proxy.

El servidor web Caddy no requiere ninguna configuración especial para funcionar.

Personalizar datos empaquetados​

El archivo wp.zip es un paquete de todos los archivos para el sistema de archivos virtual en Playground. Hay un archivo de datos para cada versión disponible de WordPress.

El paquete en packages/playground/wordpress-builds es responsable de construir estos archivos de datos.

Edita el script de construcción en Dockerfile para crear un paquete personalizado que incluya plugins preinstalados o contenido.

Para reconstruir los builds de WordPress después de personalizar el Dockerfile, ejecuta el siguiente comando:

npm run rebuild:wordpress-builds

Para reconstruir el sitio web para incluir los builds personalizados de WordPress, sigue las instrucciones aquí.

Instalar plugins​

Aquí hay un ejemplo de instalación de plugins para el paquete de datos.

Antes de la sección titulada 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;

Puedes descargar plugins desde URLs distintas al directorio de plugins de WordPress, o usar Git para obtenerlos de otro lugar.

También es posible copiar desde una carpeta local. Por ejemplo, antes de RUN:

COPY ./build-assets/*.zip /root/

Luego coloca los archivos zip de plugins en build-assets. En este caso, puede que quieras añadir sus rutas a .gitignore.

Importar contenido​

Aquí hay un ejemplo de importación de contenido.

# === 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

Esto asume que has puesto un archivo de exportación WXR llamado content.xml en la carpeta build-assets. Puedes añadir su ruta a .gitignore.

Lista de verificación para despliegue en producción​

Antes de ir a producción, verifica que tu Playground auto-hospedado cumple estos requisitos:

Configuración del servidor​

  • Tipos MIME: Asegura que los archivos .wasm se sirven con el tipo de contenido application/wasm
  • Encabezados CORS: Si incrustas desde otro origen, configura los encabezados CORS apropiados
  • Caché: Establece tiempos de caché largos para WASM y recursos estáticos (están versionados)
  • Compresión: Habilita gzip/brotli para transferencias de archivos más rápidas
  • HTTPS: Requerido para service workers y algunas características del navegador

Optimización de rendimiento​

  • CDN: Sirve recursos estáticos desde un CDN para entrega global más rápida
  • Plugins pre-instalados: Empaqueta plugins de uso frecuente en tu build de WordPress
  • Blueprints mínimos: Mantén las instalaciones de plugins en tiempo de ejecución al mínimo

Solución de problemas​

Problemas comunes y soluciones​

Playground no carga o muestra pantalla en blanco​

Posibles causas:

  • El servidor no sirve archivos WASM con el tipo MIME correcto
  • El despliegue no incluye archivos requeridos
  • Errores de JavaScript en la consola del navegador

Soluciones:

  1. Revisa la consola del navegador para errores (F12 → pestaña Consola)
  2. Verifica que los archivos .wasm devuelven el tipo de contenido application/wasm
  3. Verifica que desplegaste todos los archivos de construcción

Carga inicial lenta (30+ segundos)​

Posibles causas:

  • Instalación de plugins grandes en tiempo de ejecución
  • Falta configuración de CDN o caché
  • Usuario con conexión de red lenta

Soluciones:

  1. Pre-instala plugins en tu build de WordPress en lugar de instalación en tiempo de ejecución
  2. Configura CDN con encabezados de caché adecuados
  3. Muestra indicadores de carga para establecer expectativas del usuario